This article is part of a series about OAuth 2.0 Authorization on OCI API Gateway:

1. Complete Guide: How to configure OAuth 2.0 with JWT & IDCS on OCI API Gateway
2. Limit access to your APIs with OCI API Gateway using OAuth 2.0 Scopes
3. Protect OIC REST APIs with OCI API Gateway and OAuth2 – 1/2

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:

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.

1. Use the same URL for the API call – in this case, is the /hello stock response we created earlier
2. Configure OAuth 2.0 Authorization as follows:
   1. Give a token name – it can be anything
   2. Select Grant Type as Client Credentials
   3. Use IDCS URL for Access Token URL as follows: https://<your-idcs-hostname>/oauth2/v1/token
      1. This is IDCS’s URL for OAuth 2.0 token generation
   4. Use the Client ID from the client application created earlier
   5. Use the Client Secret from the same client application created earlier
      1. You can find those again by going in the client application, over in the Configuration tab, and General Information
   6. Use the Scope from the client application – should be the format <primary-audience>/<scope-name>
      1. You can find the scope in the client application, over in the Configuration tab as well, but in the Client Configuration section
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.

Image rights