Complete Guide: How to configure OAuth 2.0 with JWT & IDCS on OCI API Gateway — #mytechretreat
OCI API Gateway is a managed service that gives you the ability to deploy, manage, secure, control, and monitor your whole API ecosystem in one place. This will also give you one single point of entry for all clients.
This article will focus on how to secure your APIs with OAuth2.0 using JSON Web Tokens (JWTs) and Identity Cloud Service (IDCS) as identity provider on the API Gateway layer for your backends. If you need extended help with the deployment of the service, check this OCI API Gateway QuickStart.
This will be a long one — so bear with me. There will be a suite of articles after this where we talk about access segregation with claim values and specific use-cases like Oracle Integration Cloud APIs.
Create a new API Gateway
This step is optional — you can use your existing API Gateway.
If you don’t already have an API Gateway, let’s just create one really quick from the Developer Services Menu –> Gateways
I am creating a Public Gateway in a public subnet where I have already opened port 443 from the associated Security List.
Create a Stock Response Deployment
This step is optional — you can use your own deployments.
I am creating a new deployment under /v1 without authentication, for the moment, where I am using a stock response as a route:
Now let’s test the deployment using Postman — for now, no authenticate was configured:
We get back the stock response configured in the route “/hello”.
The URL is composed of : https://<your-gateway-endpoint>/<your-deployment-path-prefix>/<your-route-path>
Prerequisites for using JWTs
When enabling authentication and authorization using JWTs, you must consider the following:
- You have to use an identity provider (Auth0, Oracle IDCS, etc) that can issue JWTs for users
- You can set up custom claims in authorization policies in your identity provider
- Remote vs Static keys — In API Gateway, you’ll have a choice between using Remote JWKS (JSON Web Key Set) or Static Key in the authentication policy for the validation of JWTs:
- Remote JWKS will be retrieving the public verification keys from the identity provider at runtime
- Static Keys will be using public verification keys already issued by an identity provider and API Gateway will be able to verify JWTs locally without having to contact the identity provider
In this example, we’ll be using Static Keys and IDCS as an identity provider
Obtain JWKS Static Key from IDCS
Permission required: IDCS Administrator rights
Before creating the Authentication Policy in API Gateway, we should obtain the JWKS Static Key from our Identity Provider — IDCS.
From the IDCS Console — You can connect to it via OCI from the Identity & Security Menu -> Federation -> OracleIdentityCloudService and now click on the Oracle Identity Cloud Service Console link:
In IDCS, go to Settings -> Default Settings and Toggle ON the Access Signing Certificate option and DO NOT FORGET TO SAVE:
Retrieve the JWKS from the following URI: https://<YOUR-IDCS-URL>/admin/v1/SigningCert/jwk
Replace <YOUR-IDCS-URL> with your tenancy IDCS domain path which should look like this: https://idcs-1234xxx.identity.oraclecloud.com/admin/v1/SigningCert/jwk
When accessing the URL above, you’ll get a JSON file with the key as a response — save the response somewhere as we’ll need it later.
Once you’ve retrieved the JWKS Key, go back to IDCS and Toggle OFF the Access Signing Certificate option to prevent unauthorized access.
Create the Authentication Policy
Step 1 — Edit the existing API Deployment
Edit the deployment we created earlier or the one to which you want to add the policy:
Step 2 — Add an Authentication Policy
In the API Request Policies section from the Deployment — Click the Add button next to Authentication:
Step 3 — Configure Authentication Policy
Configure the policy as follows:
Authentication Type — Select JWT
Authentication Token — Select Header
Header Name — Authorization
Authentication Scheme — Bearer
Enable Anonymous Access — Leave unchecked
Allowed Issuers — https://identity.oraclecloud.com/
Allowed Audiences — Specify a value that is allowed in the audience (aud) claim of a JWT to identify the intended recipient of the token. For this example, we’ll be setting the audience with the API gateway’s hostname
Type — Select Static Keys
Key ID — SIGNING_KEY — this is from the JWKS taken from IDCS, it is the value of the kid parameter
JSON WEB Key — Example: { “kid”: “SIGNING_KEY”, “kty”: “RSA”, “use”: “sig”, “alg”: “RS256”, “n”: “abc123xxx”, “e”: “AQAB” }. All the values for these parameters you’ll find them in the JWKS saved from IDCS. Replace the values with the ones from your IDCS key
For more info on what each field represents — please check the documentation.
In the end, you should Apply the changes and click on Next
Create IDCS applications to generate and validate JWTs
We need to create two confidential applications in IDCS to generate and then to validate the tokens:
- Resource Server — this application will be used to validate the tokens
- Client Application — this application will be used by a consumer to obtain the tokens
The relationship between the Resource Server and Client Application can be 1:many. As a best practice, we would create separate client applications for each consumer.
Step 1 — Create the Resource Server Application
The Resource Server Application will be used for JWT validation.
From the IDCS dashboard — go to Applications and click on Add and select Confidential Application
Give the Resource Server application a Name and click on Next
Skip the Client configuration as this will be our Resource Server Application
Configure this application as a resource server
Set the Primary Audience with the same value as set in the deployment’s authentication settings. In this case, we’ve set it to be our API Gateway hostname.
Add a scope for OAuth. For this example, it can be whatever you want — we’ll just use it for token generation.
We’ll go into more details on how to use the scopes for access segregation in a following article. For now, let’s just create one scope to use for all requests.
Click on Next
Skip the Web Tier Policy — click on Next and then on Finish
Once finished, Activate the application
Step 2 — Create the Client Application
The Client Application will be used by the API consumers to obtain JWTs.
To reiterate — as a best practice, we would create separate client applications for each API consumer.
From the IDCS dashboard — go to Applications and click on Add and select Confidential Application
Give the Client Application a Name and click on Next
Configure this application as a client and check Client Credentials and JWT Assertion
Add the scopes defined in our Resource Server app
Select the Resource Server application created before
Select the scope and click Add
The scope should now be added with the format: <primary-audience>/<scope-name>
Click on Next and skip the rest of the screens
A Client ID and Client Secret for this client application will be generated for you at the end of the process.
You can note these down — but you’ll be able to get them later as well, from the Configuration tab
Do not forget to ACTIVATE the application
Test the OAuth 2.0 authorization
We’ll be using Postman to test our OAuth 2.0 authentication/authorization with OCI API Gateway.
- Use the same URL for the API call — in this case, is the /hello stock response we created earlier
- Configure OAuth 2.0 Authorization as follows:
— Give a token name — it can be anything
— Select Grant Type as Client Credentials
— Use IDCS URL for Access Token URL as follows: https://<your-idcs-hostname>/oauth2/v1/token
— Use the Client ID from the client application created earlier
— Use the Client Secret from the same client application created earlier
— Use the Scope from the client application — should be the format <primary-audience>/<scope-name>
3. Generate New Access Token
4. Use the token and Send a new request
5. We are successfully authenticated
Conclusions
This was a simple example of how to use an OAuth2.0 Authentication Policy on OCI API Gateway with JWT and IDCS as an identity provider.
In the next articles, we’ll go into details about how to use OAuth2.0 scopes for access segregation on your back-end APIs and a specific use-case for Oracle Integration Cloud. Come back soon for them.
Originally published at https://mytechretreat.com on May 23, 2021.
