Adding Okta as an IdP in Keycloak

Introduction

This guide will show you how to configure Keycloak to act as a broker between the Control Center and Okta. The communication mechanism between Control Center and Keycloak will be OIDC. The communication mechanism between Keycloak and Okta will be SAML. Okta will act as the IdP.

Overview

The overall setup should conclude with the Control Center Device Manager creating an OIDC connection to Keycloak, which brokers a connection to Okta via SAML, which will authenticate the user using traditional username and password. This communication flow will yield a successful SAML token being stored in Keycloak and an OIDC token being returned to the Control Center, which allows the user to gain access to the Device Manager. Here, the Device Manager application is used, but could easily be swapped out for the Control Center Admin access.

The overall flow is:

Steps	Flow of Okta as IDP to Keycloak.
1.	User comes to Okta and clicks on Bookmark Application.
2.	Okta will check the flag and if it is false that means the user has not registered. Okta will direct the call to CC.
3.	CC is not the IdP so it directs the call to KC
4.	KC is not the IdP so it directs the call to Okta
5.	Okta will ask for username and password and will give the session ID to the user
6.	Session ID is returned to KC
7.	Session ID is returned to CC
8.	User is able to access Device manager and register his device
9.	Device Manager will turn the flag in Okta ON which means the device has been registered and the session is active

Overall Objectives

Create Realm in Keycloak
Create Client in Keycloak
Create IdP Provider in Keycloak which will communicate with Okta via SAML
Enable communication with the Control Center to Keycloak's client via OIDC

Keycloak Setup

Create a Realm in Keycloak. This name will be referenced several times throughout this explanation.

After clicking Add realm, you will be directed to name it. In this scenario, we named it DemoJune5.

Add a client in Keycloak which will act as the endpoint for this IdP. The incoming request will come from the Control Center to this client.

You will be presented with this screen. We named our Client democlient.

Upon hitting Save, the following screen is displayed.

Verify that the Client Protocol is set to 'openid-connect' and the Access Type is set to 'confidential'. Again, this is so that the incoming requests from the Control Center can find and communicate with this Keycloak client. The Valid Redirect URL highlighted at the bottom of the page must be the Control Center's url.

Create IdP in Keycloak which will be used for Okta
Now that the Keycloak OIDC client is created, we can create a Keycloak IdP. In this case, we're going to make a SAML IDP. Begin by clicking on 'Identity Providers'.

Open Keycloak admin page, open Identity Providers, select the SAML v2.0 provider from the list of providers.

Name the IdP and copy the values of the Redirect URI (this will be used in Okta). It is recommended to use suffixes to avoid confusion. In this scenario, we are going to name this Keycloak IDP "ccadmin" and since this isn indeed an IdP, we will append the "_IDP" to it, making the whole name "ccadmin_IDP".

The url in the Redirect URI will be used in the SAML application in Okta. Make sure to keep it.

The First Broker Login must be selected

Gather Identity Provider Metadata Link from the OKTA SAML application
Navigate to the relevant app in Okta and copy the auto config URL (If the Okta Application Does not exist, see documentation located here )

Keycloak needs to send the authorization request to Okta. Okta must be configured to accept the SAML request generated by Keycloak. Go to your OKTA SAML application and click "Sign On". You will see a blue link for "Identity Provider Metadata". Right click and save the url. You need to put this information into Keycloak.

Import data from OKTA into Keycloak
We now have to put that url into Keycloak so that Keycloak knows where to send the auth request. While you are still inside the Identity Provider you were just creating, paste the URL you just copied into the "Import from URL" text field at the bottom of the form. Once that is done, hit "Import".

Ensure that the FIRST_BROKER_LOGIN is set properly. This will make sure that the user doesn't have to be manually created in KC.

5.1 Verify the First Broker Login
The First Broker Login needs to be set up so that the authenticating/authenticated user does not need to set up an account in Keycloak. To do this, go to the Authentication tab on the left side of the admin console. Click the drop-down and select First Broker Login.

Once this is completed, verify that the settings match those below.

Add an IdP redirector to Keycloak
Keycloak needs to link the client to the IdP. This can be done by creating an IdP redirector in the client which will point to the IdP you just created.

Navigate to the Authentication section. Click New.

Add new flow — this will add a new authentication mechanism

Add new execution — this will add a step in the parent authentication mechanism

Click on Identity Provider Redirector

Set execution to 'alternative'

Config the authenticator to specify the SAML provider

Name the "Default Identity Provider" the EXACT name of the identity provider you created earlier. the name should have a suffix of "_IDP". When you're done. hit save.

Go back to the client you created earlier by clicking "Clients" in the menu and selecting the client from the list.

Set the client to use the IdP redirector at the very bottom of the form. To do that, click "Browser Flow" and select the IdP Redirector you just made.

So far, you have Keycloak configured to accept incoming OIDC connections on a client and redirect that request to an External IdP, in this case, Okta.

Plug-in into HYPR CC
We need to gather the OIDC information from Keycloak so that we can set the urls in the Control Center. To do so, we need to go to our clients and click the installation TAB. Once there, click the drop-down and select the "Keycloak OIDC JSON" option.

Note/copy the auth-server-url, resource, and the credential secret

Keycloak OIDC url(s) are listed in the relevant docs. They are listed below for convenience:

🚧
URL Case Sensitive
Note that the URLs are case sensitive

You will need to take note of these url's. They will be entered into the Control Center.

Control Center config attr	Value
HYPR Url	Base url of the HYPR Control Center
Client Id	corresponds to resource attribute on KC config page
Client secret	corresponds to secret attribute on KC config page
User name claim attribute	This is the attribute in OIDC claims set, to map to the HYPR user name More info: `sub` is a standard claim, It is required by the OIDC spec, hence likely to be available. However, this is usually cryptic text. `preferred_username` not a mandatory claim. KeyCloak supplies this and is more user friendly. `email` is what we've been using See List of standard claims
OAuth url	{auth-server-url}/auth/realms/{realm}/protocol/openid-connect/auth Example: http://ec2-35-153-253-82.compute-1.amazonaws.com:8230/auth/realms/DemoJune5/protocol/openid-connect/auth
JWKS url	{auth-server-url}/auth/realms/{realm}/protocol/openid-connect/certs
Token url	{auth-server-url}/auth/realms/{realm}/protocol/openid-connect/token
Userinfo url	{auth-server-url}/auth/realms/{realm}/protocol/openid-connect/userinfo

Configure the RP application
Navigate to the relevant Application in the Control Center and select IdP management. Enter the correct URLs and values that you gathered from Keycloak into the appropriate fields.

You can now access the device manager from the Control Center using Okta as an IDP from the following url:

https:///devicemanager/rpAppID

Troubleshooting

It is possible to map an attribute to/from the payloads.