Open Id Authentication use case and workflow

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. 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 .
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 webMethods API Gateway and on validation accesses the protected resource.
   • The user presents the ID token to webMethods 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 webMethods 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://hostname/gateway/security/exchangeIDToken
     • Payload:

       {
       	"gatewayScopes": ["OktaTenant1:inventory"],
       	"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
       	"expiry": 3000
       }

     • The user presents the ID token as a JWT directly to webMethods API Gateway \(if the user has configured the JWT option in step 4\), and on validation accesses the protected resource.

OpenID Authorization Worklow

The OpenID Connect support in webMethods 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.

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 webMethods API Gateway.
4. webMethods API Gateway then performs the following:
   1. Identifies the application using the client ID.
   2. Validates the token locally or remotely if it is not possible locally.
   3. Checks if the requested resource is part of the scopes in the token.
   4. Checks the audience.

   webMethods API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, webMethods 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. webMethods 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://hostname/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 webMethods API Gateway.
6. webMethods API Gateway then performs the following:
   1. Identifies the application using the client ID.
   2. Validates the token locally or remotely if it is not possible locally.
   3. Checks if the requested resource is part of the scopes in the token.
   4. Checks the audience.

   webMethods API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, webMethods 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.