LinkedIn
Twitter
Auth0 with Apigee
In this article, I want to present an option of using Auth0 as the OAUTH2 provider for APIs protected by apigee.
Little bit about Auth0…
Auth0 is a service that abstracts how users authenticate to applications.
You can connect any application (written in any language or on any stack) to Auth0 and define its connection, the method used to authenticate the users of that application:
- Custom credentials: username + passwords
- Social network logins: Google, Facebook, Twitter, and any OAuth2, OAuth1 or OpenID Connect provider
- Enterprise directories: LDAP, Google Apps, Office 365, ADFS, AD, SAML-P, WS-Federation, etc.
- Passwordless systems: Touch ID, one time codes on SMS, or email
Auth0 is OIDC compliant, can act as a SAML IDP/SP and a whole lot of other things.
Back to the discussion...
Apigee Edge already has a well-defined OAuth2 policy that has support for the various OAuth2 grant types. You can read more about this here
In addition to that Apigee can support integration with an external OAuth system and relying on the Authentication flow of the external system to provide security for the APIs proxied via Edge. There are 2 ways this can work
- Using an external OAuth system (Auth0) just for User Authentication but creating and persisting an Apigee Access token within Apigee and using that for authorization using the OAUTH v2 policies
- Using an external OAuth system(Auth0) for authentication and using the Access token created by the external system and persisting and recognizing that token within Edge
But, Apigee with its rich ecosystem of policies can enable another flow which makes integrating APIs protected under Apigee with applications using third party OIDC/OAUTH systems very easy. The flow is pretty simple and straightforward.
- An Application using Auth0 as the Authentication system allows user to Authenticate with Auth0 and the access_token is sent to the application
- Application can then use this access_token to access an API proxied via Edge
- Application makes a call to the API and attaches the access_token as an Authorization header to the proxy endpoint
- Apigee policies extract the access_token
- Perform a callout to verify the access_token. Auth0 access_tokens are also JWTs so you can decode and extract claims data once the token is verified
- On verification extract the claims and attach them as headers if the target endpoint requires that data
- Allow the call to go thru to the target
Setup
Auth0 Setup
- Signup at https://auth0.com for an account/tenant
- Create a single page client under Auth0’s management console -> https://manage.auth0.com/#/clients
- Set the allowed callback url as https://jwt.io
- Define an API/Resource Server under Auth0 -> APIs. This step allows Auth0 to recognize the external resource as an audience and will make sure the access_tokens are issued for this audience. When a user authenticates with Auth0 via the application and specifies this audience as part of the process of authentication Auth0 makes sure that the access_token is scoped to this audience so that the application can access the resource on behalf of the user with the scopes that the user consented to while authenticating
- Auth0 domain → tenant.auth0.com
- Client ID of the application created above → auth0_client_id
- Allowed callback url → https://jwt.io
- Audience of the API defined above
I will not go into explaining how to create a connection and users within Auth0 as it is subject to the reader’s setup and they can use any type of connection and user source such as Database, LDAP, federation
With the above setup, you have enough information to login as a user and get an access_token and use that to call the Apigee proxy.
To login the user you can start an authentication transaction with Auth0 constructing a URL as shown below:
https://tenant.auth0.com/authorize?scope=openid profile
&client_id=auth0_client_id
&response_type=token
&redirect_uri=https://jwt.io
&audience=audience
&nonce=random number
&state=random number
On login, you will be redirected to https://jwt.io with an access_token. You can use this access_token to call the Apigee proxy
curl -X GET -H "Authorization: Bearer <access_token>" -H "Cache-Control: no-cache" "http://<your>-test.apigee.net/auth0-hello"
Before you do that though you have to have the correct setup within the Proxy to be able to validate the token presented in the Authorization header. Let’s talk a little bit about that below
Apigee API Proxy Configuration
The API proxy needs to know how to validate/verify the access_token that is attached to the Authorization header. The Java Callout Policy in the attached proxy has configuration to allow for this. (Thanks Dino Chiesa).
The 3 things you will need to change for the Java Callout are:
1. public-key - For RS256 tokens it is the public key of the authorization server
2. iss - Issuer of the token
3. aud - Audience
<?xml version="1.0" encoding="UTF-8"?>
<JavaCallout name="JWT-Parse-OpenIDConnect">
<Properties>
<Property name="algorithm">RS256</Property>
<Property name="jwt">{clientrequest.oauthtoken}</Property>
<!--
public-key used only for algorithm = RS256. This is Auth0 tenant’s public key that you can download from https://tenant.auth0.com/pem or https://tenant.auth0.com/cer and and convert the format if required.
Example: openssl x509 -in cert.cer -pubkey -noout > cert_publickey.pem
You can also configure Apigee Edge to dynamically download RSA public keys from the JWKS (JSON Web Key Set) endpoint exposed by Auth0. https://<tenant>.auth0.com/.well-known/jwks.json and cache it in Apigee Edge using the kid in the JWKS as the key. This step is not enabled in the sample and this article but could be a simple exercise for an Apigee experienced user to download, parse and cache this information in Apigee Edge
-->
<Property name="public-key">-----BEGIN PUBLIC KEY-----
…
-----END PUBLIC KEY-----</Property>
<Property name="iss">https://tenant.auth0.com</Property>
<Property name="aud">audience_of_api_defined_in_auth0</Property>
</Properties>
<ClassName>com.apigee.callout.jwtsigned.JwtParserCallout</ClassName>
<ResourceURL>java://apigee-edge-callout-jwt-signed-1.0.6.jar</ResourceURL>
</JavaCallout>Once you have this configuration done based on your setup you can deploy your proxy and configure your target endpoint and test out the protection of your APIs.
Note: For testing you can just setup a target API that extracts the headers and shows that the required user claims are available within the header
Happy Authenticating and API protecting!☺
Source code for the proxy, policies and callout are available at https://github.com/pushpabrol/auth0-tokens-for-apigee
The Java Callout policy is borrowed from a great set of code libraries made available by @Dino at https://github.com/apigee/iloveapis2015-jwt-jwe-jws/tree/master/jwt_signed
