Use Okta Workforce Identity as an identity provider in Keyfactor Command

Okta Workforce Identity is an enterprise-grade identity and access management (IAM) solution that enables secure authentication, authorization, and user lifecycle management for employees, contractors, and partners. It provides single sign-on (SSO), multi-factor authentication (MFA), and adaptive security policies to streamline access and enhance security across applications and infrastructure. Keyfactor Command supports authentication via Okta Workforce Identity, allowing users to sign in using their Okta credentials.

In this guide, we explain how to prepare Okta Workforce Identity and configure it as an identity provider in Keyfactor Command. This enables users in Okta to authenticate to Keyfactor Command using their Okta credentials.

Outcomes

In this guide, you will:

• Prepare Okta by configuring an app integration, access policy, and ID and access token claims
• Add Okta as an identity provider in Command
• Add a group in Okta and map it to a security role in Command
• Verify that your configuration works as intended by signing in with the Okta identity provider

Prerequisites

Before you continue, you must ensure that you have the following prerequisites.

• Keyfactor Command 12 or greater: This guide assumes that you have access to Keyfactor Command and that it's deployed per the official Command documentation.
• Okta Workforce Identity with the API Access Management add-on: This guide assumes that you have Okta Workforce Identity configured with at least one authorization server. Your Okta tenant must have the API Access Management add-on. You may incur additional charges for this add-on. Please check with Okta for specific details.

Required roles

Ask your administrator to add your claim to a security role in Command that has the following permissions:

• Read and Modify identity providers
• Read and Modify security

Refer to the Command documentation to learn more about security roles and claims.

Step 1: Create an Okta app integration

This section provides the steps to create an Okta app integration using the Okta Admin Console. Only basic configuration is described in this section. Please refer to Okta's OIDC integration guide for more details.

1. Sign in to the Okta Admin Console.
2. Go to Applications > Applications.
3. Click Create App Integration.
4. In the Sign-in method section, select OIDC - OpenID Connect.
5. In the Application type section, select Web Application.
6. Click Next to create the app integration.
7. In App integration name, enter a name for this app, such as "Command".
8. Leave Proof of possession unchecked.
9. In the Grant type section, ensure that Authorization Code and Refresh Token are selected.

10. In the Sign-in redirect URIs section, enter a redirect URL. Users are redirected to this URL after they successfully sign in with Okta. The URL should use the following format:

    https://COMMAND_HOSTNAME/COMMAND_PORTAL_PATH/callback/AUTH_SCHEME

    Optionally, you can elect a URL to direct your users to when they end a session by populating a Sign-out redirect URI.

11. Replace the following fields:
    • COMMAND_HOSTNAME: The public hostname of Command, e.g. command.yourcompany.com.
    • COMMAND_PORTAL_PATH: The path to the Command Portal. This is usually either KeyfactorPortal or Keyfactor/Portal.
    • AUTH_SCHEME: A unique, URL-friendly identifier used to distinguish the identity provider in Command's authentication flow. E.g., you could use Okta. Make sure that you take note of the value used here; it will be used later.
12. In Controlled access, select Skip group assignment for now.
13. Click Save to save the app integration.

Step 2: Create an access policy on the authorization server

This section provides the steps to create an access policy on an authorization server to define access and refresh token lifetimes. Access policies in Okta are specific to a particular authorization server and the app integrations that you designate. Only basic configuration is described in this section, and you may find that your authorization server already has an access policy that covers your use case. Please refer to Okta's access policy guide for more information.

1. Sign in to the Okta Admin Console.
2. Go to Security > API.
3. Select the authorization server that you wish to use to sign users into Command. If you don't have any custom servers, select the default authorization server.
4. Select the Access Policies tab.
5. Click Add New Access Policy.
6. In the Name field, name the access policy something descriptive, such as "Command Access Policy".
7. In the Assign to section, select The following clients.
8. Start typing the name of the app integration created earlier, e.g. Command.
9. Click Create Policy.
10. You will then need to create a rule on the access policy. Select the name of the access policy that you created, and then click Add Rule.
11. In the Rule Name field, name the rule something descriptive. E.g., Command Access Rule.
12. In the IF Grant type is section, make sure Client Credentials and Authorization Code are checked.
13. Leave the default value for AND User is unless you have different organizational requirements.
14. In the AND Scopes requested field, select The following scopes, and then click OIDC default scopes. All OpenID Connect reserved scopes should appear in the box.
15. Leave the other options default, and then click Create rule.

Step 3: Configure claims on the authorization server

