Enable SSO using Keycloak with Developer Portal
This guide enables you to connect the Developer Portal to Keycloak for using Single-Sign On (SSO) with SAML protocol. Users logged in inKeycloak can work in Developer Portal without login again.
Keycloak as Identity Provider (IdP) and Prerequisites
Keycloak acts as an IdP to authenticate and authorize users. We configure Developer Portal that Keycloak can be used as IdP.
To support multiple tenants (or clients), you can create multiple realms. After first installation, there is only a Master realm. It is not recommended this. Use or create your own realm for this integration scenario.
Add a SAML Client in Keycloak
Add a new client (e.g. developer-portal ID) of client protocol saml in your Keycloak reaml …
After adding a new client, we change following settings …
| Setting | Value | Maybe a Reason or Description … |
|---|---|---|
| Sign Documents | disabled | For the first test we don’t need to sign documents. We sign documents later in this guide. |
| Client Signature Required | disabled | For the first test we don’t need it at this time. |
| Root URL | https://api-portal.yourdomain.com |
Replace api-portal.yourdomain.com by your own hostname |
| Valid Redirect URIs | /portal/* |
|
| Base URL | /portal |
|
| Master SAML Processing URL | https://api-portal.yourdomain.com/portal/rest/v1/saml/initsso |
Replace api-portal.yourdomain.com by your own hostname |
Add Mappers
Protocol Mappers are mapping user information into SAML protocol. Go to Mappers tab into you new created developer-portal client and press Add Builtin mappers X500 email, X500 givenName and X500surname …
… and press Add selected. Additional we need a group mapper of type Group list to transport the group member information …
Notice and remember the value of SAML Attribute Name for each mapper. We need the values later on SAML configuration settings in Developer Portal.
| Mapper | SAML Attribute Name Value | Hint |
|---|---|---|
| X500 Email | urn:oid:1.2.840.113549.1.9.1 |
|
| X500 GivenName | urn:oid:2.5.4.42 |
|
| X500 Surname | lastName |
This value must be set manually by replacing urn:oid:2.5.4.4 |
| maps-groups | member |
Configure SAML in Developer Portal
To configure SAML in Developer Portal, go to Administration > SAML > General …
We must set following settings on General tab …
| Setting | Value | Description |
|---|---|---|
| SAML enabled | On | |
| Binding | Redirect | |
| Identity provider ID | https://keycloak.yourdomain.com/realms/DeveloperPortal |
Set to URL of Keycloak and the realm name. Replace DeveloperPortal by your own realm. |
| Service provider ID | developer-portal |
This is the client ID created in Keycloak |
| Single sign-on endpoint | https://keycloak.yourdomain.com/realms/DeveloperPortal/protocol/saml |
Set to URL of Keycloak and the realm name. Replace DeveloperPortal by your own realm. |
| Single logout endpoint | https://keycloak.yourdomain.com/realms/DeveloperPortal/protocol/saml |
Set to URL of Keycloak and the realm name. Replace DeveloperPortal by your own realm. |
On User attributes tab … |
||
| First name | urn:oid:2.5.4.42 |
SAML Attribute Name value of mapper |
| Last name | lastName |
SAML Attribute Name Value of mapper |
urn:oid:1.2.840.113549.1.9.1 |
SAML Attribute Name value of mapper | |
| Member of | member |
SAML Attribute Name value of mapper |
On Advanced settings tab … |
||
| Create user automatically | On | This allows Developer Portal to create a user locally. |
Test the Round Trip
With the basic settings in Keycloak and Developer Portal you are ready to test the SSO login. For this, you need an onboarded user credentials in Keycloak. Go to the login page of Developer Portal …
… and use the Sign in with SSO button to login …
… and after login, you are redirected to Developer Portal …
… but you doen’t have any privileges. This let us to move to the next step and defines user groups in Keycloak.
Optional: Validate Mappers
Remember, we have selected the option Create user automatically. With all logins of a user, the user is created (or updated if already exists) in Developer Portal with all defined attributes. Login into Developer Portal as administrator and go to Home > Manage Users and validate the attributes of already logged in user. If an attribute is not corrected filled, validate the mappers.
Create User Groups in Keycloak
We create 3 user groups API Developer Portal Administrator, API Developer Portal Consumer and API Developer Portal Provider in Keycloak …
Now, we need a user in Keycloak which will member of all created groups temporary. You can use the user of the first round trip. Assign the user to all 3 groups.
Assign Privileges to User Groups
With the login procedure, the SAML protocol transports all group information of the user in Keycloak to Developer Portal. If we do a login again with the user which is member of all 3 groups, all groups are imported and available in Developer Portal. All imported groups have leading slash …
Now, we edit each group and assign privileges …
Conclusion: With the membership assignment of users in Keycloak to groups, we defines the privileges in Developer Portal.
Remember, we have assigned all 3 groups to the test user temporary. The assignment of membership can now moved to the correct once.
Make SAML Communication secured
Under construction: We continue here next time