Single Sign-On (SSO)

superglue supports Okta sign-in through OpenID Connect (OIDC). Optional SCIM provisioning creates users, synchronizes groups, and deactivates access during offboarding.

Before you begin

You need:

An existing superglue organization and its organization ID.
An Okta administrator who can create an OIDC application and token claim.
A public superglue app URL that Okta can redirect users back to.
A role rule that maps every assigned Okta user to either admin or member.
An Okta SCIM 2.0 integration when you need lifecycle management.

Configure Okta

Create an application: In Applications → Applications, create an OIDC - OpenID Connect integration with Web Application as its type.
Enable the flow: Enable the Authorization Code grant and client-secret authentication. superglue also uses PKCE for the authorization flow.
Register the callback: Add https://<your-superglue-domain>/api/auth/oauth2/callback/okta as a sign-in redirect URI.
Assign access: Assign the users or groups that should be able to sign in.
Add the role claim: Configure an ID-token claim named userType or user_type. It must always return exactly admin or member for every assigned user.

Use a custom Okta authorization server so the role claim is included in the ID token issued during the authorization-code flow. Configure the claim as an ID Token claim, include it Always, and derive its value from the user profile or group policy used by your organization. Then use that authorization server’s issuer for OKTA_ISSUER, for example:

https://your-domain.okta.com/oauth2/default

For a group-based rule, create a superglue-admins group and use this claim expression:

isMemberOfGroupName("superglue-admins") ? 'admin' : 'member'

Okta’s custom-claim guide explains how to add and preview an ID-token claim. Custom authorization servers may require Okta API Access Management in production.

Configure superglue

Set the following deployment variables:

Variable	Value
`AUTH_PROVIDERS`	Include `okta`; use `okta` alone for an SSO-only login page
`OKTA_CLIENT_ID`	Client ID from the Okta application
`OKTA_CLIENT_SECRET`	Client secret from the Okta application
`OKTA_ISSUER`	Exact issuer of the authorization server that adds the role claim
`OKTA_ORG_ID`	Existing superglue organization that receives provisioned users
`OKTA_SCIM_TOKEN`	Optional SCIM bearer token copied into the provisioning integration
`AUTH_DISABLE_SIGNUP`	Required boolean controlling non-Okta self-service registration
`AUTH_DISABLE_INVITES`	Required boolean controlling organization invitations

For an SSO-only deployment:

AUTH_PROVIDERS=okta
OKTA_CLIENT_ID=...
OKTA_CLIENT_SECRET=...
OKTA_ISSUER=https://your-domain.okta.com/oauth2/default
OKTA_ORG_ID=...
AUTH_DISABLE_SIGNUP=true
AUTH_DISABLE_INVITES=true

Both account-creation flags must be set explicitly. Setting both to true is valid when Okta is configured because Okta just-in-time provisioning remains available. The deployment rejects that combination when no Okta provider is configured, as it would leave no account-creation path.

Configure SCIM provisioning

Set OKTA_ORG_ID, then run this command in Bash. It supports macOS, Linux, Git Bash, and WSL:

: "${OKTA_ORG_ID:?Set OKTA_ORG_ID first}"
od -An -N32 -tx1 /dev/urandom | tr -d ' \n'
printf '\n'

Store the opaque output as the OKTA_SCIM_TOKEN secret value. Copy the same value into Okta. Restart superglue after changing the value.

Configure an Okta SCIM 2.0 integration with these values:

Setting	Value
Base URL	`https://<your-superglue-domain>/api/auth/scim/v2`
Authentication	HTTP Header / bearer token
API token	The configured `OKTA_SCIM_TOKEN` value
Unique field	`userName`, using the user’s primary email address

Enable Create Users, Update User Attributes, and Deactivate Users in Okta. Assign the same users or groups to the OIDC and SCIM integrations.

Synchronize Okta groups

Enable Push Groups in the Okta provisioning settings. Then add each Okta group that must control superglue access.

Each pushed Okta group creates one custom role with the same name. Open Access Rules in superglue to configure that role’s resource grants. Okta controls the role’s users. superglue controls the role’s grants.

Group updates have these effects:

Adding or removing an Okta group member updates the custom role assignment.
Renaming an Okta group renames the custom role and preserves its grants.
Deleting a pushed Okta group deletes its custom role, assignments, and grants.

Group sync does not change the admin or member base role. The signed userType or user_type claim continues to control that role.

Okta group names must be unique in superglue. They cannot use the reserved names admin or member. Rename an existing custom role before pushing an Okta group with the same name.

Provisioning and role sync

On each successful Okta login, superglue:

Verifies the ID token against the configured issuer, client ID, and Okta signing keys.
Requires the email claim and a valid userType or user_type role claim.
Creates the superglue account on first login when SCIM has not created it already.
Adds or updates membership in the organization specified by OKTA_ORG_ID.
Assigns the admin or member base role from the token claim.

Existing users can also sign in with Okta. Other login methods remain available only when they are listed in AUTH_PROVIDERS.

Deprovisioning

When Okta deactivates an assigned user, it sends the SCIM state active: false. superglue then:

Bans the account, which blocks password, SSO, JWT, API key, and MCP OAuth access.
Deletes all Better Auth sessions and MCP OAuth grants.
Disables every API key owned by the user across organizations.
Disables every schedule created by the user across organizations.

Reactivating the user in Okta restores login access. It does not re-enable API keys or schedules. Review and enable those resources manually after reactivation.