How to Connect to an External Identity Provider Using SAML

Keycloak can act as a service provider using the SAML protocol to communicate with the external identity provider. This mode of operation is called identity brokering. To configure the Keycloak SAML brokering, navigate to <keycloakURL>/auth and log in with the account created during installation. Then select manta realm in the realm selection dropdown in the top-left corner of the screen.

Creating an Identity Provider

In the Keycloak admin console, navigate to the Identity Providers section and select SAML v2.0 from the dropdown to configure a new SAML provider.

No alt text provided

Next, fill in the required field Alias. The alias has to be unique in the set of providers configured in your realm. Next, select a display name. This value is used as a label on the login page. The rest of the options in the top section can be left with default values. Make sure the value of the field Enabled is ON before continuing.

Configuring the External Identity Provider

Import the Provider Metadata

Next, scroll to the bottom of the page to import the metadata of your SSO provider. If your provider does not offer metadata in XML format, the values can be input manually. In such cases, continue to the next section.

To import the metadata, either upload the metadata XML file or provide an URL from which the metadata can be downloaded.

No alt text provided

After choosing the file or URL, click Import. This will populate the SAML Config section with metadata acquired from the imported source.

At this moment, you can Save the configuration to persist the setting in the Keycloak server.

Define the Metadata Manually

To configure the integration manually, there are two required values.

Details about other fields are listed in the official https://www.keycloak.org/docs/latest/server_admin/index.html#saml-v2-0-identity-providers.

Registering Keycloak with the External Identity Provider

The next step is to register your newly created service provider with the external identity provider. The exact instructions depend on the external provider.

The metadata for the Keycloak Service Provider (SP), which is required for SP registration, can be found in the identity provider detail.

First, open the Settings page of the already configured identity provider by clicking the Edit button in the list of providers.

No alt text provided

Then click on the link in the field Endpoints.

No alt text provided

Use this URL to download the service provider’s XML metadata for import to the external identity provider.

Log In through the Identity Provider

Once the IdP has been configured, a new login option is available on the login page. Under the form where the username and password can be entered is a new section called Or Sign in With.

No alt text provided

The button label is determined by the value Display Name in the identity provider configuration. After clicking the button, the user is redirected to the configured SSO login page. After providing the login credentials, the user is then redirected back to the application.

Alternatively, the IBM Manta Data Lineage login screen can be skipped entirely, and the user can be automatically redirected to the IdP login page. In order to configure this, navigate to the Flows tab under the Authentication menu item in the Keycloak admin console. Select Browser Flow from the select box and click on the Actions button in the Identity Provider Redirect row. Then, continue by clicking on the button Config. In the form presented, set the ID of your identity provider (as it is registered in the identity provider lists) as a value for Default Identity Provider and save the configuration. In the same row, select REQUIRED.

No alt text provided

If the option First Broker Login (this is the default value) is selected for First Login Flow, the user has to validate and, optionally, fill in more details for the user profile. The user account is then created in Keycloak and linked to the external IdP.

User Roles

By default, the user who logged in through the IdP will not have any roles assigned. Remember, the roles are defined inside the Keycloak server.

To set up the roles for users, navigate to the Identity Provider section and create new mappers.

No alt text provided

There is a number of mappers available, and the actual setup depends on the IdP selected. The only exception is the hardcoded mappers.

The hardcoded mappers provide predefined roles to the user by default. The set value is applied to the user every time.

The user roles can later be adjusted for each user separately, as described in How to Create a Native User.

Setting up the SAML automatic login

Some general info first:

  1. Login page should not be displayed, or not for long at least. The user should be redirected to the IdP without any input required.

  2. Failed login is handled by the IdP, and is IdP specific. The IdP will not return the user back to application unless the user successfully finished the login. Keycloak will not let the user to access Manta Data Lineage.

  3. Admin has to use the Keycloak Admin Console URL: http://localhost:9090/auth/admin/manta/console/. The SSO is set only for the Manta Data Lineage Clients.


When you setup the IdP in the way described above the login page will look like this:

No alt text provided

You can either provide the required Keycloak account credentials, or click the saml button to login using the SAML provider. (Note that saml in this example is just and example label, it can have any label configured).

Some customer might want to bypass this login form altogether, when using the SAML IdP. This way the login page will take the user directly to the configured IdP and the user is directly logged in without any other interaction.

This configuration requires multiple configuration steps:

1. Create custom authentication flow

Login to Keycloak as admin and make sure you are working in the manta realm. In the Authentication section, create new flow:

No alt text provided

In the form select flow name (any string, anything descriptive) and make sure the flow type is set to Basic Flow:

No alt text provided

When the flow is created add following two steps:

No alt text provided

First, add the Cookie step, next add the Identity Provider Redirector step. Then change their requirement to Alternative. The final setup should look like this:

No alt text provided

Finally, click the cog icon on the Identity Provider Redirector step, and setup the default Identity provider for this step:

No alt text provided

The alias can be anything, and Default Identity Provider needs to be set to the alias of the required SAML provider setup in this guide.

2. Bind the authentication flow to clients

With the custom flow created we still need to bind it to specific clients. To do that, navigate to the Clients section. And select the client manta-admin-gui-fe

No alt text provided

At the bottom of the page, in the subsection Authentication flow overrides, set the browser flow to the newly created Flow created in step 1:

No alt text provided

Keep the Grant Flow empty as is.

Repeat the same steps for the clients: omd-fe-client and manta-flow-server