OAuth Authentication Use case and Workflow
The Open Authorization is a flexible authorization framework for securing application access to protected resources of APIs. OAuth 2.0 uses access tokens that are presented by client applications (on behalf of the end users) to access the protected resources.
The OAuth authorization framework includes the following terms:
Roles
Resource Owner (or the End User). This is the holder of the protected resources that the client application accesses. The resource owner is typically a person (usually the end user), but could also be an application.
Client Application (or the Client). This is the application that is requesting access to protected resources on behalf of the end user.
Resource Server (or
API Gateway). This is the server that stores the protected resources the application is trying to access. API Gateway acts as a resource server.
Authorization Server. This is the server that acts as an interface between the client application and end user, authenticates the end user, and issues access tokens after proper authorization. API Gateway can be configured to act as an OAuth 2.0 authorization server. You can configure API Gateway for use with a third-party OAuth 2.0 authorization server, such as PingFederate.
Authorization Grant Types
Authorization Code. This is the grant type used to obtain access tokens (and optionally refresh tokens) and is optimized for confidential clients.
Note:
API Gateway supports the confidential client authentication using Authorization headers. The confidential clients have to authenticate using their credentials, the client id and client secret combination. Few points to consider using the Authorization Code grant type:
If the property
watt.server.oauth.token.endpoint.auth=session (the default value) and the confidential client already has a session when it comes to the token endpoint, the access to the endpoint is granted even if there are no credentials in the header.
If the property
watt.server.oauth.token.endpoint.auth=credentials or if the client does not already have a session, the confidential client must provide the client_secret in the Authorization header.
API Gateway does not support the client secret in the body of the request for the Authorization code grant.
For details about the properties mentioned, see webMethods Integration Server Administrator’s Guide
Implicit. This is the grant type used to obtain access tokens and is optimized for public clients. It does not support the issuance of refresh tokens.
Client Credentials. This is the grant type used to obtain access tokens for client-only authentication.
Resource Owner Password Credentials. This is the grant type used to obtain access tokens when the resource owner has a trust relationship with the client, and clients are capable of obtaining the resource owner's credentials.
Clients
Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client is a web app, where no one but the administrator can get access to the server, and see the client password.
Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password.
API Gateway can be used as an authorization server and as a resource server.
API Gateway as a Resource Server
When API Gateway acts as a resource server, it hosts the protected resources, accepts, and responds to the client applications' requests that include an access token. The client application sends the access token in the Authorization request header field using the Bearer authentication scheme. The resource server validates the access token locally or remotely if it cannot validate locally.
If the token is valid and the client application has privileges to access the protected resources, the resource server executes the request. If the access token is invalid, it rejects the request.
API Gateway as an Authorization Server
When API Gateway acts as an authorization server, it receives authorization requests from client applications. The authorization server handles the interactions between the client application, resource server, and resource owner for approval of the request.
As an authorization server API Gateway issues tokens to client applications on behalf of a resource owner for use in authenticating subsequent API calls to the resource server. The resource server hosts the protected resources, and can accept or respond to the protected resource requests using access tokens. If the client application is authorized to access the protected resources, the resource server executes the request. The authorization server retains the information about the access tokens it issues, including the user information. When a client presents an access token to the resource server, the resource server sends the token to the authorization server to ensure that the token is valid and that the requested service is within the scope for which the access token was issued. A scope is the definition of the resources that the client application can access on behalf of a resource owner. If the client application does not have privileges to access the resources, the resource server rejects the request.
Using API Gateway with an External Authorization Server
When API Gateway is the resource server, you must specify an authorization server. As an alternative to using API Gateway as the authorization server, you can use a third-party server as the authorization server. This allows API Gateway to validate access tokens issued by third-party servers and also allow to dynamically create clients in the third-party server.
Note:
Before you configure
API Gateway to use a third-party authorization server, make sure that the authorization server is compliant with the RFC 7662, OAuth 2.0 token introspection.
From
API Gateway release 10.3 onwards
API Gateway supports multiple authorization servers.
To use an external authorization server, you must configure your third-party authorization server. This includes, but is not limited to, the following:
To introspect the token, you should have a JWKS URI or you should create a client account that
API Gateway uses to call the authorization server's introspection endpoint.
Make a note of the client_id and client_secret values. You provide this information as part of defining the external authorization server alias for the API Gateway resource server.
Make a note of the URL for the introspection endpoint. You provide this information as part of defining the external authorization server alias in the API Gateway resource server.
Validation of JWT token of the external authorization server happens in the following ways:
Local Introspection | Remote Introspection |
Validation of the JWT token happens within the gateway in the following methods: Using JWKS URI. The external authorization server's signature is verified by using the public certificate in the JWKS URI. API Gateway's cache has a key as kid claim and its value is the certificate corresponding to the kid claim. The cache is populated on every restart of API Gateway by invoking the JWKS URI. In the runtime, while validating the token using the local introspection, the kid value from the incoming JWT is fetched and the corresponding certificate is retrieved from the cache and the signature validation happens. Using RSA. The external authorization server's signature in the JWT is verified by the truststore defined in the local introspection configuration. Using HMAC. If the authorization server uses HMAC algorithm, that means the signature validation of the JWT is performed using a shared key between the authorization server and API Gateway. You must specify the HMAC shared secret when creating the strategy of the application. The HMAC shared secret in the application is used to validate the authorization server's signature present in JWT. | Validation of the JWT token happens with the authorization server. Therefore, token caching is not possible in remote introspection. It has an introspection endpoint, which is used to validate the token. In addition, the client id and client secret are used to protect the endpoint, so that anonymous users cannot access the resource. To invoke an endpoint, you require a user; Gateway user is the one you can use to invoke the endpoint. |
Create the required scopes.
Configure an alias to the authorization server.
Currently, API Gateway, by default, can be used with the following third-party authorization servers, but are not limited to, that are RFC 7662, OAuth 2.0 token introspection compliant:
Okta
PingFederate
You can also use other third-party authorization servers like Google, keycloak, and so on.
Authorizations for applications created from API Portal
When you create applications through API Portal, you must specify the required authorization server using the watt.server.oauth.authServer.alias settings in the Administration section of API Gateway.
If API Gateway is the authorization server, then provide
local as the value of the
watt.server.oauth.authServer.alias setting. Else, provide the name of the corresponding authorization server. For information on extended settings, see
Configuring Extended Settings.
Use case 1: OAuth Authentication with API Gateway as a Resource server as well as an Authorization server
This describes the high level workflow for the scenario where API Gateway is a resource server as well as an Authorization server.
1. Configure API Gateway as an internal authorization server.
2. Map the scopes.
3. Enforce the Identify & Authorize policy on the API.
Ensure to select OAuth2 token. For details of the Identify & Authorize policy see,
Identify & Authorize.
4. 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 OAuth 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. Refer the
Authorizations for applications created from API Portal section for information on configuring authorization server for the applications created from API Portal.
5. Activate the API.
User on invoking the API uses the OAuth identification method to access the protected resource.
6. Get OAuth token required to access the application. For the procedure on retrieving an OAuth token, see
Retrieving OAuth Token.
7. Use the access token to invoke the API.
Use case 2: OAuth Authentication with API Gateway as a Resource server and an external Authorization server
This describes the high level workflow for the scenario where API Gateway is the resource server with a third-party authorization server. This is generally used in an environment where there is an existing authorization server, which is used with API Gateway as a resource server.
1. Configure a Provider if you are using the Dynamic client registration. Else you can proceed to step 2.
2. Configure an external authorization server.
Ensure you configure OAuth scopes while configuring the authorization server. For a complete procedure on configuring an external authorization server, see
Adding an External Authorization Server.
3. Map the scopes.
4. Enforce the Identify & Authorize policy on the API.
Ensure to select OAuth2 token. For details of the Identify & Authorize policy see,
Identify & Authorize.
5. Associate an application with the API.
You can create a new application or use an existing one. Ensure that the associated application contains the strategy for OAuth authentication and contains the client ID. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. If the authorization server supports dynamic client registration, then you can select the option Generate credentials. If the application is already created in authorization server, then provide the respective client ID. For a complete procedure on creating an application with a strategy, see
Creating an Application. Refer the
Authorizations for applications created from API Portal section for information on configuring authorization server for the applications created from API Portal.
6. Activate API.
User on invoking the API uses the OAuth identification method to access the protected resource.
7. Get the access token from the authorization server. For the procedure on retrieving an OAuth token, see
Retrieving OAuth Token.
8. Use the access token to invoke the API.
For a detailed procedure on using OAuth Authentication with
API Gateway as a Resource server and OKTA as an external Authorization server, see
Securing APIs using 3rd party OAuth 2 provider in API Gateway.
OAuth Authorization Workflow
The flow of authorization requests and responses between the end user, client application, authorization server, and resource server is as depicted in the following figure.
The OAuth authorization workflow is as follows:
1. The end user logs in, the client application sends the authentication request to the authorization server to obtain an access token.
2. Authorization server validates the request and generates an access token for the client.
3. Client uses this access token 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.
If all the above are validated, 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.
