Connect Okta

This is the Okta walkthrough for Authenticate users with your identity provider. We will start by creating an application in your Okta organization. We will then configure Okta as a provider in your Keycard zone. This application and provider pair creates a connection that will allow users to sign in using Okta.

For illustrative purposes, the zone in this tutorial is named “Example”. Each zone also has a unique Zone ID that appears in the zone’s domain: <zone-id>.keycard.cloud. The Zone ID is distinct from the zone’s name. Throughout this tutorial, <zone-id> is a placeholder you will replace with the ID of your own zone.

In the first phase of this tutorial, we will create an application in Okta. You’ll configure the application with the necessary settings to connect it to your zone.

1. In Okta Admin Console, select Applications and Resources > Applications in the navigation menu.

2. On the Applications page, click the Create App Integration button. A Create a new app integration wizard will appear.

   Select OIDC - OpenID Connect as the Sign-in method.

   Keycard signs users in with OpenID Connect, so this sign-in method is required.

   An Application type section will appear. Select Web application.

   Click the Next button. You will be directed to a New Web App Integration page.

3. The New Web App Integration page is where settings are configured.

   Under General Settings, enter “Example”, which is the name of your zone, as the App integration name.

   Scroll down to Sign-in redirect URIs and enter: https://<zone-id>.keycard.cloud/oauth/2/redirect

   Optionally, scroll down to Sign-out redirect URIs and enter https://<zone-id>.keycard.cloud/openid/connect/redirect/logout. Keycard uses it only for single logout, which is off unless you turn it on for the Provider through the Management API.

   Double check that the domain in the URLs matches the domain of your zone.

   Scroll down to Assignments. For the Controlled access setting, select Limit access to selected groups and add the groups whose users should sign in to the Zone. Allow everyone in your organization to access with Enable immediate access turns on Okta Federation Broker Mode, which removes group assignment; use it only in a test org.

   Click the Save button.

You’ve successfully created an application in Okta. You should now be on the settings page for the new Example application. This application will allow users in the groups you assigned to sign in to your Zone with their Okta account.

Remain on this page, as we will need to refer to the settings in the next phase.

In the next phase of this tutorial, we will create a provider in Keycard. You’ll configure the provider with the necessary credentials to connect to your Okta organization.

It is recommended that you complete these steps in a new browser tab or window, as you’ll need to copy and paste settings between Okta Admin Console and Keycard Console.

1. In Keycard Console, make sure you’re in your Zone, because Keycard creates the Provider in the Zone you’re in and your Zone can only use its own Providers for sign-in. If you aren’t in it, go to Zones, open the ⋯ menu on your Zone’s card, and select Switch to zone.

   Creating a Provider takes the Manager Role on the Zone. If Switch to zone is missing from the card’s menu and you aren’t already in that Zone, you don’t have access to it yet; see Assign Zone Admin Access.

2. Select Providers in the navigation menu.

3. On the Providers page, click the Add Provider button. A Create provider screen will appear.

   In the Name field, enter “Okta”.

   In the Issuer URL field, enter your Okta domain, prefixed with https:// as the URL scheme. For example: https://<your-domain>.okta.com. You can find your domain by clicking your name in the top-right corner of Okta Admin Console. The domain appears in the menu.

   In the Client ID field, enter the Client ID that Okta assigned to the newly created Example application. This can be found on the settings page for the application in Okta Admin Console. It is easiest to copy and paste the Client ID from Okta Admin Console to Keycard Console.

   In the Client Secret field, enter the Client Secret that Okta generated for the Example application. This can be found on the same settings page. Notice that there is a list of Client Secrets, which should contain a single secret. It is easiest to copy and paste the secret from Okta Admin Console to Keycard Console.

4. Click Create Provider. Keycard Console opens the new Provider’s Configuration tab.

You’ve just created a Provider in Keycard that is connected to your Okta organization!

In the final phase of this tutorial, we will configure user authentication to occur through Okta.

1. In Keycard Console, still in your Zone, click Settings under Zone in the sidebar.

2. On the zone configuration page, select the Settings tab.

3. In the Zone sign in configuration section, open the Identity Provider dropdown and select Okta.

4. Click Save Changes.

You have just configured your zone to authenticate users through Okta! Users who sign in to this Zone now authenticate with their Okta accounts.