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
master
realm to create and configure the SSO in the Keycloak server. You can create a newrealm
and 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
subscriber
to 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/displayName
roles
: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 !!!! 🤘 ✌️