Chapter 2. OpenID Connect integration
3scale integrates with the 3rd-party Identity Providers (IdP) for authenticating the API requests using the OpenID Connect specification. OpenID Connect is built on top of OAuth 2.0 that complements the OAuth 2.0 Authorization framework with an authentication mechanism. When OpenID Connect authentication option is used, the API requests are authenticated using the access tokens in the JSON Web Token (JWT) format (RFC 7519).
The integration consists of the following two parts:
Red Hat 3scale API Management fully supports both integration points with Red Hat Single Sign-On (RH-SSO) acting as the OpenID Provider. See the supported version of RH-SSO on the Supported Configurations page. APIcast integration is also tested with ForgeRock.
In both cases, you can configure the integration by specifying the OpenID Connect Issuer field in the APIcast Configuration on the Integration page of the service using OpenID Connect authentication option. For instructions, see Section 2.3, “Configure Red Hat Single Sign-On integration”.
2.1. JWT verification and parsing by APIcast
The API requests to the service using the OpenID Connect authentication mode should provide the access token in the JWT format, issued by the OpenID Provider, in the
Authorization header using
Bearer schema. The header should look like the following example:
Authorization: Bearer <JWK>
Authorization: Bearer: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2lkcC5leGFtcGxlLmNvbSIsInN1YiI6ImFiYzEyMyIsIm5iZiI6MTUzNzg5MjQ5NCwiZXhwIjoxNTM3ODk2MDk0LCJpYXQiOjE1Mzc4OTI0OTQsImp0aSI6ImlkMTIzNDU2IiwidHlwIjoiQmVhcmVyIn0.LM2PSmQ0k8mR7eDS_Z8iRdGta-Ea-pJRrf4C6bAiKz-Nzhxpm7fF7oV3BOipFmimwkQ_-mw3kN--oOc3vU1RE4FTCQGbzO1SAWHOZqG5ZUx5ugaASY-hUHIohy6PC7dQl0e2NlAeqqg4MuZtEwrpESJW-VnGdljrAS0HsXzd6nENM0Z_ofo4ZdTKvIKsk2KrdyVBOcjgVjYongtppR0cw30FwnpqfeCkuATeINN5OKHXOibRA24pQyIF1s81nnmxLnjnVbu24SFE34aMGRXYzs4icMI8sK65eKxbvwV3PIG3mM0C4ilZPO26doP0YrLfVwFcqEirmENUAcHXz7NuvA
The JWT token contains a signature that the token’s receiver can verify and ensure that the token was signed by a known issuer and that its content has not been changed. 3scale supports RSA signature based on the public/private key pair. Here, the issuer signs the JWT token using a private key. APIcast verifies this token using a public key.
On each request, APIcast does the following:
- Verifies the JWT token using the public key.
Validates the claims
Verifies that the issuer specified in the claim
iss(Issuer) is the same as the one configured in the OpenID Connect Issuer field.
Extracts the value of the
audclaim and uses it as the Client ID (that identifies the application in 3scale) to authorize the call through the Service Management API.
If any of the JWT validation or the authorization checks fail, APIcast returns an "Authenication failed" error. Otherwise, APIcast proxies the request to the API backend. The
Authorization header remains in the request, so the API backend can also use the JWT token to check the user and client identity.
2.2. Client credentials synchronization by Zync
Using the Zync component, 3scale syncronizes the client (application) credentials between 3scale and the Red Hat Single Sign-On server configured through the OpenID Connect Issuer setting. Whenever a new application is created, updated, or deleted for a service configured to use OpenID Connect, Zync receives the corresponding event and communicates the change to the Red Hat Single Sign-On instance using RH-SSO API. The Section 2.3, “Configure Red Hat Single Sign-On integration” section provides the steps required to ensure that Zync has the correct credentials to use the RH-SSO API.
2.3. Configure Red Hat Single Sign-On integration
2.3.1. Configure Red Hat Single Sign-On
To configure Red Hat Single Sign-On, take the following steps:
Create a realm (
Create a client:
- Specify a client ID.
In the Client Protocol field, select
To configure the client permissions, set the following values:
Access Type to
Standard Flow Enabled to
Direct Access Grants Enabled to
Service Accounts Enabled to
- Access Type to
Set the service account roles for the client:
- Navigate to the Service Account Roles tab of the client.
In the Client Roles dropdown list, click
In the Available Roles pane, select the
manage-clientslist item and assign the role by clicking Add selected >>.
Note the client credentials:
Make a note of the client ID (
Navigate to the Credentials tab of the client and make a note of the Secret field (
- Make a note of the client ID (
Add a user to the realm:
- Click the Users menu on the left side of the window.
- Click Add user.
Type the username, set the Email Verified switch to
ON, and click Save.
On the Credentials tab, set the password. Enter the password in both the fields, set the Temporary switch to
OFFto avoid the password reset at the next login, and click Reset Password.
- When the pop-up window displays, click Change password.
2.3.2. Configure 3scale
After you have created and configured the client in Red Hat Single Sign-On, you must configure 3scale to work with Red Hat Single Sign-On.
To configure 3scale, take the following steps:
Enable OpenID Connect.
- Select the service on which you want to enable the OpenID Connect authentication, navigate to [your_API_name] > Integration > Configuration.
- Select edit integration settings.
Authenticationdeployment options, select
- Click Update Service to save the settings.
Edit the APIcast Configuration:
- Navigate to [your_API_name] > Integration > Configuration.
- Select edit APIcast configuration.
Under the Authentication Settings heading, in the OpenID Connect Issuer field, enter the previously noted client credentials with the URL of your Red Hat Single Sign-On server (located at host
- To save the configuration, click Update the Staging Environment.
2.4. OAuth 2.0 supported flows
The API clients must get access tokens from the OpenID Connect issuer configured in 3scale, using any OAuth 2.0 flow that is supported by this OpenID provider. In case of Red Hat Signle Sign-On, the following flows are supported (the terms used in RH-SSO clients are specified in parenthesis):
- Authorization Code (Standard Flow)
- Resource Owner Password Credentials (Direct Access Grants)
- Implicit (Implicit Flow)
- Client Credentials (Service Accounts)
When the clients (applications) are created in 3scale, the corresponding clients created by Zync in Red Hat Single Sign-On have only the Authorization Code flow enabled. This flow is recommended as the most secure and suitable for most cases. However, it is possible to enable other flows either through the RH-SSO admin console or using the Client Registration API.
The client gets the access token using the authorization request, or the token request, or both. The URLs that receive these requests can be discovered using the
.well-known/openid-configuration endpoint of the OpenID provider, in the
"token_endpoint", accordingly. Example:
2.5. Test the integration
To test the integration, you must perform the steps listed in the following sections.
2.5.1. Test the client synchronization
To test the client synchronization, take the following steps:
- Create an application for the service where you configured the OpenID Connect integration.
- Note the client ID and the client Secret of the generated application.
- Verify that the client with the same client ID and client secret is now present in the configured Red Hat Single Sign-On realm.
- Update the Redirect URL of the application in the 3scale admin portal.
- Verify that the Valid Redirect URIs field of the client in Red Hat Single Sign-On has been updated accordingly.
2.6. Example of the integration
The service "API" in 3scale is configured to use the OpenID Connect authentication. The Public Base URL on the service "API" is configured to be
https://api.example.com and the Private Base URL is configured to be
The OpenID Connect Issuer field is set to
https://zync:firstname.lastname@example.org/auth/realms/myrealm in the API integration and the client
zync in the realm myrealm has the correct Service Account roles.
In 3scale, there is an application having the
myclientid client ID,
myclientsecret client secret, and a
https://myapp.example.com Redirect URL. In Red Hat Single Sign-On, in the myrealm realm, there also exists a client having a
myclientid client ID,
myclientsecret secret, and
https://myapp.example.com Valid Redirect URIs. Standard Flow is enabled on this client. There is a user configured in the myrealm realm having the myuser username and mypassword password.
The flow is as follows:
Using the endpoint
https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/auth, the application sends an Authorization request to RH-SSO. The application should provide the client ID
myclientsecretand Redirect URL
https://myapp.example.comwith the request.
- RH-SSO shows the login window, where the user must provide the user’s credentials: Username myuser and password mypassword.
- Depending on the configuration, and if it is the first time that the user is authenticating in this specific application, the consent window displays.
After the user is authenticated, the applciation sends a Token request to RH-SSO using the endpoint
https://idp.example.com/auth/realms/myrealm/protocol/openid-connect/tokenand providing the client ID
myclientid, client secret
myclientsecretand Redirect URL
RH-SSO returns a JSON with an "access_token" field
The application sends an API request to
https://api.example.comwith the header
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…xBArNhqF-A.
The application should receive a successful response from