OAuth 2.0 Authorization Code Flow - Save 3rd-Party Authorization Code and 3rd-Party Access Token in Apigee Edge
This repo demonstrates the following:
- How to save an external authorization code generated by Auth0 in Apigee Edge
- How to save an external access token (opaque or JWT) from Auth0 in Apigee Edge
Why is this important? Our clients are integrating with OpenID connect providers like Okta, Oracle IDCS, Ping, Auth0, etc. and they want to understand how to integrate Apigee Edge with these providers. Specifically, the best practices around handling JWTs generated by these providers. This repo demonstrates how to save Auth0's authorization codes and access tokens in Apigee Edge. You can follow this pattern for the other providers as well.
You may need to install acurl.
You must export the following environment variables:
export ae_password=apigeepassword
export ae_username=apigeeusername
export ae_org=apigeeorg
You should:
- create an account in Auth0
- create an Auth0 client to obtain a client ID and secret.
- create an Auth0 API
A good starting point is to read this community article. It provides instructions to setup a new Auth0 client to obtain a client ID and secret.
- The redirect URI that you should enter is listed below.
https://org-env.apigee.net/oauth_auth0/redirectif you are going to save the Auth0 authorization code in Apigee Edge.https://org-env.apigee.net/oauth_auth0_store_jwt/redirectif you are going to save the Auth0 authorization code and access token in Apigee Edge.
- Create a user in Auth0. This is the user that you will use to login during the redirect step.
You should update the following entries in the auth0-oauth/edge.json and auth-oauth-save-token/edge.json files. Just use a find and replace to update all the values shown below.
yourdomain.auth0.comhttps://yourdomain.auth0.comhttps://org-env.apigee.net/
You don't have to review these links, since I list all the commands to deploy the proxy. But if you are interested in learning more about the config and deploy plugins, then you should read them.
This proxy demonstrates how to enable external authorization with Auth0. It saves the authorization code generated by Auth0 in Edge so that the proxy can subsequently validate that authorization code on the /token request.
The auth0-oauth proxy does not save the JWT as an external access token. Once the client has the JWT, then they should include that as an Authorization: Bearer header on subsequent requests. All of your other proxies should validate the JWT, with the public certificate, expiry and custom claims. Make sure to include the JWT/JWE/JWS Java Callout written by Dino, which validates JWTs.
There is only one issue with this approach, Edge will not have the developer details, so you won't know who called your API proxy. There are two approaches to solve this problem:
- Store the JWT as an external access token within Apigee Edge. Then use the Verify Access Token policy to validate the token exists in Apigee Edge and that the token has not expired.
- Additionally, you can also validate the JWT with the Java Callout after the Verify Access Token policy.
- Validate and decode the JWT, extract the client_id, use the Verify API Key to validate it. This will ensure that the developer details are assigned to the request and your analytics will be updated accordingly.
/authorize- validates the client ID redirect uri and forwards the request to Auth0 to generate the authorization code./redirect- called by Auth0 and extracts the Auth0 authorization code and saves it in Apigee Edge./token- validates the client ID and redirect URI and forward the request to Auth0 to generate the access token (opaque or JWT).
Follow the steps below to deploy shared flows and the proxy, and create the developer, product and app in Apigee Edge.
The shared flows must be deployed first.
cd auth0-ProxyDefaultFaultRule
mvn install -PtestSharedFlow -Dusername=$ae_username -Dpassword=$ae_password -Dorg=$ae_org -Dauthtype=oauth
cd ../auth0-ProxyFaultRules
mvn install -PtestSharedFlow -Dusername=$ae_username -Dpassword=$ae_password -Dorg=$ae_org -Dauthtype=oauth
This will deploy the auth0-auth proxy and create the Apigee developer named [email protected], a product named auth0-product and an app named auth0-app.
If you are running this for the first time then you must deploy the proxy first, before you run the config step. Then run the config step below.
cd ../auth0-auth
mvn install -Ptest -Dusername=$ae_username -Dpassword=$ae_password \
-Dorg=$ae_org -Dauthtype=oauth
If the proxy is deployed, then you can run this step. It will redeploy the proxy and create the necessary configuration.
mvn install -Ptest -Dusername=$ae_username -Dpassword=$ae_password \
-Dorg=$ae_org -Dauthtype=oauth -Dapigee.config.options=create
Once you create the client in Auth0 and create the Apigee product and app, then you have to add the client ID and secret into Apigee Edge. Use the following API calls to add the credentials to Apigee Edge.
Use the developer [email protected] and the app named auth0-app.
Associate the consumer key and secret with an Apigee product
The payload for this request is shown below.
{ "apiProducts": ["auth0-product"] }
After you have your Auth0 configured and you have deployed the proxy you should copy the following command into your browser. Be sure to update the auth0_api_identifier, {org}, {env} and {clientID}.
If you don't include the audience parameter then you will not receive a JWT as an access token.
https://{org}-{env}.apigee.net/oauth_auth0/authorize?audience={auth0_api_identifier}&{client_id}=clientID&response_type=code&redirect_uri=https://callback.io&scope=openid
- You will be redirected to the Auth0 login screen.
- login with the Auth0 user that you created.
- The authorization code will be downloaded to your local machine.
- Copy the authorization code into the request below. Be sure to update
orgenvclientIDsecret
curl -X POST \
https://{org}-{env}.apigee.net/oauth_auth0/token \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'client_id={clientID}&code={authCode}&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fcallback.io&client_secret={secret}'
Now you have an Auth0 JWT that was proxied through Apigee Edge.
Please note the following:
- The JWT is not stored in Apigee Edge.
- You should validate the JWT with Dino's JWT Java callout.
- You will miss out on some analytics because the Verify API key/Validate Access Token policy is not included in the proxy, so you won't know who the developer is.
- However, the JWT includes the client ID (or should include it), so you could extract that from the JWT and then include a VerifyAPIKey policy on the preflow, then Apigee will know who the developer is and will populate all the analytics data associated with the developer.
This section describes the proxies that are used to save an external access token (an opaque token) within Apigee Edge so that you can still obtain the developer analytics. It similar to the previous example, but it saves the external authorization code and the access token.
It consists of two proxies:
- auth0-oauth-save-token - this proxy saves the external access token with Edge.
- auth0-test-proxy - this proxy contains the VerifyAccessToken policy to validate the external access token.
This proxy saves the Auth0 access token as an external access token within Apigee Edge.
-
Create a new client in Auth0 and make sure to set your Auth0 client's redirect URI to
https://org-env.apigee.net/oauth_auth0_save_token/redirect -
Deploy the proxy If you are running this for the first time then you must deploy the proxy first, before you run the config step. Then run the config step below.
cd ../auth0-oauth-save-token
mvn install -Ptest -Dusername=$ae_username -Dpassword=$ae_password \
-Dorg=$ae_org -Dauthtype=oauth
If the proxy is deployed, then you can run this step. It will redeploy the proxy and create the necessary configuration.
mvn install -Ptest -Dusername=$ae_username -Dpassword=$ae_password \
-Dorg=$ae_org -Dauthtype=oauth -Dapigee.config.options=create
- Create the client ID and secret in Edge Once you create the client in Auth0 and create the Apigee product and app, then you have to add the client ID and secret into Apigee Edge. Use the following API calls to add the credentials to Apigee Edge.
Use the developer [email protected] and the app named auth0-save-token-app.
Associate the consumer key and secret with an Apigee product
The payload for this request is shown below.
{ "apiProducts": ["auth0-save-token-product"] }
- Start Apigee Edge trace and test the deployment
Copy the following command into your browser. Be sure to update the
audience,{org},{env}and{clientID}parameters.
If you include the audience parameter then Auth0 will return a JWT as the access token.
https://{org}-{env}.apigee.net/oauth_auth0_save_token/authorize?audience={auth0_api_identifier}&client_id={client_id}&response_type=code&redirect_uri=https://callback.io&scope=openid
Note: If you do not include the audience parameter in the /authorize request, then Auth0 will return an opaque access token.
https://{org}-{env}.apigee.net/oauth_auth0_save_token/authorize?client_id={client_id}&response_type=code&redirect_uri=https://callback.io&scope=openid
- Your browser should be redirected to the Auth0 login page. Login to Auth0 with the username and password you created earlier.
- Save the authorization code and enter it into the request below.
Request for an access token
curl -X POST \
https://{org}-{env}.apigee.net/oauth_auth0_save_token/token \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'client_id={clientID}&code={authCode}&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fcallback.io&client_secret={secret}'
Response:
{"access_token":"K9Qtbh"
,"expires_in":86400
,"id_token":"eyJ0eXAi....4z6QXOiFZ56VdourjlO2kPr_pxgyHgdw"
,"token_type":"Bearer"}
- Validate the token.
- Use the management API to confirm token is saved in Apigee Edge.
- OR deploy the proxy below validate the token is stored in Edge.
This proxy have the ValidateAccessToken policy included to validate the external access token, which should be included in the Authorization header (Bearer token).
Please note the following:
- Edge checks that the token exists in its internal token store and that it has not expired.
- Deploy the proxy
cd ../auth0-test-proxy
mvn install -Ptest -Dusername=$ae_username -Dpassword=$ae_password \
-Dorg=$ae_org -Dauthtype=oauth
- Test the deployment You can validate that the token that you received above is a valid token in Apigee Edge.
curl https://org-env.apigee.net/auth0_test_proxy \
-H 'Authorization: Bearer K9QYwZtbh'
You should see the following response:
HTTP/1.1 200 OK
< Date: Wed, 21 Jun 2017 17:07:31 GMT
< Content-Type: text/plain
< Content-Length: 60
< Connection: keep-alive
< Server: Apigee Router
<
* Curl_http_done: called premature == 0
* Connection #0 to host org-env.apigee.net left intact
Your token is valid!
To find your Auth0 API Identifier follow the steps below.
- Click the APIs section and then select your API from the list.
-
Click the Settings link.
-
Scroll down and you should see the identifier.
- Create a new repo that demonstrates how to save the Auth0 access token in Apigee Edge. - COMPLETE
- Create a proxy to demo how to extract the client ID from the JWT and then use the Validate API Key policy to populate all the default analytics - COMPLETE see apigee-jwt-signed-strategies.