OAuth Authentication in API Gateway
The Open Authorization is a flexible authorization framework for securing application access to protected resources of APIs.API Gateway can connect to the OAuth server of your choice to authorize client applications. API Gateway also includes an in-built authorization server that supports OAuth 2.0 for securing your APIs. This article explains how to use the OAuth 2.0 functionality in API Gateway.
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. For details, see
https://tools.ietf.org/html/rfc6749.
OAuth adds a new layer called Authorization Layer for enabling access for protected information for the clients. Unlike the OAuth 1.0 protocol, OAuth 2.0 provides a rich authorization framework (not a protocol) with well-defined security properties. However, as a rich and highly extensible framework with many optional components, on its own, this specification is likely to produce a wide range of non-interoperable implementations. In addition, this specification leaves a few required components partially or fully undefined (for example, client registration, authorization server capabilities, endpoint discovery). Without these components, clients must be manually and specifically configured against a specific authorization server and resource server in order to interoperate.
The following diagram depicts the abstract flow of OAuth 2.0 Authorization framework. OAuth defines four roles: Resource Owner, Resource Server, Client, and Authorization Server.
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.
Resource Server (or
API Gateway). This is the server that stores the protected resources the application is trying to access and is capable of accepting and responding to protected resource requests using access tokens. API Gateway acts as a resource server.
Client Application (or the Client). This is the application that is requesting access to protected resources on behalf of the resource owner and with its authorization.
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 to the clients 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 OKTA and PingFederate.
Resource Server and Authorization Server interact with each other to verify the access tokens. There can be various levels of these interactions (3-legged OAuth, 4-legged OAuth, and so on). API Gateway can be used as an authorization server and as a resource server.
Clients can be of following types:
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 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.
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. |
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.
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.
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 client sends user authentication request to the authorization server (local or external) to obtain an access token.
2. The authorization server validates the request, wuthenticates the client and generates an access token for the client.
3. The client uses this access token to send HTTP requests to API Gateway.
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.
4. After validating the client, the request is directed to the Internal Server.
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:
When a Policy violation event is logged in case of expired Oauth2 tokens, the application that is associated turn in to Unknown.
5. The Internal Server sends the response with requested resource to API Gateway.
6. API Gateway then sends the protected request resource to the Client.
Authorization Grant Types Supported
OAuth 2.0 provides several grant types, based on the work flow required by your application. The following grant types are supported by the API Gateway local Authorization Server. APIs can be enabled for more than one grant types. This table lists the grant types and the applications they are sutable for
Grant type | Suitable for |
Authorization Code | Regular web applications executing on a server. |
Implicit | Single page applications. |
Resource Owner Password Credentials | Aplications that can be fully trusted with user credentials. |
Refresh Token | To further secure applications that require the Authorization Code or Implicit grant types. |
Client Credentials | Applications that involve only machine to machine interactions. |
Authorization Code
The Authorization Code grant type enables API providers to open their APIs to unknown (but registered) third-party application developers. This grant enables a flow in which user credentials are never shared with the client application. Users are redirected to the authorization server to authenticate themselves. Only when users authenticate themselves and grant the required permissions to the client application can the client application access their resources.
When should you use the authorization code grant type?
Use the authorization code grant type in scenarios where the API is being opened to unknown third-party application developers and exposing the user credentials is risky.
The user agent (web browser) is required component of this flow as many of the steps, such as user authentication, granting access permissions, passing an authorization code to the application and verifying the authenticity of the client application are performed by redirecting the web browser to different URLs. Therefore, it can be implemented in applications that either run in a web browser or can access a web browser.
It is suitable for:
Web applications that execute on a server
Mobile applications that can access a web browser
This diagram illustrates the flow for the Authorization Code grant type
For public clients, the
Authorization Code grant type can be further secured by PKCE mechanism. For more details, see
Securing Access Token Calls with PKCE .
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
The implicit grant type is similar to the authentication code flow, but the access token is given to the user-agent to forward to the application. This exposes the token to the user and other applications on the user's device. Also, this grant type does not authenticate the identity of the application and relies on the redirect URI (that was registered with the service) to serve this purpose.
In addition, the implicit grant type does not support refresh tokens. This diagram illustrates the flow for the implicit grant type
The flow for the implicit grant type is similar to the flow for the authorization code grant type, except that the authorization server sends an access token to the user-agent instead of an authorization code. The user-agent then passes the access token to the client application.
When should you use the implicit grant type? You should use the implicit grant type only with applications developed and published by trusted parties.
It is suitable for single-page applications that execute in the web browser as they cannot execute the flow required by the more secure and elaborate Authentication Code grant type
Resource Owner Password Credentials
In the flow for the resource owner password credentials grant type, users enter their username and password for a resource directly in the client application. The client application then passes the credentials to the authentication server to authenticate the user and obtain an access token.
This diagram illustrates the flow for the Resource Owner Password Credentials grant type.
Client application asks the user for her credentials and passes them to the Authorization Server. In response, the Authorization Server sends the access token directly to the client application.
When should you use the resource owner password credentials grant type? The resource owner password credentials grant type can be used only when users trust the client application with their credentials for a resource. This is usually the case when the client application is from the same party that hosts the resource or service that the client application is trying to access.
This grant type should only be used only if other grant types are not viable.
Client Credentials
This is the grant type used to obtain access tokens for client-only authentication.
The client credentials grant type is similar to the resource owner password credential grant type. The difference is that instead of user credentials, the client application provides its own client and secret. This grant type is intended for flows in which users are not involved.
This diagram illustrates the flow for the Client Credentials grant type.
The steps are similar to the resource owner password credential flow. Clients use their client IDs and secrets to identify themselves. On success, the Authorization Server returns access tokens. Avoid using refresh tokens in this flow as it increases the risk of exposing the client credentials.
When should you use the client credentials grant type? In this grant type, users do not need to authenticate themselves or authorize access to a particular resource or service. This grant type is suitable for scenarios such as client applications accessing their own resources. For example: a client application retrieving data from its own account
