Deploying Keycloak IdP with Okta

Introduction

This guide shows how to configure Keycloak as an Identity Provider (IdP) with Okta.

To begin, please ensure you have administrative access to both your Keycloak and Okta environments. The following high-level milestones will be reached through the course of our deployment.

Overall Objectives:

Enable Keycloak Identity Provider Role
Configure Keycloak as an Identity Provider (IdP within Okta
Configure the Okta Client (SP) within Keycloak

User Flow:

Steps	Keycloak as IdP
1	User goes to Okta
2.	The user attribute already exists and the flag is True. This will check the routing rules as Okta is a SP.
3.	Keycloak will ask HYPR to authenticate.
4.	User will get a PUSH and authenticate from their phone
5.	User goes to Device Manager via Control Center
6.	Control Center will ask Keycloak (as Keycloak is IdP here) if the session is still active
7.	Keycloak will respond with a session token if the session is still active.
8.	User will be taken to Device Manager screen to register more devices.

Enabling the Keycloak Identity Provider Role:

Start by accessing the administrative console for your Keycloak environment. Note that within your Keycloak deployment there are ‘realms’. Each realm will have a unique Federation / SAML configuration. Select the realm of your choice for this integration.

Once you have accessed the Keycloak Realm of your choice, you will need to do two things. First, take note of the realm name as listed in the Name setting, in the example it is Example. This is a case-sensitive value. Click on the Identity Providers section of the navigation bar.

📘
It is critical you keep in mind that the Realm Name is case-sensitive and must be taken from the Name setting as shown in the screenshot above. This value will be used in multiple URLs and is case sensitive in these URLs too.

You will see a drop-down menu to select an Identity Provider type. In this configuration you will want to select SAML v2.0.

📘
You will notice that each realm can only act with a single Identity Provider. As an example, should you want to also configure SP applications with OpenID Connect (OIDC), this would require another realm.

When you have selected SAML v2.0, a configuration menu will open. There are three changes you will need to make at this point, as depicted in the image below.

Configuration	Value
Alias	This can be set to any value. The value saml-anything is used in the example.
Single Sign-On Service URL	This format of the URL will be required for your configuration: https://{KeycloakURL}/auth/realms/{RealmName}/protocol/saml
NameID Policy Format	This dropdown will need to be set to Unspecified for the Okta deployment.

After making these setting changes, select save at the bottom of the page.

Keycloak is now configured as a SAML 2.0 Identity Provider. You’ll now need to download the Identity Provider Metadata for the next configuration steps.

This metadata can be found at the following URL:

https://{KeycloakURL}/auth/realms/{RealmName}/protocol/saml/descriptor

Within this metadata you will need to extract the IdP signing certificate. Copy the dsig:X509Certificate certificate value to a text editor of your choice. The document will need to consist of 3 lines as follows:

-----BEGIN CERTIFICATE-----
{Certificate Value}
-----END CERTIFICATE-----

Save this value as a .crt file, for example: example_idp.crt

Configuring Okta to use Keycloak as an IdP:

Start by accessing the administrative console for your Okta environment. In the examples we will be utilizing the Classic-UI for the Okta administrative environment.

Start by navigating to the Identity Providers configuration under Security.

In the Add Identity Provider drop-down, select Add SAML 2.0 IdP.

In the Add Identity Provider configuration you will need to add the following settings:

Setting	Value
Name	Any friendly value to identify the IdP configuration in the future. As example: Keycloak Example
IdP Username	idpuser.subjectNameId
Match against	Okta Username
If no match is found	Redirect to Okta sign-in page
IdP Issuer URI	https://{KeycloakURL}/auth/realms/{RealmName}
IdP Single Sign-On URL	https://{KeycloakURL}/auth/realms/{RealmName}/protocol/saml
IdP Signature Certificate	Upload the certificate which was extracted from the IdP metadata above. Note: if crt file displays error "There was an error reading the certificate file: java.io.IOException: Incomplete data", Save the file with ".cer" extension

Select Add Identity Provider when these settings have been input.

Now that the Keycloak IdP has been created, select the Drop-Down Arrow next to the new IdP within Okta (see screenshot below for example).

Next to SAML Metadata, select the option to Download metadata.

Configuring the Okta Client (SP) within Keycloak:

To start, navigate back to the Keycloak administrative console and the realm which was configured as an Identity Provider.

Click on the Clients option on the lefthand navigation bar.

From the Client configuration menu, select the Create option on the right.

When the creation options appear, select the Import option and upload the metadata that was downloaded from Okta previously. Once you have done this, the Client ID will auto-populate and you will be able to save the client.

After selecting Save you will be in the configuration menu for the newly-created client. You will need to make the following changes:

Setting	Value
Sign Documents	Toggled Off
Encrypt Assertions	Toggled Off

After you have toggled off both of the settings, select Save at the page bottom.

The last step we will take is to disable unrecognized SAML Attributes. To do this, click into the Client Scopes in the client settings navigation.

The role_list attribute is Client Scope is added by default. These client scopes are added to the SAML assertion as SAML Attributes. Okta will not recognize the role_list as an attribute and will show an error in the system logs if it is left enabled.

Select the role_list attribute and click Remove Selected. The page will automatically save the change when you have clicked this button. Okta is now configured to use Keycloak as an IdP.

Conclusion

Keycloak is now configured as an Identity Provider, configured within Okta and also has a Client SP configuration for Okta.