This section provides the steps to configure the claims that Okta will attach to JWT access and ID tokens issued by your authorization server. Keyfactor Command maps claims in JWT tokens to security roles. The claims used must be present on both the access and ID tokens. This section configures the groups claim on ID and access tokens and the email claim on access tokens. We don't configure the email claim on ID tokens in this section because, in a later section, we configure the requested scopes for the authorization code grant to include the email claim in ID tokens. If emails aren't globally unique in your organization, you may need to use a claim different than email. Please refer to Okta's Adding Custom Claims guide for more information on claims.

1. Sign in to the Okta Admin Console.
2. Go to Security > API.
3. Select the authorization server that you wish to use to sign users into Command. You should choose the same authorization server that you created the access policy on.
4. Select the Claims tab.
5. Click Add Claim.
6. In the Name field, enter groups.
7. In the Include in token type dropdown, select Access Token.
8. Set the Value type to Groups.
9. In the Filter section, add an appropriate filter. To include all of the user's groups in the groups claim, select Matches regex from the dropdown, and then enter .*.
10. In the Include in section, make sure Any scope is checked.
11. Click Create.
12. Repeat steps 1-6.
13. In the Include in token type dropdown, select ID Token.
14. You will then need to add the email claim to the access token. To do so, click Add Claim.
15. In the Name field, enter email.
16. In the Include in token type dropdown, select Access Token.
17. Set the Value type to Expression.
18. In the Value field, enter user.email. If your organization uses a different profile attribute for a user's email, use that value.
19. In the Include in section, make sure Any scope is checked.
20. Click Create.

Optionally, you may wish to add other claims to access and identity tokens if you want to authorize users by claims other than group membership in Okta.

Step 4: Create a group in Okta and assign the app integration

In the previous sections, we created an app integration and configured Okta to attach the groups a user is a member of to the JWT ID and access tokens when they're requested from the authorization server. In this section, we'll create a group in Okta and assign the app integration to it. Please refer to Okta's Create a Group guide and Assign App Integration guide for more information.

In this section, we create a group called Command-Admins to demonstrate the process and mapping. This is for illustrative purposes.

1. First, create a group in Okta by accessing the Okta Admin Console. Then go to Directory > Groups.
2. Click Add group.
3. In the Name field, enter Command-Admins.
4. Click Save.
5. Next, assign the app integration to the Command-Admins group by clicking the Command-Admins group.
6. Click the Applications tab.
7. Click Assign applications.
8. Find or search for the app integration created earlier (e.g. Command), and then click Assign.
9. Click Done.
10. Finally, add users to the Command-Admins group by clicking the Command-Admins group.
11. Under the People tab, click Assign people.
12. Click the + button next to the users you wish to add to the Command-Admins group. For this guide, you should add at least your own user to this group.
13. Click Done.

Step 5: Add Okta as an identity provider in Command

This section provides the steps to add Okta as an identity provider in Command. Please refer to the identity provider documentation for more information on identity providers in Command.

1. Sign in to the Command Web Portal.
2. Go to ⚙️ (Settings) > Identity Providers.
3. Click Add.
4. On the Details tab, enter the following information.
   • In the Type dropdown, select Generic.
   • In the Authentication Scheme field, enter the value you used for AUTH_SCHEME when constructing the callback URL in the Okta app integration (e.g. Okta).
   • Give the identity provider a Display Name (e.g. Okta).
   • In the Permission Set dropdown, select an eligible permission set to apply to the identity provider. Refer to the permission set documentation for more information on permission sets in Command.
5. Click the Parameters tab.
6. Click Import Discovery Document.

7. In the Discovery Document URL field, enter the OIDC discovery document URL for the authorization server in Okta. Usually, this URL has the following format:

   OKTA_AUTHORIZATION_SERVER_ISSUER/.well-known/openid-configuration

   Replace the following field.

   • OKTA_AUTHORIZATION_SERVER_ISSUER: The issuer URL of the Okta authorization server used in the previous steps. You can find this URL by signing into the Okta Admin Console, going to Security > API, selecting the authorization server that you wish to use to sign users into Command, and then copying the URL in the Issuer field.
