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:

982982

Steps

Flow of Okta as IDP to Keycloak.

User comes to Okta and clicks on Bookmark Application.

Okta will check the flag and if it is false that means the user has not registered. Okta will direct the call to CC.

CC is not the IdP so it directs the call to KC

KC is not the IdP so it directs the call to Okta

Okta will ask for username and password and will give the session ID to the user

Session ID is returned to KC

Session ID is returned to CC

User is able to access Device manager and register his device

Device Manager will turn the flag in Okta ON which means the device has been registered and the session is active

Overall Objectives

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

Keycloak Setup

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

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

13781378
  1. 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.
14541454

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

972972

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.

16841684
  1. 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.

14851485

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

10081008
  1. 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.

16921692
  1. 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.

16921692

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.

712712

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

12461246
  1. 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.

23602360

Add new flow β€” this will add a new authentication mechanism

16941694

Add new execution β€” this will add a step in the parent authentication mechanism

17061706

Click on Identity Provider Redirector

17061706

Set execution to 'alternative'

23422342

Config the authenticator to specify the SAML provider

23502350

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.

17121712

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

23442344

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.

613613

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.

  1. 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.
11101110

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

13301330

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

  1. 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.
15191519

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.

10771077