Set up Okta for authentication with a client secret

Users in your Okta org can sign in to applications registered in SecureAuth Connect, using the account they already have. Okta acts as an external identity provider, following the Bring Your Own Identity (BYOID) model.

Two ways to connect Okta over OIDC

SecureAuth has two Okta OIDC templates, and they integrate with your Okta org differently.

With the connector in this guide, you register one Okta web application, and every SecureAuth application authenticates through it. Setup is short, and SecureAuth needs no administrative access to your Okta org.

With the other connector, SecureAuth holds an Okta service application with application management rights and creates an Okta application for each application you register. That is more to set up and more privilege to grant. In return, you can keep per-application sign-on rules in Okta.

	Okta	OktaV2
Application you register in Okta	API Services (machine to machine)	Web Application (OIDC)
Okta API scopes it needs	okta.apps.manage, okta.groups.read	None
How it authenticates	Private key	Client secret, or private key
Applications it creates in your Okta org	One for each application you register in SecureAuth	None
Per-application sign-on rules in Okta	Yes	No
Guide	Okta (OIDC, private key)	This guide

The Create Connection page shows a single Okta template, so you do not choose between them when you add a connection. To see which one an existing connection uses, check the Type column on the Identity Providers page. Okta has no matching label, so the difference is visible only on the SecureAuth side, or in what appears in your Okta org.

This guide covers the OktaV2 connector authenticated with a client secret, which is the common setup. The same connector can use a private key instead.

To connect Okta over SAML, read Okta (SAML).

Prerequisites

• Administrator access to your SecureAuth workspace.
• Administrator access to your Okta org, with permission to create an application integration.

You move between the SecureAuth admin portal and the Okta Admin Console during this setup, so keep both open.

Create the connection in SecureAuth

Start here rather than in Okta, because Okta needs the redirect URL that SecureAuth generates for the connection.

1. In your workspace, go to Authentication > Providers.

   note

   In the Agentic AI workspace, the same page is at Identity > Identity Providers.

2. Click Create Connection.

3. Select the Okta template.

   

4. Copy the Redirect URL. You paste this into Okta in the next section.

Leave this page open.

Create the Okta application

Switch to your Okta Admin Console.

1. Create a new App Integration.

2. For Sign-in method, select OIDC - OpenID Connect. For Application type, select Web Application. Click Next.

3. Enter a name for the application.

4. In Sign-in redirect URIs, paste the redirect URL you copied from SecureAuth, and remove the default entry. Okta calls this value a sign-in redirect URI; SecureAuth calls it a redirect URL.

5. For Assignments, follow your organization's usual practice for deciding who gets the application.

6. Save your changes.

7. Copy the Client ID and Client Secret.

Complete the connection in SecureAuth

Switch back to the SecureAuth admin portal, to the connection you started.

1. Fill in the form.

   Parameter	Description
   Name	Name for the connection. Users see this name when they choose how to sign in.
   Domain	Okta domain where the application is registered, similar to example.okta.com. Do not include the protocol.
   Client ID	Client ID of the application you registered in Okta.
   Authentication Method	Select Client Secret.
   Client Secret	Secret of the application you registered in Okta.

   

2. Save your changes.

3. Expand Advanced settings and check that the Get user info check box is selected. New connections have it selected by default, including connections created through the API without explicit attribute mappings, or whenever the attribute mappings are reset to defaults. If you pass your own mappings, set get_user_info explicitly.

   Okta's ID token does not carry the user's given name, family name, or email verification status, so SecureAuth reads them from the Okta user info endpoint instead. Without this option, those attributes stay empty.

   

4. If you changed anything, Save your changes.

Check the attributes and mappings

A new connection reads its attributes from two places and maps them to the authentication context for you:

Attribute	Source	Mapped to
name	ID token	Name
preferred_username	ID token	The primary username that represents the user
email	ID token	Email
groups	ID token	List of groups that user belongs to
given_name	User info	Given name
family_name	User info	Family name
email_verified	User info	Email verified

Open the Attributes and Mappings tabs to confirm the list. You need to change them only if you want to map more Okta claims.

note

