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.
![*](icon_task_xpe.png)
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 following information to validate the incoming tokens.
Field | Description |
Local introspection. Provide the following information to validate the tokens locally. |
Issuer | Name of the token issuer. |
JWKS URI | Specifies JSON Web Key Signature endpoint to fetch the corresponding public certificates. |
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. |
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 ![](../yai-webhelp/images/active_policy.png) 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. |
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: ![*](chapterTOC_bullet.png) The client account on the third-party authorization server is configured to use mutual (two-way) SSL, and ![*](chapterTOC_bullet.png) 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 Save.
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.