8. Click the Fetch button.
9. The dialog should populate the correct URL for Authority, AuthorizationEndpoint, TokenEndpoint, JSONWebKeySetUri, and UserInfoEndpoint.
10. Click Save.
11. Fill out the remaining fields on the Add Identity Provider Parameters tab, as follows:
    • NameClaimType: The name of the claim on the JWT ID token that Command should use for the signed-in user's name. Set this value to name.
    • UniqueClaimType: The name of a claim on JWT ID and access tokens that is globally unique in the authorization server. Command displays this value in the UI if the NameClaimType claim is empty in ID tokens. Set this value to email.
    • RoleClaimType: The name of the claim on JWT ID and access tokens that identifies which groups the user is a member of. Set this value to groups.
    • ClientId: The app integration's client ID in Okta. This is used by Command in the authorization code grant. You can find this by doing the following:
      1. In the Okta Admin Console, go to Applications > Applications.
      2. Click the App Integration created for Command in an earlier step.
      3. Use the value for Client ID in the Client Credentials section.
    • ClientSecret: A client secret on the app integration in Okta. This is used by Command in the authorization code grant. You can find this by doing the following:
      1. In the Okta Admin Console, go to Applications > Applications.
      2. Click the App Integration created for Command in an earlier step.
      3. In the Client Credentials section, click Generate new secret if a client secret doesn't exist.
      4. Use the Secret value.
    • Authority: The Issuer URL of the authorization server in Okta. Should have been populated by the OIDC Discovery Document import.
    • Timeout: The number of seconds a request to the Okta authorization server is allowed to take before timing out with an error. Set this to 60.
    • OIDCAudience: The expected value of the audience (aud) claim in ID tokens returned by the Okta Authorization Server in the authorization code grant. Okta sets the aud claim to the client ID of the app integration. Set this value to the value of ClientId.
    • AuthorizationEndpoint: The authorization URL of the authorization server in Okta. Should have been populated by the OIDC Discovery Document import.
    • TokenEndpoint: The Token URL of the authorization server in Okta. Should have been populated by the OIDC Discovery Document import.
    • JSONWebKeySetUri: The JSON Web Key URL of the authorization server in Okta. Should have been populated by the OIDC Discovery Document import.
    • UserInfoEndpoint: The user Info URL of the authorization server in Okta. Should have been populated by the OIDC Discovery Document import.
    • FallbackUniqueClaimType: The name of a claim on JWT ID and access tokens that is globally unique in the authorization server. Command displays this value in the UI if the NameClaimType and UniqueClaimType claims are empty in ID tokens. The sub claim is always returned on ID and access tokens in Okta. Set this value to sub.
    • OIDCScope: Additional scopes that Command should request when initiating the authorization code grant. Command automatically requests the openid and profile claims. Set this value to email offline_access. These additional scopes tell Okta to include a refresh token in the response and to include the user's email in an email claim on the ID token.
12. Click Save.

Step 6: Map the group in Okta to a security role in Command

In the previous sections, we prepared Okta by creating an app integration, access policy, configured claims in ID and access tokens with the groups claim, and created a group in Okta. Then, we added Okta as an identity provider in Command and mapped the groups claim to the role claim type. In this section, we'll create a claim in Command that maps to the group in Okta. Please refer to the Security Roles and Claims documentation for more information.

In this section, we use the group created earlier called Command-Admins to demonstrate the process and mapping. This is for illustrative purposes.

1. First, add a claim in Command for the Command-Admins group in Okta by signing in to the Command Web Portal.
2. Go to ⚙️ (Settings) > Security Roles & Claims.
3. Click the Claims tab.
4. Click Add.
5. In the Claim Type dropdown, select OAuth Role.
6. In the Claim Value dropdown, enter Command-Admins.
7. In the Provider dropdown, select Okta or the friendly name that you chose for Okta in the previous section.
8. Give the claim a Description (e.g. Command Admins).
9. Click Save.
10. Next, add the Command-Admins claim to a security role by clicking the Security Roles tab on the Security Roles & Claims page (⚙️ (Settings) > Security Roles & Claims).
11. Create or modify a security role.
12. Double-click the security role that you would like to associate the Command-Admins Claim to. You can use the built-in Administrator role.
13. Click the Claims tab.
14. Click Add.
15. Select the Command-Admins claim.
16. Click Include and Close.
17. Click Save.

Step 7: Sign in and test access

Okta is now added as an identity provider in Command, and your user should have permission to sign in. To test access, enter the URL to Command with the Okta identity provider explicitly selected. Use the following URL format.

https://COMMAND_HOSTNAME/COMMAND_PORTAL_PATH/Login/Signin?idpHint=AUTH_SCHEME

Replace the following fields.

• COMMAND_HOSTNAME: The public hostname of Command (e.g. command.yourcompany.com).
• COMMAND_PORTAL_PATH: The path to the Command Portal. This is usually either KeyfactorPortal or Keyfactor/Portal.
• AUTH_SCHEME: The value you used for AUTH_SCHEME when constructing the callback URL in the Okta app integration and the authentication scheme of the identity provider in Command (e.g. Okta).

Following is what you should expect to happen when you enter this URL in your browser.

1. Unless you're already signed in to Okta in another browser session, you should be redirected to Okta.
2. Authenticate to Okta.
3. Your browser should redirect you back to the Command Portal, and you should see the Command Dashboard.