Skip to content
Actagate

Set up SSO with Okta

This page is for organization owners and admins who want members to sign in to Actagate with their Okta account. You create an OIDC app in Okta, add a connection on the Actagate settings screen, test it, and then activate it.

Before you start, ask your operator to set SSO_SECRET_ENCRYPTION_KEY and WEB_BASE_URL (see Single sign-on basics). If your Okta org uses a custom domain, follow the generic OIDC steps instead of this page.

1. Create the app in Okta

Section titled “1. Create the app in Okta”
  1. In the Okta Admin Console, open Applications > Applications > Create App Integration. The creation dialog opens
  2. Choose OIDC - OpenID Connect as the sign-in method and Web Application as the application type. The app settings screen opens
  3. Enable only Authorization Code as the grant type
  4. Enter the temporary value https://<host>/api/auth/sso/callback/0 in Sign-in redirect URIs. The real URL is known after you save the connection in step 2
  5. Under Assignments, assign the admin who will run the test and the members who will sign in, then save. Okta creates the app
  6. On the General tab, turn on Require PKCE as additional verification. Leave Client authentication set to Client secret
  7. Copy the Client ID and the Client secret
  8. Copy the issuer. For the Okta org authorization server it is https://<org>.okta.com. For a custom authorization server, use the Issuer URI under Security > API > Authorization Servers (for example https://<org>.okta.com/oauth2/default)

Official documentation: Okta app integration guide

2. Add the connection in Actagate

Section titled “2. Add the connection in Actagate”
  1. Open Settings > Security (/ws/settings/security). Under Single sign-on, in “Pick a provider to add a connection”, open “Okta”. The connection form opens
  2. Enter “Display name”, “Issuer URL”, “Client ID” and “Client secret”, then press “Add connection”. The screen shows “Connection saved.” and a new connection marked “Draft · Not tested” appears under “Connections”
  3. Copy the “Callback URL to register in the IdP” shown on the connection. It looks like https://<host>/api/auth/sso/callback/<connection ID>
  4. Register that URL in Sign-in redirect URIs in Okta and delete the temporary value. Match the displayed value exactly, including the connection ID
Okta connection form
The connection form, with the provider hint, "Official setup guide", Display name, Issuer URL, Client ID and Client secret

The Okta preset accepts only an issuer whose host ends in .okta.com, .oktapreview.com or .okta-emea.com. Any other host returns invalid_issuer. After you save, the client secret is never shown again. The screen only says “Secret: set”.

3. Test

Section titled “3. Test”
  1. Press “Test” on the connection. The Okta sign-in page opens
  2. Sign in with your own Okta account. You return to the settings screen, which shows “Test passed. You can activate the connection.” The connection is now marked “Test passed”

The test runs the full authorization code flow with PKCE and checks the ID token signature, issuer, audience, expiry, nonce and sub. Your admin session stays as it is. The test creates no user and links no login method. If it fails, the screen shows a reason code.

4. Activate

Section titled “4. Activate”
  1. Press “Activate” on the connection. The screen shows “Connection activated. It is now available on the login screen.” and the status changes to “Active”

You can press “Activate” only after a test passes. Changing the Issuer URL, client ID or client secret clears the test result and returns the connection to draft.

5. Check sign-in

Section titled “5. Check sign-in”
  1. An invited member who is not an admin opens the login screen. A button labeled “Continue with ” is shown
  2. The member presses the button and signs in with Okta. The Actagate screen opens
  3. Check that a user who is not assigned to the app in Okta cannot sign in

On the first sign-in, Actagate matches the email address that the IdP marks as verified (email_verified) against the invited member’s email address. Owners and admins sign in with an existing method first, then link the connection with “Add ” under Settings > Login methods.

6. Troubleshooting

Section titled “6. Troubleshooting”
  • invalid_issuer: you entered an Okta custom domain. Connect again with generic OIDC
  • provider_rejected: check the Okta Assignments and the URL in Sign-in redirect URIs
  • token_exchange_failed: check the client ID and client secret
  • issuer_mismatch: the issuers of the org authorization server and a custom authorization server are mixed up. Enter the issuer exactly as Okta shows it

Other reason codes are listed in SSO troubleshooting.