Using Keycloak as an external IDP with WSO2 API Manager 3.1.0

This is a step-by-step guide on how to configure Keycloak (9.0) as an external IDP (federated IDP) with WSO2 API Manager. In this scenario we will be enabling OIDC as the protocol for Keycloak.

Installation

1. Download Keycloak standalone server (9.0 used here) from Keycloak download page.
2. Download and install WSO2 API Manager 3.1.0 (binary distribution used here) from https://wso2.com/api-management/#.

Setting up Keycloak Server

1. After downloading go to <KeycloakServer>/bin folder and execute the standalone.sh file.The Keycloak server is now running on port 8080.
2. Go to http://localhost:8080 and create an administrator account. You can now click on Administration Console > and log in using the account you’ve just created.

Admin Console Login

3. You are now on the pre-defined Master realm. A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm and they are isolated from one another and can only manage and authenticate the users that they control.The master realm is the highest level in the hierarchy. Admin accounts in this realm have permissions to view and manage any other realm. Hence to start with let’s create a new realm first.

Creating a New Realm

1. Create a new realm by clicking on the drop-down arrow next to the realm name in the upper left corner.In this guide we will call the new realm ‘apim’.

Creating a New Client

Every application that interacts with Keycloak is considered to be a client. Let’s create a new client under the new realm ‘apim’ as below.Look for the Clients tab (under Configure ) in the left menu and hit Create. Select the client protocol as below and add a preferred client ID as well.

After clicking on save, configure the rest of the fields as below. WSO2 Identity Server (default key manager of API Manager) ‘s common authentication endpoint is added as Root URL.

After setting ‘Access Type’ field to ‘confidential’ this will enable the ‘Credentials’ tab at the top, where you can obtain the client secret for this client. Copy the secret value which will be required later.At this point, we have configured our openid-connect client named oidc-km.

Role Creation and Mappings

If you are familiar with WSO2 API Manager there are certain roles maintained to decide which user could perform which actions such as ‘subscriber’,’creator’ and ‘publisher’ etc. Hence we need such mapping roles defined in the client we created, so these roles of a Keycloak user can be mapped to the internal roles of API Manager. In an ideal scenario you could create different roles to represent different permissions/user types. For simplicity, in this guide we will create a single role to be mapped.

Go to Clients -> oicd-km (specific client) -> Roles and click on ‘Add Role’. In this instance the role we created is called ‘any’.

Now, we will need this role claim included in the access_token. Hence we need to create a role mapping under the client. Select ‘Mappers’ tab and click on ‘create’ of this client. Fill in the details as below.

If you introspect the access token sent from Keycloak as explained in [1] it includes an atrribute called ‘sub’.This is an auto generated ID with special characters. Since we will be enabling JIT provisioning (at a successful login, Keycloak users will be auto inserted to APIM ) we need to extract the username from this claim else it will throw an error when trying to add the special characters. We can eliminate it by using the script mapper. Create the following mapper under the client for this. (This Script mapper is deprecated in 9.0 hence restart keycloak with the following to enable it : -Dkeycloak.profile.feature.upload_scripts=enabled )

Creating a User

Now we can add user/users under our new apim realm and also add the client specific roles to them. Go to Manage-> Users-> Add Users. Fill the relevant details and go to Credentials section.

Here provide the password value and set Temporary to ‘off’ ( else at the first login you will be requested to reset the password) and click on ‘Reset Password’.

Next go to ‘Role Mappings’ and under Client Roles select your Client ID (oidc-km in this case) and then you can select the new role we created (‘any’) and apply it to this user.

WSO2 API Manager Configuration

Defining Roles

If you defined separate roles in Keycloak client(such as subscriber/creator etc) you do not need to define any additional roles in API Manager. However, in this guide we are setting all those permissions to a single role for simplicity you can create a new role (ex: keycloak_role) through the management console combining all the permissions and add the necessary scope mappings (where the UI will be rendered for different roles/users based on those scope mappings)from the admin portal. You can refer to https://apim.docs.wso2.com/en/latest/install-and-setup/setup/sso/okta-as-an-external-idp-using-oidc/#page-header on how to address it.

Configuring Identity Provider

Now, we will have to configure a Federated Identity Provider (representing Keycloak) in WSO2 API Manager that can authenticate with the OpenID-connect client (oidc-km) in Keycloak.

1. Start WSO2 API Manager and login to management console through https://localhost:9443/carbon/ and go to ‘Identity Providers’ and ‘Add’.
2. Provide a name for the IDP and click on ‘Federated Authenticators’ and select ‘OAuth2/OpenID Connect Configuration’ and fill in the following details.

Authorization Endpoint URL: https://localhost:8443/auth/realms/apim/protocol/openid-connect/auth

Token Endpoint URL: https://localhost:8443/auth/realms/apim/protocol/openid-connect/token

Userinfo Endpoint URL: https://localhost:8443/auth/realms/apim/protocol/openid-connect/userinfo

Logout Endpoint URL: https://localhost:8443/auth/realms/apim/protocol/openid-connect/logout

3. Next go to Just-in-Time Provisioning section of the IDP configuration and enable the options as below. You could provision silently too but in this guide we will prompt for consent before provisioning.

4. Add the claim mappings as below under the same IDP configuration.Make sure that the ‘Identity Provider Role’ value added here is the same ‘Token claim name’ that you defined when creating the mapping in Keycloak.

5. Finally add the role mapping, which would map the role claim of keycloak to the required APIM internal role that your users should be applied with. In this guide Keycloak role ‘any’ will be mapped to ‘keycloak_role’ that was created. Ideally you can map the various keycloak roles you created to subscriber/creator etc.

Afterwards click on ‘update’ on the IDP configuration.

Updating the Service Providers

1.Now we need to update some configurations for the service providers which in this case are publisher and developer portal. If you have already logged in to these portals at least one, you can view the two service providers generated under Service Providers-> List.

Go to ‘Edit’ of apim_devportal service provider, and add the claim configurations as below.

2.Next go to ‘ Local and Outbound Authentication Configuration‘ section and update the federated authenticator with the IDP configuration that was done as below. Afterwards click on ‘update’.

3.Follow the same updates to apim_publisher service provider as well.

Finally, you need to import the public certificate of Keycloak to the client truststore of WSO2 API Manager. Follow below steps for this process.

Stop both servers, and go to <KEYCLOAK_SERVER>/standalone/configuration folder and execute below command.

keytool -export -alias server -keystore application.keystore -file publickeycloack.pem

Now go to <WSO2_APIMANAGER>/repository/resources/security and import the public certificate that was created by executing below command. Make sure to provide the absolute path to the .pem file.

keytool -import -alias server -file publickeycloack.pem -keystore client-truststore.jks

Once the certificate is added successfully, you can restart the servers. (make sure Keycloak is started with -Dkeycloak.profile.feature.upload_scripts=enabled )

Now you can try logging into the publisher /dev portals with the users created in Keycloak where you will be redirected to Keycloak login page to be authenticated. This guide only focus on enabling the two main portals, but if you need to enable SSO for admin portal or the management console please refer to http://www.xicojunior.com/blog/2020/05/09/enabling-sso-on-wso2-api-manager-3.1.0-carbon-console-and-admin-portal-with-keycloak/ .

[1] https://dzone.com/articles/sso-wso2-api-manager-amp-keycloak