This article introduces you to using Red Hat 3scale API Management for OpenID Connect (OIDC) integration and compliance. Our goal is to secure an API in 3scale API Management using JSON Web Token (JWT), OIDC, and the Oauth2 Authorization Framework. We will set up the integration using Okta as our third-party OpenID Connect identity provider. An important part of the demonstration is establishing the 3scale API Management gateway's connection with Okta.
Note: This article is not a deep dive into OIDC or Oauth2. I won't cover the details of authentication and authorization flows. Toward the end of the article, you will see how to obtain an access token, which you will need to execute a request against a protected API.
Prerequisites
For demonstration purposes, we will use 3scale API Management and Okta as self-managed services. If you don't have them already, begin by creating free service accounts using 3scale.net and okta.com.Setting up the 3scale API Management OIDC integration
Our first step is to create the simplest possible REST API for integration. We'll use the 3scale API Management platform and an API back end configured to theecho-api
: https://echo-api.3scale.net:443.
As an alternative to this setup, you could try a different back end or a self-managed APIcast instance. This article showcases OIDC authentication. You can adapt different settings to the use case.
Figure 1 shows the OIDC settings in 3scale API Management.
[caption id="" align="aligncenter" width="633"]
Overview of the 3scale API Management Okta integration
So far, we have employed OpenID Connect's.well-known/openid-configuration
endpoint to connect 3scale API Management with Okta. The 3scale API Management gateway determines what it needs from the OpenID Connect issuer URL, which we've just defined. Before going further, let's clarify what we want to accomplish. The diagram in Figure 2 illustrates the step-by-step process for integrating 3scale API Management and Okta.
[caption id="" align="aligncenter" width="640"]
Verify and match the JWT claim
The 3scale API Management gateway secures every request by checking its associated JSON web token for the following characteristics:- Integrity: Is the JWT being tampered with by a malicious user (signature check)?
- Expiration: Is this token expired?
- Issuer: Has it been issued by an authorization server that is known to the 3scale API Management gateway?
- Client ID: Does the token contain a claim matching a client application ID that is known to the 3scale API Management gateway?

appid
.[/caption]
This configuration tells 3scale API Management which claim to match against a client application in its API. For this demonstration, I decided to use appid
rather than the default azp
claim. The Okta authorization server requires a custom claim. I also wanted to avoid the often misunderstood and misused azp claim.
Configuring Okta
Next, let's head over to the Okta admin portal to configure the Okta authorization server and OpenID Connect application. This configuration allows a client application to request a JSON web token on behalf of a user. Recall that we’re using a custom authorization server (named default) to add theappid
JWT claim. The value assigned to this claim will be the Okta client application ID.
Configure the Okta authorization server
As shown in Figure 4, we use the Authorization Servers dialog to add a new claim to the default authorization server. [caption id="" align="aligncenter" width="573"]
Create the OIDC application
While in the Okta admin portal, we'll use the OpenID Connect sign-on method to create a new application. Figure 5 shows the dialog to create a new application integration. [caption id="" align="aligncenter" width="573"]


Create and assign a user to the OIDC application
The last thing we'll do in Okta is to create and assign at least one user to the application, as shown in Figure 8. This allows a valid login to execute using the OpenID Connect authorization flow. [caption id="" align="aligncenter" width="573"]
Configuring the 3scale API Management client application
The API gateway can only authorize API calls from a previously registered client application. So, our last step is to create a 3scale API Management application whose credentials match with the application we've just created in Okta. We only need to match theapplication_id
(also called the client ID), because it is carried by the JWT appid
claim.
As an admin user, navigate to the 3scale API Management docs. You must use 3scale API Management to create the client application and specify a user-defined application_id
. Figure 9 shows the dialog to create the 3scale API Management client application.
[caption id="" align="aligncenter" width="573"]
Testing the application
Now, you might wonder how to ensure that the 3scale API Management application performs correctly. In this case, we can use Postman to execute a request with a valid JWT access token from Okta. The screenshot in Figure 10 shows how to execute the authorization flow in Postman. [caption id="" align="aligncenter" width="573"]

Authorization: Bearer
HTTP request header:
$ curl "https://some-example-api.xyz.gw.apicast.io" -H "Authorization: Bearer jwt-access-token-base64"Postman can take care of the rest. The
echo-api
will respond when the authentication is successful.