Keycloak as a third-party Key Manager for WSO2 API Manager

Enterprises which are in requirement for an API Management (APIM) solution may already have their own identity and access management (IAM) product in place. In such situations they need to reuse their existing IAM solution and integrate it with the new APIM solution. Keycloak is a such open source identity and access management product.

The WSO2 API Manager has a capability to integrate with a third party IAM product to handle the clients, security and OAuth tokens. WSO2 API Manager has five main components as Publisher, Developer portal, Key manager, Gateway and Traffic manager.

The API developer portal makes the request to the key manager to create / edit / delete an OAuth application, generate the consumer key and secret, and generate the application token.

The API gateway makes the request to the key manager to validate the application token. These validations may include subscription validation and scope validation as well.

In this blog I discuss how to integrate Keycloak with WSO2 API Manager to provide the key management features as a third party key manager. We will be using the Keycloak 10.0.1 version and WSO2 APIM 2.6.0 version.

Key Manager extension point in WSO2 APIM

The Key Manager interface facilitates the bridging between the OAuth provider and WSO2 API Manager by providing many methods to implement according to the third-party Key Manager API specification to build third-party key manager extension. This extension needs to be built as a JAR file so it can be deployed as a library inside the APIM by changing the api-manager.xml allows the extension point.

The API Manager provides some generic method implementation via the AbstractKeyManager abstract class, so we need to extend the AbstractKeyManager class in our implementation.

As you can see in the above diagram there are many methods in this interface. We have to override and implement at least the below set of methods in our KeyManager implementation in order to integrate with Keycloak. We should refer the Keycloak API documentation when we are implementing each method.

For example, when API Developer portal is calling the createApplication method we have to call the corresponding API in the Keycloak to create an OAuth application in Keycloak side.

We have to make sure the return object from each method contains the proper data otherwise API Developer portal UI will brake while rendering the information.

METHOD	DESCRIPTION
createApplication	Creates a new OAuth application in the Authorization Server.
updateApplication	Update the OAuth application created in above method.
deleteApplication	Delete the OAuth application.
retrieveApplication	Retrieving the OAuth application details.
getNewApplicationAccessToken	Generating a new access token to be shown in the API developer portal after clicking ‘Generate Keys’ and ‘Regenerate Keys’.
getTokenMetadata	Gets details about an access token. This method will be invoked during the token validation phase upon an API invocation.

Keycloak configuration

Keycloak provides a REST APIs set for developers to interact with. These APIs are secured with OAuth 2.0, so before you call an API, first you need the access token. To get it, we should have a realm, client and user account with relevant permission in Keycloak side. In this section we will discuss how we can register those in Keycloak.

Prerequisite

Download the Keycloak 10.0.1 version, extract it and run the product.

Create an admin account.

Create a new realm

1. Login to the admin console by typing the http://127.0.0.1:8080/auth/admin in the address bar.
2. Click on the Add realm button.
   
3. Provide the realm name as “apim” and hit the “Create” button.
   
   You will be redirected to the realm setting page.
   

Create a client

1. From the left menu click on the “Clients”.
   
2. Now click on the “Create” button.
   Enter the “Client ID” as “apim-client” and hit the “Save” button.
   
   You will be redirected to the client settings page.
   

Create a user and grant permission

1. Click the “Users” on left menu and click on the “Add user”.
   
2. Create a user with the name “apim-user”.
   
3. Set a password to the created user using the “Credentials” tab in the user settings page.
   
   Make sure to turn off the “Temporary” toggle in this window.
4. Now click on the “Role Mapping” tab to assign the role to our user.
   
5. Select the “Realm Management” from “Client Roles” drop down and select all roles from the “Available Roles” box. Add the selected roles by clicking “Add Selected” button.
   

Now we have done all the configurations in the Keycloak side. Next step is to configure the API Manager. The API Manager will require the above details to integrate with Keycloak and below is the summary:

Realm: apim
Client: apim-client
Username: apim-user
User password: apimuser.123

Keycloak-WSO2 APIM integration java extension

As mentioned above, we have to implement the Java code and deploy it as a library to integrate API Manager with Keycloak. In this section we will discuss how we can implement the code and how to deploy it in the API Manager.

Keycloak key manager java code

As discussed above, we have to implement Java code at least for the methods mentioned in the “table 1”.

You can find the sample Keycloak integration Java code implementation on GitHub. With your business use case and with your requirement, you may change the implementation accordingly.

Clone the repository and build the code using Maven.

WSO2 API Manager configuration

1. Coping the JAR file to lib
   We have to copy the JAR file created above to the API Manager lib directory.
   
2. Keycloak configuration in api-manager.xml
   Java extension refers some configuration parameters from the api-manager.xml file. So those need to be defined in the xml file. Below table contains these parameters.

keycloakInstanceUrl	URL of the Keycloak server.	http://127.0.0.1:8080
keycloakRealmName	Realm name provided in above Keycloak configuration	apim
client_id	Client_id from client creation in Keycloak	apim-client
username	Used username in above when creating a user in Keycloak	apim-user
password	Password we have given in above when creating a user in Keycloak	apimuser.123

In the api-manager.xml file, the configuration should be done under the element <APIKeyManager></APIKeyManager>.

<APIKeyManager
   <KeyManagerClientImpl>org.wso2.keycloak.client.KeycloakClient</KeyManager ClientImpl>
   <Configuration>
      <keycloakInstanceUrl>http://localhost:8080</keycloakInstanceUrl>
      <keycloakRealmName>apim</keycloakRealmName>
      <client_id>apim-client</client_id>

      <username>apim-user</username>
      <password>apimuser.123</password>
   </Configuration>
</APIKeyManager>

3. The API Manager should retrieve the token from Keycloak and validate it as per our implementation. In the API Manager there is a synapse configuration file which defined the token endpoint. The endpoint is, by default distribution, configured to the local key manager server. And as we are integrating a third-party key manager, we have to change this synapse API endpoint to Keycloak server token endpoint.Keycloak server token endpoint: http://localhost:8080/auth/realms/apim/protocol/openid-connect/token
   

   Note: In the Keycloak server token endpoint URL, “/apim/” context path is a realm name. You may need to replace it with your appropriate realm name. Keycloak documentation reference for the token endpoint.

   
   

   Open the _TokenAPI_.xml file located in the {APIM_Home}/repository/deployment/server/synapse-configs/default/api/ and update the endpoint to above URL.
   

   
   

Now our setup is completed in terms of the configuration points. Restart / start the Keycloak and the WSO2 API Manager using the startup scripts which are located in the bin directory.

Testing the integration

1. Deploy the sample API using the API publisher. After that you would be able to view your sample API, PizzaShackAPI , in API store.
   
2. Create a new OAuth application named as “KeycloakApp” in the API store.
   
3. Go to the create application page and generate the keys. Enter the callback URL as https://localhost.
   
4. Refresh the page so you will be able to see the client application key and the secret. Now our OAuth client is registered in the Keycloak and the client key and secret are generated from the Keycloak end.
   
5. To generate the token, you may use the curl or web interface. Here I’m just using the web interface “Regenerate” button. Once the token is generated copy the token from here to the other location.
   
6. Go to the API and subscribe to the “KeycloakApp” application.
7. Now we have a valid access token as well as the application subscription so we would be able to call our API.