Software AG Products 10.5 | Using API Gateway | API Gateway Administration | Security Configuration | OAuth, JWT, and OpenID Configuration | OpenID Authentication Use case and Workflow
 
OpenID Authentication Use case and Workflow
OpenID Connect is an open standard and decentralized authentication protocol that extends on the OAuth 2.0 authorization framework. It combines the capability of Open ID in verifying the client's identity and OAuth's capability of accessing the client's resources.
In case of OpenID support in API Gateway, you can use the OpenID authentication protocol to identify and authorize a client application to access the protected resources in one of the following ways (these are explained in detail in the Astacus section.):
*Use just the access tokens (that is OAuth token) to invoke the protected resources.
*Use the ID token (that gives information about the user) to invoke the protected resources in one of the following ways:
*Present the ID token to exchange it for an access token and use the access token to access the protected resources.
*Use the ID token directly to access the protected resources.
API Gateway does not act as a OpenID Connect server but can validate the tokens issued by other OpenID Connect servers.
The following internal API is used for getting an access token for an ID token.
exchangeIDToken
Method: POST
URL: http://host:port/gateway/security/exchangeIDToken
Payload
{
"gatewayScopes": ["OktaTenant1:inventory"],
"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
"expiry": 3000
}
For details on scopes, see Mapping OAuth or OpenID Scopes.
Note:
The getOpenIDtoken call is deprecated and is no more available from the API Gateway release 10.3 onwards.
Use case 1: OpenID authentication using OpenID Connect Provider
This describes the high level workflow for using the OpenID authentication protocol to identify and authorize a client application to access the protected resources.
1. Configure a Provider if you are using the Dynamic client registration. Else you can proceed to step 2.
For a complete procedure on configuring a provider, see Adding a Provider.
2. Configure an external authorization server.
Ensure you configure the external authorization server with the introspection URL and OAuth scopes. For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.
3. Map the scopes.
For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.
4. Enforce the Identify and authorize application policy on the API.
Ensure to select OpenID Connect or JWT as options. For details of the Identify and authorize application policy see, Identify and Authorize Application.
5. Associate an application with the API.
You can create a new application or use an existing one. Ensure that the application associated contains the strategy for OpenID authentication. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. For a complete procedure on creating an application with a strategy, see Creating an Application.
6. Activate the API.
User on invoking the API uses the access token or the ID token provided by the provider to access the protected resource.
7. User can access the protected resources in one of the following ways:
*The user presents the access token to API Gateway and on validation accesses the protected resource.
*The user presents the ID token to API Gateway to exchange it for an access token (if the user has configured the OpenID Connect option in step 4). The client then presents the access token to API Gateway and on validation accesses the protected resource.
The following internal API is used for getting an access token for an ID token.
exchangeIDToken
Method: POST
URL: http://host:port/gateway/security/exchangeIDToken
Payload
{
"gatewayScopes": ["OktaTenant1:inventory"],
"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
"expiry": 3000
}
*The user presents the ID token as a JWT directly to API Gateway (if the user has configured the JWT option in step 4), and on validation accesses the protected resource.
OpenID Authorization Workflow
The OpenID Connect support in API Gateway provides two different ways for a client to access a protected resource depending on whether the provider has provided an access token or an ID token. The workflow diagram depicts both these cases. The first 2 steps are same in both the cases, the arrows in blue depict the flow where an access token is used to access the protected resource, and the arrows in orange depict the flow where an ID token is used to access the protected resource.
OpenID authorization workflow using the OpenID Connect Provider
The flow of authorization requests and responses between the end user, client application, OpenID Connect provider, and resource server is as depicted in the following figure. The client application makes an OpenID call to the OpenID Connect provider and receives an access token or an ID token in the response. It uses these tokens to access the protected resources.
OpenID authorization workflow using the access token provided by the Open ID Connect Provider
1. The client makes an OpenID call to the OpenID connect Provider.
2. The OpenID Connect Provider provides an access token to the client.
3. The client application presents the access token received from the OpenID Connect Provider to send HTTP requests to API Gateway.
4. API Gateway then performs the following:
a. Identifies the application using the clientId.
b. Validates the token locally or remotely if it is not possible locally.
c. Checks if the requested resource is part of the scopes in the token.
d. Checks the audience.
API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.
OpenID authorization workflow using the ID token provided by the Open ID Connect Provider
1. The client makes an OpenID call to the OpenID Connect Provider.
2. The OpenID Connect Provider provides an ID token to the client.
3. The client application presents the ID token received from the OpenID Connect Provider to API Gateway.
4. API Gateway validates the ID token and returns an access token to the client application.
The following internal API is used for getting an access token for an ID token.
exchangeIDToken
Method: POST
URL: http://host:port/gateway/security/exchangeIDToken
Payload
{
"gatewayScopes": ["OktaTenant1:inventory"],
"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
"expiry": 3000
}
For details on mapping scopes, see Mapping OAuth or OpenID Scopes.
5. The client then uses this access token to send HTTP requests to API Gateway.
6. API Gateway then performs the following:
a. Identifies the application using the clientId.
b. Validates the token locally or remotely if it is not possible locally.
c. Checks if the requested resource is part of the scopes in the token.
d. Checks the audience.
API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.
Note:
The user can present the ID token directly as a JWT to access the protected resources in case the ID token is provided on configuring the JWT property in the Identify and authorize application policy enforced on the API.