Chapter 12. OpenID Connect integration
3scale integrates with third-party Identity Providers (IdP) for authenticating the API requests using the OpenID Connect specification, with these features:
- OpenID Connect is built on top of OAuth 2.0 that complements the OAuth 2.0 Authorization framework with an authentication mechanism.
- With the OpenID Connect authentication option, 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 Configure Red Hat Single Sign-On integration.
12.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>
Example:
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.
APIcast uses OpenID Connect Discovery for getting the JSON Web Keys (JWK) that can be used for verifying the JWT signature.
On each request, APIcast does the following: . Verifies the JWT token using the public key. . Validates the claims nbf
and exp
. . 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 azp
or aud
claim 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.
12.2. Client credentials synchronization by zync-que
3scale synchronizes the client (application) credentials between 3scale and the RH-SSO server when you are using the zync-que
component. Configure this through the OpenID Connect Issuer setting.
When you create, update, or delete a service configured to use OpenID Connect, zync-que
receives the corresponding event and communicate the change to the RH-SSO instance using RH-SSO API.
The Configure Red Hat Single Sign-On integration section provides the steps required to ensure that zync-que
has the correct credentials to use the RH-SSO API.
12.3. Configure Red Hat Single Sign-On integration
The following procedure guides you through configuring zync-que
to use custom CA certificates.
12.3.1. Configuring zync-que
to use custom CA certificates
Prerequisites
You must be able to serve RH-SSO over
https
and make sure it is reachable byzync-que
. To test this type the following:curl https://rhsso-fqdn
-
3scale 2.2 and above support custom CA certificates for RH-SSO with the
SSL_CERT_FILE
environment variable. This variable points to the local path of the certificates bundle.
-
Some versions of OpenSSL accept
-showcerts
instead of--showcerts
. Modify the following command accordingly to the version you are using. -
The command in step 1 of the below procedure mentions
<rhsso_fqdn>
. The Fully Qualified Domain Name (FQDN) is the human-readable domain name, for example,host.example.com
.
Procedure
Run the following command to get a proper certificate chain:
echo -n | openssl s_client -connect <rhsso_fqdn>:<rhsso_port> -servername <rhsso_fqdn> --showcerts | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > customCA.pem
Procedure
Validate the new certificate with the following cURL command. The expected response is a JSON configuration of the realm. If validation fails it is an indicator that your certificate may not be correct.
curl -v https://<secure-sso-host>/auth/realms/master --cacert customCA.pem
Add the certificate bundle to the Zync pod:
Gather the existing content of the
/etc/pki/tls/cert.pem
file on the Zync pod. Run:oc exec <zync-que-pod-id> cat /etc/pki/tls/cert.pem > zync.pem
Append the contents of the custom CA certificate file to
zync.pem
:cat customCA.pem >> zync.pem
Attach the new file to the Zync pod as ConfigMap:
oc create configmap zync-ca-bundle --from-file=./zync.pem
oc set volume dc/zync-que --add --name=zync-ca-bundle --mount-path /etc/pki/tls/zync/zync.pem --sub-path zync.pem --source='{"configMap":{"name":"zync-ca-bundle","items":[{"key":"zync.pem","path":"zync.pem"}]}}'
After deployment, verify that the certificate is attached and the content is correct:
oc exec <zync-pod-id> cat /etc/pki/tls/zync/zync.pem
Configure the
SSL_CERT_FILE
environment variable on Zync to point to the new CA certificate bundle:oc set env dc/zync-que SSL_CERT_FILE=/etc/pki/tls/zync/zync.pem
12.3.2. Configure Red Hat Single Sign-On
To configure RH-SSO, take the following steps:
-
Create a realm (
<realm_name>
). Create a client:
- Specify a client ID.
-
In the Client Protocol field, select
openid-connect
.
To configure the client permissions, set the following values:
-
Access Type to
confidential
. -
Standard Flow Enabled to
OFF
. -
Direct Access Grants Enabled to
OFF
. -
Service Accounts Enabled to
ON
.
-
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
realm-management
. -
In the Available Roles pane, select the
manage-clients
list item and assign the role by clicking Add selected >>.
Note the client credentials:
-
Make a note of the client ID (
<client_id>
). -
Navigate to the Credentials tab of the client and make a note of the Secret field (
<client_secret>
).
-
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
OFF
to avoid the password reset at the next login, and click Reset Password. - When the pop-up window displays, click Change password.
12.3.3. Configure 3scale
After you have created and configured the client in RH-SSO, you must configure 3scale to work with RH-SSO.
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.
-
Under the
Authentication
deployment options, selectOpenID Connect
. - 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 RH-SSO server (located at host
<rhsso_host>
and port<rhsso_port>
).https://<client_id>:<client_secret>@<rhsso_host>:<rhsso_port>/auth/realms/<realm_name>
- To save the configuration, click Update the Staging Environment.
12.4. Configure HTTP integration with third-party Identity Providers
You can configure HTTP integration of OpenID Connect (OIDC) to facilitate syncing credentials with third-party identity providers (IdPs). This means that it is possible to integrate different IdPs other than RH-SSO, by implementing the OpenAPI specifications we provide.
12.4.1. Prerequisites
- * Enable OIDC as authentication mode, as indicated in Configure 3scale
- Zync
- Integration with Zync for client synchronization between chosen IdP and 3scale
12.4.2. Procedure
To configure HTTP integration of OIDC with third-party identity providers, follow these steps in the Admin Portal:
- Navigate to [Your_API_name] > Integration > edit APIcast configuration > Authentication Settings.
- Under OpenID Connect Issuer Type, select REST API.
- In OpenID Connect Issuer. specify the location of your OpenID Provider.
- To save your changes, click Update the Staging Environment.
12.4.3. Zync REST API example
This example project implements Zync REST API protocol to synchronize OAuth2.0 clients. When a 3scale application is created, updated or deleted Zync tries to replicate that change to http://example.com/api
.
12.4.3.1. Prerequisites
3scale must be configured to use:
- OIDC as the authentication mode
-
REST API
as a OpenID Connect Issuer Type -
http://id:secret@example.com/api
as OpenID Connect Issuer
12.4.3.2. Creating, updating and deleting clients
Zync makes the following requests to create, update or delete clients: * Create and update PUT /clients/:client_id
* Delete DELETE /clients/:client_id
All endpoints must reply with a 2xx
status code. Otherwise, 3scale retries the request.
12.4.3.3. Payload
The request payload in case of create and update is application/json
:
{ "client_id": "ee305610", "client_secret": "ac0e42db426b4377096c6590e2b06aed", "client_name": "oidc-app", "redirect_uris": ["http://example.com"], "grant_types": ["client_credentials", "password"] }
The request to delete a client has no payload.
12.4.3.4. Using OAuth2 authentication
Zync sends GET requests to the /.well-known/openid-configuration
endpoint and expects an application/json
response. The response payload should contain the following:
{ "token_endpoint": "http://idp.example.com/auth/realm/token" }
Zync uses token_endpoint to exchange the client_id
and client_secret
provided in the OpenID Connect Issuer address for an access token using the OAuth2 protocol. If the API responds with an unsuccessful response, Zync falls back to HTTP Basic/Digest authentication using the provided credentials.
12.5. OAuth 2.0 supported flows
The API clients must get access tokens from the OpenID Connect (OIDC) issuer configured in 3scale, using any OAuth 2.0 flow that is supported by this OpenID provider. In case of RH-SSO, 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 Flow)
- Implicit (Implicit Flow)
- Client Credentials (Service Accounts Flow)
When clients under OpenID Connect (OIDC) are created in 3scale, the corresponding clients created by Zync in Red Hat Single Sign-On (RH SSO) 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.
12.5.1. How OAuth 2.0 supported flows work
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 "authorization_endpoint"
and "token_endpoint"
, accordingly. Example: https://<RHSSO_HOST>:<RHSSO_PORT>/auth/realms/<REALM_NAME>/.well-known/openid-configuration
.
12.5.2. Configuring OAuth 2.0 supported flows
You can configure allowed OAuth 2.0 flows for the 3scale API in the Admin Portal. When you create a new application, the basic integration is finished, including the OpenId Connect (OIDC) configuration.
To configure OAuth 2.0 supported flows, perform these steps:
- Navigate to the Authentication Settings section: [Your_API_name] > Integration > edit integration settings > Authentication
- Choose OpenId Connect.
The corresponding flows are enabled on the client on RH SSO side. You can view them by navigating through [Your_API_name] > Integration > Edit APIcast configuration > Authentication Settings
-
standardFlowEnabled
(Authorization Code flow) [selected by default] -
implicitFlowEnabled
(Implicit flow) -
serviceAccountsEnabled
(Service Accounts Flow) -
directAccessGrantsEnabled
(Direct Access Grant Flow)
-
- Choose one or multiple flows.
- To save your changes, click Update the Staging Environment.
12.6. Test the integration
To test the integration, you must perform the steps listed in the following sections.
12.6.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 RH-SSO realm.
- Update the Redirect URL of the application in the 3scale Admin Portal. Redirect URLs should be as specific as possible.
- Verify that the Valid Redirect URIs field of the client in RH-SSO has been updated accordingly.
12.6.2. Test the API authorization flow
To test the APT authorization flow, take the following steps:
- Get the access token from the RH-SSO server using an OAuth 2.0 flow that is enabled on the corresponding RH-SSO client.
-
Use the value of the
access_token
retrieved from RH-SSO in theAuthorization
header as follows:Authorization: Bearer <access_token>
If the token is correct and the corresponding application in 3scale is authorized, APIcast gateway returns a response from the 3scale backend.
12.7. 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 https://internal-api.example.com
.
The OpenID Connect Issuer field is set to https://zync:41dbb98b-e4e9-4a89-84a3-91d1d19c4207@idp.example.com/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 RH-SSO, in the myrealm realm, there also exists a client with these values:
-
Client ID:
myclientid
-
Secret:
myclientsecret
-
Valid Redirect URIs:
https://myapp.example.com
For this client, Standard Flow is enabled. 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. Within the request, the application provides these parameters:myclientid
client ID, andhttps://myapp.example.com
Redirect URL. - 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/token
and providing the client IDmyclientid
, client secretmyclientsecret
and Redirect URLhttps://myapp.example.com
. -
RH-SSO returns a JSON with an "access_token" field
eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…xBArNhqF-A
. -
The application sends an API request to
https://api.example.com
with the headerAuthorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk…xBArNhqF-A
. -
The application should receive a successful response from
https://internal-api.example.com
.