How-to: Configure Deploy for Okta authorization

HCL DevOps Deploy (Deploy) uses Okta for secure authorization, which ensures that only authorized users and groups can access your applications.

During the authorization process, Deploy relies on the groups claim in your Okta access token realm to determine access rights. To enable this, you must complete the following tasks:
  • Define an authorization server within Okta.
  • Configure your Deploy authentication realm to refer to the Authorization Server OpenID URLs.

If you have an existing LDAP configuration, you can migrate it to use Okta. See Migrating from an LDAP configuration.

Note: The configuration steps may vary as this integration uses an external identity provider. For detailed setups and up-to-date instructions, refer to the official documentation of Okta.

Configuring Okta

To set up your Okta integration, perform the following steps:
  1. Create an app integration in Okta.
    1. Navigate to the Okta Applications page.
    2. Create a new application specifically for Deploy if one does not exist.
    3. Copy the Client ID and Client Secret values. The values are used while configuring OpenID Connect settings in Deploy.
    4. Ensure that the sign-in redirect URIs include the Deploy callback URL, which is the configured External User URL in your Deploy system settings
  2. Define API Access in Okta.
    1. Navigate to Security > API in Okta.
    2. Create an authorization server, if necessary.

      Make sure that the authorization server is configured with the necessary claims and policies.

    3. Create an access policy.

      You must design an access policy with the set of users or groups that have permission to access Deploy.

    4. Configure the groups claim.
      Note: In the Authorization Server Claims section, ensure that you have enabled the groups claim. By enabling the groups claim, Okta includes group information within the authorization token. Deploy examines the Access Token for this claim.
  3. Obtain the Authorization Server Issuer URL.

    After your Authorization Server is configured, you can find the Issuer URL on the Authorization Server settings tab. Copy the URL as it is used while configuring OpenID Connect settings in Deploy.

  4. Configure the OpenID Connect settings in Deploy.
    You must configure the following fields while configuring the OpenID authentication realm in Deploy:
    • Client ID: The unique identifier for your Deploy application. The value is the same you copied in Step 1c.
    • Client Secret: The secure secret associated with your Deploy application. The value is the same you copied in Step 1c.
    • Issuer URL: The Issuer URL from your Authorization Server settings tab in Okta. The value is the same you copied in Step 3.
      Notes:
      • This is not the same set of URLs that you find on the App page of your Okta organization.
      • You can click Discovery to discover the OIDC URLs from the authorization server. See Creating authentication realms to configure the remaining fields.
  5. Manage User Groups in Okta.
    1. Create the necessary user groups within your Okta organization to align with your Deploy access policies.
    2. Assign users to the appropriate groups to ensure they receive the correct permissions.
    3. Verify that the authorization token reflects group memberships in the groups claim.

Troubleshooting

Token Previews: If you encounter issues, you must double-check the Issuer URL and other OIDC URLs in your Deploy configuration match the values from the Okta Authorization Server metadata.

Authorization Server Issuer: Ensure that the Issuer URL is copied correctly from the Authorization Server settings tab in Okta. You might find other Issuer URLs on the App page of your Okta organization, but these are not generally the correct URLs to use for Deploy configuration.

Migrating from an LDAP configuration

The methods to migrate from an LDAP configuration are as follows:
  • By creating a new authentication realm and migrating the users to Okta.

    This method requires manual intervention. A new set of Okta realms is created, and users and groups are automatically created when they authenticate for the first time. However, because the users and groups are considered new, they are not mapped to any permissions. The administrators must manually map the new groups to the appropriate teams and may opt to manually add groups from Okta to set those permissions proactively.

  • By modifying an existing configuration with LDAP authentication and authorization to use Okta instead.
    This method is seamless as an existing LDAP configuration has both an LDAP authentication realm and a corresponding LDAP authorization realm. Each realm contains its corresponding users and groups, respectively. So, as you modify both realms to use Okta, ensure that the users and groups are mapped properly.
    • Authentication Realm: You must ensure that the username derived from the Okta JSON Web Token (JWT) matches the username derived from LDAP. For LDAP, this username is the value used to log in and is determined by the attributed indicated by the User Search Filter field in the LDAP realm configuration. It is mainly the UID or SamAccountName. When configuring Okta, the Username Claim must track this value. The value is referenced as the sub claim in the JWT by default, but can be modified in the realm configuration.
    • Authorization Realm: The names returned by the groups claim in the Okta JWT must match the group names in the LDAP authorization realm. You can verify the group names from the Groups tab in the LDAP authorization realm configuration. The attribute used is configured by the User Group Attribute or Group Name field in your LDAP authorization realm settings, depending on how it is configured. Those group names must appear the same in the Okta UI to be properly mapped to the same groups in Deploy.