Okta Directory

Antenna syncs your Okta directory to keep contributor identities, emails, employment details, and groups current. Use it to resolve Git, project tracker, and AI tool accounts to the same person without maintaining a manual user list.

This is an API Service integration and is separate from Antenna’s Okta Single Sign-On integration. SSO controls how users log in to Antenna; the Okta Directory integration reads your directory for identity resolution. You can use either one on its own, or both together.

Choose an app

You can connect with either of two Okta apps:

	Okta Integration Network (OIN)	Enterprise-managed
Who creates the app	Install Antenna from the OIN	You create an API Services app in your Okta org
Users Antenna can read	Every user in your org	Only users in the groups you choose
Profile attributes Antenna can read	All	Only the attributes you allow
Groups	Synced	Optional
Authentication	Client secret	Antenna signs requests with a key; Okta fetches the public key from a URL Antenna gives you

Choose Enterprise-managed if your security review requires limiting Antenna to a subset of users or attributes.

Prerequisites

Okta super administrator access: to install OIN apps, or to create API Services apps and custom admin roles
Admin access to your Antenna organization

Required permissions

The integration requests read-only scopes:

Scope	Purpose
`okta.users.read`	Read users and their profile attributes
`okta.groups.read`	Read groups and their memberships to create identity groups in Antenna. Optional for enterprise-managed apps.

Setup (Okta Integration Network)

Install Antenna from the OIN

In the Okta Admin Console, go to Applications and Resources > API Service Integrations.
Click Add Integration.
Select Antenna, then click Next.

Antenna is an API service integration, so it is listed under Applications and Resources > API Service Integrations rather than in the app catalog. See Okta’s Add an API Service Integration guide for details.

Install and authorize

On the Authorize step, review the requested permissions — reading users’ profiles and reading groups and their members — and click Install & Authorize.

Copy your credentials

Okta opens the integration’s General tab with the Copy your client secret dialog already open.

Click Copy to clipboard and store the client secret somewhere safe, then close the dialog.
Under Client Credentials, copy the Okta Domain and Client ID.

The client secret appears only once. If you close the dialog without copying it, click Generate new secret under Client Secrets to create a new one.

Connect in Antenna

In app.antenna.dev , go to Settings > Sources, click Add source, and select Okta Directory.
Keep Okta Integration Network selected, and enter your Okta domain, Client ID, and client secret.
Click Connect.

Setup (Enterprise-managed)

Copy your JWKS URL from Antenna

In app.antenna.dev , go to Settings > Sources, click Add source, and select Okta Directory.
Click Enterprise-managed, then click Copy next to JWKS URL. Keep this window open.

The URL is unique to your enterprise, for example https://app.antenna.dev/enterprises/acme/okta/jwks. It serves only the public half of a key that Antenna holds for your enterprise.

Create an API Services app in Okta

In the Okta Admin Console, go to Applications > Applications and click Create App Integration.
Select API Services, name the app (for example, “Antenna Directory”), and click Save.
On the General tab, click Edit under Client Credentials. Set Client authentication to Public key / Private key.
Under Public keys, select Use a URL to fetch keys dynamically, paste the JWKS URL, and click Save.
Under General Settings, clear Require Demonstrating Proof of Possession (DPoP) header in token requests and save. Antenna authenticates with a signed key (private_key_jwt) but does not send DPoP proofs, so it requires this setting off.
On the Okta API Scopes tab, click Grant for okta.users.read. Grant okta.groups.read only if you also complete Sync groups (optional) below; without matching role access, the connection check fails.

Antenna checks which scopes are granted when you connect. If you grant okta.groups.read later, disconnect and reconnect Okta Directory in Antenna to start syncing groups.

Limit the users Antenna can read

Go to Security > Administrators > Resources and click Create new resource set.
Click Add resource, choose Users, select Users from the following groups, and pick the group to sync (for example, everyone who reports to your CIO).
Go to the Roles tab and click Create new role. Under User, select only View users and their details.
Open the API Services app’s Admin roles tab and click Edit assignments. Select the custom role, select the resource set, and click Save changes.
On the same tab, remove any other role, including Super Admin. Okta can assign Super Admin to new service apps automatically when Public client app admins is turned on, and a broader role overrides the limits above.

Add the group under the Users resource type, not Groups. Choosing the group under Groups gives access to the group itself, not its members, and Antenna sees no users.

Limit the attributes Antenna can read (optional)

Go to Security > Administrators > Roles and edit the role.
Under View users and their details, click Add conditions.
Choose Include and select the attributes Antenna may read.

Okta does not let conditions hide first name, last name, username, primary email, or mobile phone, so Antenna can always read those. Include at least login and email, which Antenna uses to match people. Antenna also uses displayName (or firstName and lastName), title, manager, department, division, organization, secondEmail, city, state, countryCode, employeeNumber, and any attribute you map under Field mapping. Excluded attributes stay blank in Antenna. Include is safer than Exclude, because attributes you add to Okta later stay hidden until you include them.

Sync groups (optional)

A Users resource set gives access to users in a group, not to the group itself. To sync groups too:

Edit the custom role and, under Group, select View groups and their details.
Edit the resource set, click Add resource, choose Groups, and select the groups to sync.
Grant okta.groups.read on the app’s Okta API Scopes tab.

Connect in Antenna

