API Gateway 10.11 | Administering API Gateway | Security Configuration | OAuth, JWT, and OpenID Configuration | Adding an External Authorization Server
 
Adding an External Authorization Server
Pre-requisites:
You must have the API Gateway's manage security configurations functional privilege assigned to add 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. To use an external authorization server, you must configure your third-party authorization server.
*To add an external authorization server
1. Expand the menu options icon , in the title bar, and select Administration.
2. Select Security > OAuth/JWT/OpenID.
The available and configured internal authorization servers and external authorization servers are listed in the respective sections.
3. Click Add authorization server in the External authorization servers section.
4. Type a name for the external authorization server.
5. Type a description for the external authorization server that is being configured.
6. Provide the discovery endpoint in the Discovery URL field and click Discover.
When you specify the discovery URL, API Gateway fetches data from the URL response and auto-populates the fields with the fetched data.
7. Click Introspection and provide the local or remote introspection details to validate the incoming tokens.
Field
Description
Local introspection. Provide the following information to validate the tokens locally by API Gateway.
Issuer
Name of the token issuer.
JWKS URI
Specifies JSON Web Key Signature endpoint to retrieve the corresponding public certificates for performing local introspection.
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.
Truststore alias
Specify the alias of the truststore on API Gateway that holds the Certificate Authority (CA) certificate of third-party authorization server.
This is required if the JWKS URI is not available for the authorization server and you want to configure this certificate directly.
Certificate alias
Alias of the certificate used to validate the token.
The Certificate alias field contains a list of the available aliases in the selected truststore. If there are no configured truststores, this field is empty.
Remote introspection. Provide the following information to validate the tokens remotely if local introspection cannot be done.
Introspection endpoint
URL of the token introspection endpoint of a third-party OAuth 2.0 authorization server. API Gateway uses the introspection endpoint to check that access tokens used in client requests are currently active and are valid to invoke the protected resources.
Gateway user
The name of the Gateway user that API Gateway uses to invoke the token introspection endpoint.
Client ID
ID of the introspection client on the authorization server that API Gateway uses to introspect the access tokens.
Note:
Introspection client is any OAuth2 confidential client in API Gateway.
Client secret
Password of the introspection client that API Gateway uses to introspect the access tokens.
8. In the Dynamic client registration section, provide the following information if you want to dynamically create a client from API Gateway when required.
Note:
The dynamic client registration is not supported for external authorization servers when you publish an application from CentraSite to API Gateway.
You would use this configuration only if you do not intend to use any of the existing clients.
Field
Description
Enabled
Specifies whether dynamic client registration is enabled.
Click the toggle button to change the state to to enable dynamic client registration.
By default this option is disabled.
Provider name
Select the name of the third-party provider.
Client registration URL
Specifies the corresponding REST endpoint URLs for the client configuration of REST APIs.
Authentication type
Specifies the type of authentication scheme that API Gateway would use to communicate with the external authorization server for client management.
Select one of the following authentication type:
*Basic. Specifies the username and password information that would be passed in the authorization header of HTTP request for client authentication.
*Username. The username to access the protected resources of REST APIs.
*Password. A valid password associated with the username.
*Token. Specifies the token information that would be added as a bearer token in the HTTP request for client authentication.
*Token type. The type of token that would be contained in the HTTP request.
*Token. The token that would be contained in the HTTP requests.
*Refresh token. Specifies the refresh token information that would be added as a bearer token in the HTTP request for client authentication.
*Refresh token. The refresh token that you would get from the external authorization server for the registered client ID and client secret.
*Client ID. The client ID that you want to specify from the external authorization server.
*Client secret. A valid client secret associated with the client ID.
*Client credentials. Specifies the client information for which the application is created in the external authorization server.
*Scope. The scope of the client application that you want to specify from the external authorization server.
*Client ID. The client ID that you want to specify from the external authorization server.
*Client secret. A valid client secret associated with the client ID.
*None . Specifies that you could create the client dynamically in the external authorization server without using any type of authorization.
Supported grant types
Specifies the list of grant types that are supported by API Gateway. Basically, grant types are the ways to get an access token from the external authorization server.
Provide the grant type, in the Supported grant types field and click +Add.
You can add more than one grant by clicking +Add.
9. In the SSL Configuration section, provide the following information for SSL configuration, if the authorization server wants the 2-way SSL for the requests.
Field
Description
Keystore alias
Alias of the keystore containing the private key that is used for a secured communication between API Gateway and the authorization server.
You can view all the keystore aliases available in API Gateway. If there are no configured keystore aliases, the list box contains only the default keystore, DEFAULT_IS_KEYSTORE.
Key alias
Alias for the private key to use to validate the HTTP requests from the client.
You can view all the aliases available in the selected keystore. If there are no configured keystores, this list box is empty.
Truststore alias
Alias of the truststore on API Gateway that holds the Certificate Authority (CA) certificate of third-party authorization server.
Note:
You need to select a truststore alias only when all of the following are true:
*The client account on the third-party authorization server is configured to use mutual (two-way) SSL, and
*The authorization server’s Certificate Authority certificate is not in the set of well-known authorities trusted by the JVM in which API Gateway runs.
10. In the Metadata section, provide the following information for the authorization server metadata, which is used for the communication to portal.
Field
Description
Access token URL
The endpoint URL on the authorization server through which the client application exchanges the authorization code, client ID, and client secret, for an access token.
Authorize URL
The endpoint URL on the authorization server through which the end user authenticates and grants authorization to the client application.
Refresh token URL
The endpoint URL on the authorization server through which the client application refreshes an expired access token.
11. Click Scopes.
OAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. For example, an access token issued to a client application may be granted READ and WRITE access to the protected resources, or just the READ access. You can implement your APIs to enforce any scope or a combination of scopes as required. So, if a client receives a token that has READ scope, and it tries to invoke an API endpoint that requires WRITE access, the invocation fails.
You can provide the meaning to the scope in OAuth/OpenID scopes management section.
12. Provide the scope, in the Scope field that is registered in the authorization server and click +Add.
You can add more than one scope by clicking +Add.
13. Click Add.
The external authorization server is added. You can add as many authorization servers as required, but only one is the default at any given time.