Adding an Identity Provider to Enable Single Sign-on

Adding an Identity Provider to Enable Single Sign-on#

This is a general guide for setting up single sign-on (SSO) with an Identity Provider (IDP). This has been verified with OpenID Connect (Okta), but the guide aims to be provider-agnostic. Please note that if an external IDP is configured for the application, all user management functions are expected to be performed in the IDP and the relevant functions in the AMD Resource Manager will be disabled.

Prerequisites#

Keycloak is set up for AMD Resource Manager, so organizations, realms, etc. are already created. Correct realm is selected as all the actions are realm specific.

Add an identity provider#

Select Identity provider under Configure and add a new provider. There are many identity providers, and this guide will not cover every provider supported by Keycloak in detail.

The main things you need are:

Redirect URI from Keycloak
Configure this in the identity provider so that when Keycloak directs authentication to the external IDP, the provider can then redirect the user back to Keycloak.
Client ID from the IDP
The identity provider offers an ID so it can distinguish between different clients (applications) making requests to the provider.
Client secret from the IDP
A secret generated by the IDP.

The rest of the settings will vary between different types of identity providers.

Link identity provider to organization#

Select the correct organization from Organizations and go to the Identity providers tab. Select Link identity provider and then select the newly created identity provider from the list. Set:

Identity provider: [Your new identity provider]
Domain: [Domain attached to the organization]
Hide on login page: Off
Redirect when email matches: Off

Mapping attributes from the IDP#

When linking an IDP to an organization, the Role and Project membership management for the application is expected to be done on the IDP. On Keycloak, you can map attributes/claims from the IDP to Keycloak user roles and group memberships.

The prerequisite is that the IDP sends the groups a user is a part of as part of the authentication token for the user. There are additional expectations on the configuration of the IDP such that:

there is a group for users who have the Platform Administrator role and
each Project configured in the AMD Resource manager has a corresponding group in the IDP, which manages the members of the project.

Mapping Roles from the IDP#

Within the correct realm, navigate to the Identity Providers tab and select the identity provider you created for SSO. Go to the Mappers tab and select Add mapper. Use the following settings:

Provide a unique name for the mapper, e.g., Platform Administrator Role Mapper
Select an appropriate Sync mode override (Inherit, Force, or Legacy), we recommend Force (this will make the roles in Keycloak match the roles in the IDP)
Select Mapper Type: Claim to Role
Set the Claim to the name of the claim in the token which contains the groups (e.g., groups)
Set the Claim value to the name of the group in the IDP which corresponds to the Platform Administrator role in the application (e.g., MyCompany-Platform-Admin)

Save the mapper, and when the user logs in the next time, they will be assigned the Platform Administrator role in the application if they are part of the specified group in the IDP.

Mapping Group Membership from the IDP#