Back in Antenna, enter your Okta domain and the app’s Client ID from its General tab.
Click Connect.

Antenna validates the connection when you connect, so invalid credentials or a missing scope are rejected immediately. After connecting, Antenna imports your directory and then refreshes it automatically.

Data collected

Antenna reads user records and their profile attributes, including name, email, username, status, and manager. With an enterprise-managed app, Antenna reads only the users and attributes your custom admin role allows. We use these to match directory users to your Git, project tracker, and AI tool accounts. Antenna also reads Okta groups and their memberships to create groups that you can use to filter enterprise data, unless an enterprise-managed app was not granted okta.groups.read.

Antenna only reads from Okta. We never create, update, deactivate, or delete Okta users or groups, and we do not write any data back to your directory.

Field mapping

Choose which Okta profile attributes fill each identity field in Antenna. Go to Settings > Sources, click Configure on Okta Directory, and use the Field Mapping card. Each row has:

Antenna field: the identity field the row fills.
Okta attribute: the Okta profile attribute copied into the field, or Don’t sync to leave the field alone.
Existing values: what happens when the field already has a value.
Example: what the saved mapping writes for one user from your directory.

Fields you can map

Antenna field	Default Okta attribute
Display Name	Don’t sync
Email	`email`
Role	`title`
Manager	Don’t sync
Team(s)	Don’t sync
Department	`department`
Cost Center	`costCenter`
Company	`organization`
Employment Type	Don’t sync
Location	`city`, `state`, and `countryCode`, joined (for example, “London, England, GB”)
Product Line(s)	Don’t sync
Seniority	Don’t sync

The Okta attribute list includes every attribute Antenna has seen on your users’ Okta profiles, including custom attributes such as jobLevel. A new attribute appears after the next sync.

Team(s) and Product Line(s) split values on commas and semicolons, so Billing, Payments becomes two teams.
Manager expects an attribute that identifies the manager, such as managerId. Antenna matches the value to another Okta user by Okta user ID, username, email, or employee number, and sets the manager to that user’s Antenna identity. If the value matches no one, or matches more than one user, the current manager is kept.
The card picks one attribute per field. The default Location mapping is the only one that combines several attributes, and the card shows it as city. Saving the card keeps only the attribute selected.

Existing values

Option	Behavior
Only fill empty	Writes the field only when it is blank.
Update unless edited (default)	Fills blank fields and keeps values that came from Okta up to date. Values someone edited in Antenna are kept.
Always overwrite	Always writes the Okta value, replacing manual edits.

An empty Okta value never clears a field. If a user’s attribute is blank in Okta, the field keeps its current value in Antenna.

When changes apply

Clicking Save or Reset to defaults starts a sync right away. If a sync is already running, another one starts when it finishes. After that, the directory syncs automatically every 2 hours. Reset to defaults restores the mappings in the table above.

Rotate credentials

Enterprise-managed apps have no client secret to rotate. Antenna holds the key, and Okta fetches the public key from your JWKS URL.

For an OIN app, rotate the client secret if it is lost or exposed:

In Okta, go to Applications and Resources > API Service Integrations and select the Antenna integration.
In the Client Secrets section of the General tab, click Generate new secret and copy it.
In Antenna, go to Settings > Sources and click Configure on Okta Directory. Click Update credentials, enter the new client secret, and click Update credentials to save it.
Once the sync succeeds, set the previous secret to Inactive in Okta and delete it.

Your Okta domain and client ID do not change when you rotate the secret.

Disconnect

In Antenna, go to Settings > Sources and click Configure on Okta Directory. Open the More actions (...) menu, click Disconnect, and confirm.
In Okta, go to Applications and Resources > API Service Integrations, select the Antenna integration, and click Revoke to remove the granted scopes. For an enterprise-managed app, deactivate the API Services app under Applications > Applications instead.

Disconnecting stops all future syncs. Previously imported identities remain in Antenna so your historical metrics stay intact.

Troubleshooting

Issue	Resolution
Invalid credentials when connecting	Confirm the client ID and secret come from the same Antenna integration, and that the secret is still active in Okta.
Lost client secret	The secret is shown only once. Rotate the credential to generate a new one.
Insufficient scope errors	Reopen the integration under Applications and Resources > API Service Integrations in Okta and confirm both `okta.users.read` and `okta.groups.read` are granted. Re-run Install & Authorize if either scope is missing.
Users missing from Antenna	Deactivated and suspended users may be excluded. Confirm the user is active in Okta and wait for the next sync to complete.
Enterprise-managed app syncs no users	Confirm the resource set uses the Users resource type with Users from the following groups, not Groups, and that the role and resource set are assigned to the app together.
”The DPoP proof JWT header is missing”	Clear Require Demonstrating Proof of Possession (DPoP) header in token requests on the app’s General tab.
”must use the private_key_jwt token_endpoint_auth_method”	The app is a custom API Services app, which can’t use a client secret. Choose Enterprise-managed in Antenna and set the app’s Client authentication to Public key / Private key.
”The client does not have a JWKSet configured”	Under Public keys on the app’s General tab, select Use a URL to fetch keys dynamically, paste your JWKS URL from Antenna, and click Save.
Sync stopped unexpectedly	Verify the integration is still active in Okta and that the client secret has not been rotated or revoked.

Support

If you need help connecting or verifying your directory sync, contact us at support@antenna.dev.