Connections created before these defaults were introduced keep their original four ID token attributes and mappings. To add the user info ones, select + Add attribute on the Attributes tab with Source set to User info, then map each one with + Add mapping on the Mappings tab.

Use Okta groups in Agent Authority policies

Skip this section unless you use an Agentic AI workspace with SecureAuth Agent Authority.

The groups mapping above puts Okta's groups in the authentication context, but Agent Authority does not read them from there. It reads the workspace's groups claim, and that claim gets its groups from the identity pool by default. To use Okta's groups, have Okta send them, request them in SecureAuth, and point the claim at the authentication context.

Send groups from Okta

Okta does not put a user's groups in the ID token until you add a groups claim to the application. These steps are for Okta's built-in (org) authorization server, which the connection uses unless you clear Use Built-In Authorization Server. For a custom authorization server, see Okta's Add a custom groups claim guide.

1. In the Okta Admin Console, go to Applications and Resources > Applications and select the application you created.

2. On the Sign On tab, click Show legacy configuration, then click Edit under Group Claims.

3. For Groups claim type, leave Filter selected.

4. For Groups claim filter, leave the claim name as groups, select Matches regex, and enter .*.

   .* sends every group the user belongs to. To send only the groups your policies use, enter a narrower regular expression.

   

5. Click Save.

6. Click Back to applications, then select Refresh Application Data from the More menu.

Request the groups scope

Okta includes groups in the ID token only when the sign-in request asks for the groups scope. A new connection that uses Okta's built-in (org) authorization server requests groups by default, together with openid, email, and profile. Check the Scopes field under Advanced settings on the connection's Configuration tab.

Add groups to Scopes yourself in either of these cases:

• The connection was created before groups became a default scope.
• The connection uses a custom authorization server. Define a groups scope on that server in Okta first. A custom authorization server rejects a sign-in request that asks for a scope it does not define.

Point the workspace groups claim at Okta's groups

1. Go to Identity > Token Claims and select the ID Tokens tab.

2. Click the groups row. Its Type is User, which means it reads groups from the identity pool.

   Edit this claim rather than adding a new one. Claim names must be unique, so a second groups claim is rejected.

3. Set Type to AuthN Context, and set Source to List of groups that user belongs to.

4. Click Update.

5. Leave User info only turned on for the groups row. This keeps groups out of the ID token while still returning them in the user info response, where Agent Authority reads them.

A claim has one source. After this change, the token carries only the groups that Okta sends. Groups you create by hand in the identity pool no longer reach Agent Authority.

Check that groups arrive

Sign in through Okta as a user who belongs to an Okta group. Then open the Users page in Agent Authority and confirm that the group appears in that user's Groups column. If it doesn't appear yet, read When a group change takes effect.

Set up just-in-time provisioning

Just-in-time provisioning creates a user record the first time someone signs in through Okta. You do not add users by hand or migrate them ahead of time.

1. Select the Provisioning tab and choose Just-in-Time Provisioning. The other modes either discard users after they authenticate, or require you to create them ahead of time.

2. Under Identifier Correlation, leave Email selected on both sides. SecureAuth matches on this field to recognize a returning user instead of creating a second record for them.

   The email address is also added as a verifiable address with OIDC discovery verification. SecureAuth marks the address as verified when Okta reports email_verified as true.

3. Under Attribute Provisioning, click + Add row and set the rows so that incoming values land on the right user fields. The Email row is filled in for you from the identifier correlation.

   Okta attribute	User field
   Given name	First name
   Family name	Last name

   

4. Save your changes.

Verify the connection

Test the flow before you point users at it.

1. Click Try Sign-in, at the bottom of the connection's Configuration tab or at the top of the Identity Providers page.

2. Sign in as a user assigned to the Okta application.

3. Confirm that sign-in completes, and that the user appears in your workspace with their first name, last name, and email.

If the name fields are empty, check two things. Confirm that Get user info is selected, and that the given_name and family_name user info attributes are present on the Attributes tab.

See also

• Connect identity providers
• Okta (OIDC, private key)
• Okta (SAML)
• Standardize user attributes across identity providers
• Provisioning users from third-party identity providers to identity pools