WSO2 API Manager 3.2 & Keycloak (OIDC) SSO
Guide: Configure Federated OpenID Connect SSO Between Keycloak & WSO2 API Manager 3.2.0
Greetings Everyone !!! 👋
In this medium, I will be 🚶walking through how to configure OIDC Federated Authentication & SSO flow between WSO2 API Manager 3.2.0 and Keycloak including JIT Provisioning.
I will be focusing and providing the instructions to configure the API Manager Devportal. You can follow the exact same steps to configure the Publisher and Admin portal if needed.
Please note that the respective Roles needs to be assigned and mapped in order to work accordingly
As out-of-the-box, the WSO2 API Manager 3.2.0 provides a platform to configure OIDC Federation. Furthermore, from APIM 3.0 onwards, the Publisher and Devportal logins are configured with OIDC flows internally (from 3.2.0, the Admin portal also supported).
Let’s break-in and start configuring our Keycloak and WSO2 API Manager 3.2.0 to do OIDC SSO …
🔐 Keycloak
Let’s start out configurations with the Keycloak server.
I hope you already have an active Keycloak server, which is up and running in your environment. If not, please follow the below-given instructions to download and start a Keycloak server in your local environment.
🚧 Setting-Up Keycloak
Click here to download the Keycloak standalone distribution to your preferred environment. After a successful download, extract the archive and navigate to <keycloak>/bin directory and execute the following command to start the server
# move to /bin directory and execute the following# unix env
sh standalone.sh# windows env
standalone.bat
Once the server is started, fire up your favorite browser and go to http://localhost:8080/auth. In the prompted view, register an admin user.
& Done… Simple as that 😃 👏
👉 On an additional note: You can follow the Getting Started Guide to start your journey with Keycloak servers
🌐 OpenID Endpoints
After registering the admin user and a successful log-in to the Keycloak server, you will be looking into a similar view as following
Click on the OpenID Endpoint Configuration in the General tab to list and display the endpoints that are related to the OpenID Connect.
Keep a note of the endpoints and URLs, as we will be needing that information when configuring the WSO2 API Manager 3.2.0.
✋ OpenID Connect Client Registration
Next, we will be creating an OpenID Connect client in the Keycloak server to represent and communicate with our API Manager server.
I will be using the existing
masterrealm to create and configure the SSO in the Keycloak server. You can create a newrealmand follow the steps if needed
Navigate to Clients menu to list all the pre-configured clients in the Keycloak server. You will be experiencing a similar view as given below
We’ll create a new one for our requirements. Click on the Create button to register a new client in the Keycloak server and input the following
- Client ID:
wso2apim - Client Protocol:
openid-connect
and Save the configurations. This will create a base OpenID Connect client.
On the next screen, add the following to configure our wso2apim client
The configuration may differ from Keycloak version to version. I am using, Keycloak 11.0 and providing the instructions
- Name:
WSO2 APIM - Enabled:
true - Access Type:
confidential - Standard Flow Enabled:
true - Implicit Flow Enabled:
true - Direct Access Grants Enabled:
true - Root URL:
https://localhost:9443/commonauth - Valid Redirect URIs:
https://localhost:9443/commonauth - Admin URL:
https://localhost:9443/commonauth
and Save the configurations.
Once the above-mentioned configurations are saved, navigate to the Credentials tab and copy the Secret value. We will need this secret value when configuring our API Manager server to communicate with Keycloak.
Next, move to the Roles tab to create and configure a subscriber role.
We will be creating a role named
subscriberto federate our Keycloak users and to give permissions to access the Devportal of the API Manager
You will be looking into a similar view as following
Click on Add Role and enter the following
- Role Name:
subscriber - Description:
A Subscriber Role
and Save.
We have successfully added a role to our OpenID Connect client. Now, we have to configure a mapper to include the created roles in the ID Token and to present it while performing the OIDC SSO flow.
To do that, move to the Mappers section and click on Add Builtin to list all the built-in mappers of the Keycloak server. Select the client roles mapper and Save.
On the following screen, configure the mapper to send the roles as we expect in the ID Token
- Client ID:
wso2apim - Client Role Prefix: leave it as empty
- Multivalued:
true - Token Claim Name:
roles - Claim JSON Type:
String - Add to ID Token:
true - Add to access token:
true - Add to userinfo:
true
and Save.
And we are done with the OpenID Connect client configurations. Next, we will be creating a demo user in the Keycloak.
✋ Keycloak User Registration
Let’s move to the Users section which is grouped under the Manage section in the left navigation panel. In the prompted view, we will find our admin user and we are going to create a new demo user for our SSO trial.
Click on Add User and enter the following
- Username:
keycloakuser - Email:
key@cloak.com - First Name:
Keycloak - Last Name:
User - User Enabled:
true - Email Verified:
true
and Save the user configurations.
Next, let’s move to the Credentials tab and enter a password for our demo user. Disable the Temporary Password and click on Set Password to save the password configurations.
Then, navigate to the Role Mappings tab to map our early created subscriber to our demo user.
Select the wso2apim client from the Client Roles dropdown and select the subscriber role and click on Add Selected to assign the role to our demo user.
We have now successfully configured the Keycloak environment to communicate and perform the OIDC SSO flow with our API Manager 👏👏
Next stop, WSO2 API Manager …
WSO2 API Manager 3.2.0
Let’s start configuring WSO2 API Manager 3.2.0, to perform SSO with Keycloak. As the first step, start the API Manager server and navigate to the Devportal to create a Service Provider.
As I explained earlier, from APIM 3.0 onwards, the Devportal and Publisher portals are configured with OIDC log-in flows. Hence, during the initial log-in to the portals, the API Manager will automatically generate and configure a Service Provider for each portal respectively. Therefore, it is no more required to explicitly create a new Service Provider for the respective Portals as in the 2.x series of the API Manager. But, we will be performing a couple of enhancements and additional configurations to the auto-created SPs to achieve our use-case.
Before making any configuration changes to the auto-created Service Providers, we have to register and configure an Identity Provider in the API Manager server to communicate with Keycloak and to perform Federated authentication. Hence, let’s get started with the Identity Provider configurations at the API Manager server
✋ Identity Provider for Keycloak
Let’s log-in to the Carbon Management console of the API Manager server by opening up a favorite browser and going to https://localhost:9443/carbon.
Sign-in to the management console using the admin credentials of the API Manager server. Then navigate to Identity Providers section and click on Add.
Setup the Identity Provider by providing the following data
- Identity Provider Name:
KeycloakIDP - Display Name:
Keycloak Identity Provider - Description:
Identity Provider for Keycloak - Alias:
https://localhost:9443/oauth2/token
Then, expand the Claim Configurations accordion to map and configure the Keycloak claims with API Manager. Click on Define Custom Claim Dialect and then Add Claim Mapping to add custom mappings. Input the following mappings
preferred_username:http://wso2.org/claims/displayNameroles:http://wso2.org/claims/role
Next, configure the User ID Claim URI as the preferred_username claim, and the Role Claim URI as roles claim.
Expand the Role Configurations section to map the Keycloak roles with local roles of the API Manager server. As we are performing SSO for the Devportal console, we are going to map the Keycloak’s subscriber role to our Internal/subscriber role.
Click on Add Role Mapping and then define the following
subscriber:Internal/subscriber
Once that is done, expand the Federated Authenticators section and then expand the OAuth2/OpenID Connect Configuration to configure the OIDC Authenticator. Input the following in the respective fields
- Enable OAuth2/OpenID Connect:
true - Client ID:
wso2apim(the Client ID of our Keycloak Client) - Client Secret: Paste the secret we copied from the Keycloak
- Authorization Endpoint URL: the authorization endpoint URL copied from the OpenID Connect Endpoint Configuration (ex:
http://localhost:8080/auth/realms/master/protocol/openid-connect/auth) - Token Endpoint URL: the token endpoint URL copied from the OpenID Connect Endpoint Configuration (ex:
http://localhost:8080/auth/realms/master/protocol/openid-connect/token) - Callback URL:
https://localhost:9443/commonauth - Userinfo Endpoint URL: the userinfo endpoint URL copied from the OpenID Connect Endpoint Configuration (ex:
http://localhost:8080/auth/realms/master/protocol/openid-connect/userinfo)
Finally, expand the Just-In-Time Provisioning accordion and tick the Always Provision to User Store Domain with PRIMARY and enable Provision Silently to provision the Keycloak users to the API Manager while logging to the portals.
And that's it for the Identity Provider configurations, click on Save and we are good to go to our final steps.
✋ Service Provider Configurations
I believe you have at least one time logged into the Devportal using the API Manager credentials to create the auto-generated Service Provider. If you have not done it, open up your favorite browser and go to the Devportal and click on Sign-in.
Now, let’s go to the Carbon Management console of the API Manager server and navigate to Service Providers and List. You will be seeing a similar screen as following with an auto-generated Service Provider in it called apim_devportal.
Click on Edit and expand the Claim Configurations. Choose the Define Custom Claim Dialect and Add Claim URI and input the following
preferred_username:http://wso2.org/claims/displayName:true
Also, select the Subject Claim URI as preferred_username.
Once that is done, expand the Local & Outbound Authentication Configuration section and tick the Federated Authentication and select the KeycloakIDP from the dropdown.
Then, enable the Assert Identity using mapped local subject identifier and update the Service Provider configurations.
🎉 Voila!!! 🎉
We have successfully configured Single Sign-On with OpenID Connect between WSO2 API Manager and Keycloak. Next, we will be doing a small test drive…
👏 👌 👏
Test Drive
Direct to the Store portal using https://localhost:9443/devportal/ and click on Sign-In.
You will be redirected to Keycloak’s login page to perform SSO. Enter the credentials of our Keycloak User and then allow the attributes on the consent screen to continue with the federation and provision of the Keycloak users to the WSO2 API Manager.
Happy Stacking !!!! 🤘 ✌️
