

Configure a Custom Key Manager¶

WSO2 API Manager is capable of integrating with any external OAuth Authorization Server to manage the OAuth clients and tokens that are required by WSO2 API Manager. Therefore, you need to use a custom Key Manager connector for this purpose.

Step 1 - Create a Key Manager connector bundle¶

You need to write a custom Key Manager connector as explained below.

Tip

The following are some out-of-the-box connectors that you can use as references.

Create a Maven project.

Let's download the sample project from here.

However, when manually creating a Maven project, you will need to follow the following steps.
1. Define a class that implements the KeyManagerConnectorConfiguration interface that is responsible for managing the configurations related to the Authorization Server.
2. Define a class that extends the AbstractKeyManager abstract class which is responsible for managing OAuth clients and the tokens that are needed by WSO2 API Manager.

Implement KeyManagerConnectorConfiguration.

In the sample project, this has been implemented in the org.wso2.custom.client.CustomOAuthClient.java class.

The following are the methods that the KeyManagerConnectorConfiguration interface uses to carry out various related operations.

Method	Description
getImplementation	Provides the fully qualified class name of the implementation that corresponds to the `KeyManager` interface.
getJWTValidator	Provides the fully qualified class name of the implementation that corresponds to the `JWTValidator`.
getConnectionConfigurations	Provides the list of configurations that need to appear in the Admin Portal in order to connect with the Key Manager.
getApplicationConfigurations	Provides the list of configurations that are needed to create OAuth applications in the OAuth server in the Developer Portal.
getType	Type of connector. For example, Okta.
getDisplayName	Display name to show in the Admin Portal.
getDefaultScopesClaim	The default scope claim available in JWT if it is different than the scope.
getDefaultConsumerKeyClaim	The default consumer key claim available in JWT if it is different to azp, which is the Authorized party - the party to which the ID token was issued.

Extend AbstractKeyManager.

The AbstractKeyManager implements the KeyManager interface. For more information on the operations carried out on the KeyManager interface, see Extending the KeyManager Interface.

In the sample project, the AbstractKeyManager interface has been extended using the org.wso2.custom.client.CustomOAuthClient.java class.
If you need to customize the JWTValidation interface, you need to extend the JWTValidator.
Build the project.

Navigate to the <PROJECT_HOME> directory and execute the following command.

mvn clean install

This will create a custom Key Manager connector JAR.

Step 2 - Deploy the bundle in the WSO2 API-M Server¶

Stop the API-M server if it is already running.
Copy the JAR file that is generated in the custom.key.manager component target directory, and add it in to the <API-M Server>/repository/components/dropins/ directory.
Start the Server

Step 3 - Configure the connector using the Admin Portal¶

Sign in to the Admin Portal.

https://<hostname>:9443/admin

https://localhost:9443/admin

Add a new Key Manager.

Click Key Managers and then click Add Key Manager.

Add the following Key Manager configurations.

The following table provides definitions for each of the Key Manager configurations.

Configuration	Description
Name	The name of the authorization server.	Mandatory
Display Name	A name to display in the UI.	Mandatory
Description	A brief description of the Key Manager.	Optional
Key Manager Type	The type of the Key Manager to be selected.	Mandatory
Well-known-url	The well-known URL of the Authorization Server (Key Manager). If the well-known URL is provided, other endpoints can be imported. e.g., `https://dev-599740.okta.com/oauth2/default/.well-known/oauth-authorization-server`	Optional
Issuer	The issuer that consumes or validates access tokens. e.g., `https://dev-599740.okta.com/oauth2/default`	Optional
Key Manager Endpoints
Client Registration Endpoint	The endpoint that verifies the identity and obtains profile information of the end-user based on the authentication performed by an authorization server.	Optional if the well-known URI is provided.
Introspection Endpoint	The endpoint that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth client.	Optional if the well-known URI is provided.
Token Endpoint	The endpoint that issues the access tokens.	Optional if the well-known URI is provided.
Revoke Endpoint	The endpoint that revokes the access tokens.	Optional if the well-known URI is provided.
Userinfo Endpoint	The endpoint that allows clients to verify the identity of the end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user.	Optional
Authorize Endpoint	The endpoint is used to obtain an authorization grant from the resource owner via the user-agent redirection.	Optional
Scope Management Endpoint	The endpoint is used to manage the scopes.	Optional
Connector Configurations
API Key	The API key that was generated from the Authorization Server.	Mandatory
Client ID	The client ID that was generated from the Authorization Server.	Mandatory
Client Secret	The client secret that was generated from the Authorization Server.	Mandatory
Claim URIs	This provides claim URIs for the consumer key and the scopes.	Mandatory
Consumer Key Claim URI	The claim URI for consumer key e.g., cid	Mandatory
Scopes Claim URI	The claim URI for scopes e.g., scp	Mandatory
Grant Types	The supported grant types.	Optional
Certificates
PEM	Either copy and paste the certificate in PEM format or upload the PEM file.	Optional
JWKS	The JSON Web Key Set (JWKS) endpoint is a read-only endpoint. This URL returns the Okta's public key set in JSON web key set format. This contains the signing key(s) that the Relying Party (RP) uses to validate signatures from Okta. e.g., https://dev-599740.okta.com/oauth2/default/v1/keys	Optional
Advanced Configurations
Token Generation	This enables the token generation process via the Authorization Server.	Optional
Out Of Band Provisioning	This enables the provisioning of Auth clients that have been created without the use of the Developer Portal, such as previously created Auth clients.	Optional
OAuth App Creation	This enables the creation of Auth clients.	Optional
Token Validation Method	The method used to validate the JWT signature. This is mandatory if the Token Validation Method is introspect
Self Validate JWT	The `kid` value is used to validate the JWT token signature. If the ``kid` value is not present, the `gateway_certificate_alias` is used.	Optional
Use introspect	The JWKS endpoint is used to validate the JWT token signature. If this option is used to validate the tokens it is mandatory to add a Token Handling Option For Okta it should be JWT and it is required to specify a claim mapping as a unique identifier. e.g., Claim Key : iss Claim Value : https://dev-599740.okta.com/oauth2/default	Optional
Token Handling Options	This provides a way to validate the token for this particular Authorization Server.	Optional This is mandatory if the token validation method is introspect
REFERENCE	The tokens that match a specific regular expression (regEx) are validated.
JWT	The tokens that match a specific JWT are validated.
CUSTOM	The tokens that match a custom pattern are validated.
Claim Mappings	Local and remote claim mapping.	Optional

Step 4 - Generate the keys using the custom Key Manager¶

Sign in to the Developer Portal.

https://<hostname>:9443/devportal

https://localhost:9443/devportal
Click Applications.
Create a new application or use the default application.
Select the Key Manager.
Click Generate Keys.

Tip

If you want to generate the tokens with scopes, make sure that those scopes are defined in the Authorization Server.

Top