Adding Okta as an IdP in Keycloak

IdP and SP Management

Configure Keycloak to act as a broker between the Control Center (CC) and Okta. The communication mechanism between CC and Keycloak will be Open ID Connect (OIDC). The communication mechanism between Keycloak and Okta will be Security Assertion Markup Language (SAML). Okta will act as the Identity Provider (IdP).

Logical Flow

The overall setup should conclude with the CC Device Manager creating an OIDC connection to Keycloak which brokers a connection to Okta via SAML who 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 CC allowing the user to gain access to the Device Manager. In this example, the Device Manager application is used, but could easily be swapped out for the CC Admin access.

982
  1. The user comes to Okta and clicks Bookmark Application.
  2. Okta will check the flag; if it is false the user has not registered, and 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 a username and password, and will give the session ID to the user.
  6. The session ID is returned to KC.
  7. The session ID is returned to CC.
  8. The user is able to access Device Manager and register a 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

  1. Create a Realm in Keycloak.
  2. Create a Client in Keycloak.
  3. Create an IdP in Keycloak which will communicate with Okta via SAML.
  4. Enable communication with CC to Keycloak's client via OIDC.

Create a Realm in Keycloak

  1. Open Keycloak as an Administrator.
  2. Click Add Realm to create a new Realm.
295
  1. You will be directed to name the Realm. This example uses DemoJune5. The name you use will be referenced several times throughout this explanation.
1378

Create a Client in Keycloak

  1. Click Clients on the left navigation pane. At the right of the Clients dialog, click Create to add a client in Keycloak that will act as the endpoint for this IDP. The incoming request will come from CC to this client.
1454

Name the client; this example uses democlient.

972
  1. Click Save.

  2. The client properties dialog displays. Verify that the Client Protocol is set to openid-connect and the Access Type is set to confidential. This is so incoming requests from CC can find and communicate with this Keycloak client. The Valid Redirect URL highlighted at the bottom of the page must be the CC base URL.

1684

Create an IdP in Keycloak to 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.

  1. Begin by clicking on Identity Providers in the left navigation pane.

  2. Select the SAML v2.0 provider from the list.

1485
  1. Name the IdP and copy the values of the Redirect Uniform Resource Identifier (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 is indeed an IdP, we will append _IDP to it, making the whole name ccadmin_IDP.

The URL in the Redirect URI will be used in the SAML application in Okta; be sure to record it for later.

  1. The First Login Flow should be set to first broker login.
1008

Gather Identity Provider Metadata Link from the OKTA SAML Application

  1. Navigate to the relevant app in Okta and copy the auto config URL (If the Okta application does not exist, see the documentation located here ).
  2. Keycloak must 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.
  3. Right-click and save the associated URL; you must put this information into Keycloak.
1692

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.

  1. While you are still inside the Identity Provider you created, paste the URL you just copied into the Import from URL field at the bottom of the form.
  2. Click Import.
  3. Ensure that the First Login Flow is set properly. This will make sure that the user doesn't have to be manually created in KC.
1692

Verify the First Broker Login

The First Broker Login must be setup so that the authenticating/authenticated user does not need to set up an account in Keycloak.

  1. Open the Authentication tab on the left navigation pane of the admin console.
  2. Click the drop-down and select First Broker Login.
712
  1. Verify that the settings match those below.
1246

Add an IdP Redirector to Keycloak

Keycloak needs to link the client to the Identity Provider. This can be achieved by creating an IdP redirector in the client, which will point to the Identity Provider you just created in Keycloak.

  1. Navigate to the Authentication section and click New in the upper right.
2360
  1. Add a new Flow. This will add a new authentication mechanism. Our example uses an Alias of "IDPRedirect". Leave Top Level Flow Type as generic.
1694
  1. Add a new Requirement; this adds a step in the parent authentication mechanism.
1706
  1. Click Identity Provider Redirector.
1706
  1. Set Requirement to ALTERNATIVE.
2342
  1. Under Actions, on the right, drop down and click Config.
2350
  1. Under Create authenticator config, give the config an Alias and make sure the "Default Identity Provider" uses the EXACT name of the IdP you created above. The name should have a suffix of "_IDP" when you're done.
1712
  1. Click Save.
  2. Go back to the client you created earlier by clicking Clients in the menu and selecting the client from the list.
2344
  1. Click Browser Flow and select the IDP Redirector you just made (IDPRedirect in this example).
613

You now have Keycloak configured to accept incoming OIDC connections on a client and redirect that request to an external IdP - in this case, Okta.

Plug into HYPR CC

We need to gather the OIDC information from Keycloak so that we can set endpoint URLs in CC.

  1. Open the Clients left navigation item and click the Installation tab.
  2. Click the drop-down and select Keycloak OIDC JSON.
1110
  1. Record auth-server-url, resource, and secret.
1330

Keycloak OIDC URL

These URLs are listed in the relevant docs, but we have included them here for your convenience.

📘

NOTE

The URLs are case-sensitive.

You will need to take note of these URLs. They will be entered into the Control Center as Application IdP endpoints.

Control Center config AttributeValue
HYPR URLBase URL of the HYPR Control Center.
Client IDCorresponds to resource attribute on KC config page.
Client secretCorresponds to secret attribute on KC config page.
User name claim attributeAttribute in the OIDC claims set to map to the HYPR username.

sub is a standard claim required by the OIDC spec, and hence likely to be available; however, this is usually cryptic text
preferred_username is not a mandatory claim; KeyCloak supplies this and is more user-friendly
* email is what we've been using

See the 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

  1. Navigate to the relevant Application in CC.
  2. Select IdP Management in the left navigation pane.
  3. Enter into the appropriate fields the URLs and values gathered from Keycloak.
1519

You can now access the Device Manager from CC using Okta as an IDP from the following URL:

https://<controlCenterUrl>/devicemanager/rpAppID

Troubleshooting

It is possible to map an attribute to/from the payloads. The following is an example of mapping email as an attribute.

1077