Okta Single Sign-On

Antenna supports OpenID Connect (OIDC) and SP-initiated SSO via Okta.

Prerequisites

Make sure you are logged in to Okta as an administrator.
Make sure you have an existing Antenna account and enterprise.
Your enterprise must be on the Business or Enterprise plan. Our Okta integration is not available on the free trial.

Supported Features

IdP-initiated SSO (through Third-party Initiated Login )
SP-initiated SSO (Single Sign-On)
Just-In-Time provisioning

For more information on the listed features, visit the Okta Glossary .

Configuration Steps

Go to the Antenna integration in the Okta marketplace.
Click Add this integration.
On the Antenna application’s Assignments tab in Okta, assign yourself and everyone who needs access to Antenna. Assigning a group, such as your engineering group or Everyone, is the simplest way to cover everyone.
On the Okta admin page, click on the Antenna application and navigate to the Sign On tab.
Copy the values of Issuer, Client ID, and Client Secret.
On app.antenna.dev , go to Settings > SSO.
Click Configure next to Okta.
Paste the Issuer, Client ID, and Client Secret (from step 5) and click Save.
Click Activate.

Once you complete these steps, all enterprise members will be required to log in through Okta to access Antenna, including the administrator that set up Okta.

Warning

After you activate Okta, members who are not assigned the Antenna application in Okta cannot sign in, even if they already have an Antenna account. Assign everyone who needs access before you click Activate.

Important

Keep existing members in Settings > Members when you turn on Okta. Do not delete them.

The first time a member signs in with Okta, Antenna sends a one-time verification code to the email address on their Okta account. If that email matches their existing Antenna email, entering the code links the Okta login to their existing account, and they keep their assigned role.

If you delete a member before they sign in with Okta, they are provisioned again as a new member on their first Okta login and receive the default role (Contributor) instead of their previous role.

If a member cannot receive the verification email, you can change their email address in Antenna to a variant such as john.doe+email@company.com before they sign in with Okta. Their Okta login then creates a new account, so you will need to assign their role again.

Roles and Permissions

Permissions are managed in Antenna, not in Okta. Okta controls who can sign in — anyone assigned the Antenna application in Okta can log in — but it does not pass roles or groups to Antenna. Unlike Entra SSO, Okta group-to-role mapping is not supported.

Accounts are created through Just-In-Time provisioning, so a user joins the first time they sign in with Okta rather than when you assign them the application. Just-In-Time provisioning does not replace the assignment: Okta checks the assignment first, and only assigned users reach Antenna to be provisioned. New members join as Contributor, except the administrator who sets up and verifies the Okta connection, who becomes an Admin.

To change a role, an Admin goes to Settings > Members, opens the member, and selects Admin, Director, Manager, or Contributor. See Roles and Permissions for what each role can access.

To grant a role before someone’s first login, invite them from Settings > Members and pick their role on the invite.

If your SSO connection is configured at the enterprise level, you can change the role new members receive with Default role for new members on the SSO settings page.

Setting a member to No Access revokes their access to Antenna without removing them, and signing in through Okta does not restore it. Reassign a role to give the member access again.

SP-initiated SSO

SP-initiated SSO occurs when a user has a pre-existing account in the enterprise and an enterprise Admin then enables Okta SSO.

Signing in with a password or another provider still succeeds, but it does not grant access to the enterprise. When the user opens any enterprise page, Antenna shows a screen stating that the enterprise requires them to log in with Okta.

From your browser, navigate to the Antenna sign-in page and sign in with your pre-existing credentials.
Open any page in your enterprise. You will see a screen asking you to log in with Okta.
Click Log in with Okta and enter your Okta credentials.
If your credentials are valid, you will be redirected to the page you were trying to open.

If you reach the sign-in page through your enterprise’s SSO flow, the sign-in page also shows a Log in with Okta button.

When a user’s Okta session expires, they see an SSO session expired screen the next time they open an enterprise page. Clicking Re-authenticate with Okta signs them in again and returns them to that page.

Troubleshooting

”This client cannot use a custom authorization server”

Verification fails and Okta returns unauthorized_client with the description This client cannot use a custom authorization server. This happens when the Issuer you pasted into Antenna points at an Okta custom authorization server (for example https://your-company.okta.com/oauth2/aus1a2b3c4d) that the Antenna application is not allowed to use.

You have two options:

Use your org authorization server. In SSO settings, change the Issuer to your Okta org URL without the /oauth2/... suffix (for example https://your-company.okta.com), then verify again. Antenna only requests the openid, email, and profile scopes, so a custom authorization server is not required.
Allow the Antenna app on the custom authorization server. In the Okta Admin Console, go to Security > API > Authorization Servers, open the authorization server in your issuer, and on the Access Policies tab add or edit a policy that is assigned to the Antenna application. The policy needs a rule that allows the authorization code grant with the openid, email, and profile scopes for the users who sign in to Antenna. This option requires Okta API Access Management.

Note

Security > API is only available in Okta orgs that license API Access Management. If you do not see it, use your org authorization server issuer.

”User is not assigned to the client application”

Okta returns access_denied with the description User is not assigned to the client application when the person signing in is not assigned the Antenna application in Okta. Antenna shows Okta did not allow you to sign in to Antenna. Okta blocks the sign-in before it reaches Antenna, so Antenna cannot link or create their account.

In the Okta Admin Console, go to Applications > Applications, open the Antenna application, and on the Assignments tab assign the user or a group they belong to. They can then sign in again.

”Verification error. Please double check your client secret and try again.”

The Client ID or Client Secret in Antenna does not match the Okta application, or the secret has been rotated in Okta. Copy both values again from the Sign On tab of the Antenna application in Okta and save them in SSO settings.

Removing Okta SSO

After activating Okta SSO, you will see the enabled connection and an option to remove it on the SSO settings page for your enterprise on Antenna.

If you remove SSO from your enterprise, all SSO users will lose login access to Antenna. Any SSO users currently logged in will have their session expire within 8 hours.

You can add Okta SSO back at any time.