Set up SSO with generic OIDC

This page is for organization owners and admins who want members to sign in to Actagate with their IdP account. You create an app in an IdP that is not on the list (Keycloak, Okta with a custom domain, and so on), add a Generic OIDC 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).

The IdP must meet these conditions:

• It publishes discovery at <issuer>/.well-known/openid-configuration
• It supports PKCE with S256 (code_challenge_methods_supported in discovery includes S256)
• Client authentication at the token endpoint is client_secret_post or client_secret_basic
• Discovery, the token endpoint and JWKS are reachable over HTTPS from the internet

1. Create the app in the IdP

1. In the IdP, create an OIDC client for a web application (a confidential client)
2. Allow the authorization code flow and turn on PKCE with S256
3. Enter the temporary value https://<host>/api/auth/sso/callback/0 as the redirect URI. The real URL is known after you save the connection in step 2
4. Allow the scopes openid, profile and email. Make sure the ID token contains sub, email and email_verified
5. Give the admin who will run the test and the members who will sign in access to the app
6. Copy the client ID, client secret and issuer

Official documentation: OpenID Connect Discovery 1.0

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 “Generic OIDC”. 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 redirect URIs in the IdP and delete the temporary value. Match the displayed value exactly, including the connection ID

The connection form (Okta example). The Generic OIDC form has the same fields: the provider hint, "Official setup guide", "Display name", "Issuer URL", "Client ID" and "Client secret"

The issuer is an absolute URL that starts with https://. User info (user:pass@), a query and a fragment are not allowed. One trailing / is removed when you save. Nothing else changes, including letter case and the path. The issuer in discovery must match the saved value, and the only difference allowed is that one trailing /. Actagate reads the token URL and the other endpoints from discovery, so there are no fields for them.

After you save, the client secret is never shown again. The screen only says “Secret: set”.

3. Test

1. Press “Test” on the connection. The IdP sign-in page opens
2. Sign in with your own IdP 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

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

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 the IdP. The Actagate screen opens
3. Check that a user who is not assigned to the app in the IdP 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

• discovery_failed: check that <issuer>/.well-known/openid-configuration opens in a browser
• unsafe_endpoint: discovery or an endpoint is not HTTPS, or points to an address on an internal network
• pkce_unsupported: turn on PKCE with S256 in the IdP
• unsupported_client_auth: set client authentication to client_secret_post or client_secret_basic
• invalid_identity: configure the IdP to put sub in the ID token

Other reason codes are listed in SSO troubleshooting.