Skip to main content

Single sign-on

Configure one OpenID Connect (OIDC) or SAML 2.0 provider per workspace. SSO is available on Norn Cloud and self-hosted Norn.

The setup flow is the same on Norn Cloud and a self-hosted instance. Only the Norn origin in the redirect, metadata, and ACS URLs is different; always use the URLs shown on the Authentication page.

Only a workspace administrator can configure it. Open Workspace settings → Authentication to begin.

Authentication page screenshot placeholder showing the protocol selector and redirect URI

Roll it out safely​

Use this order even if you intend to require SSO for everyone:

  1. Configure the provider in Norn and save it.
  2. Complete Test connection. Saving any later change clears the tested status.
  3. Have at least one workspace administrator connect their existing account through Workspace settings → Your provider → Connect your provider.
  4. Test the normal workspace sign-in URL in a separate browser session.
  5. Turn on Require single sign-on.
  6. Copy the eight recovery codes and store them somewhere that does not depend on your identity provider. They are shown once, and each code can be used once.

Norn will not enable enforcement until a provider is configured, the latest configuration has passed a test, and at least one administrator has linked their provider identity.

OpenID Connect​

Register Norn with the provider​

Create a confidential web application in your provider and register this redirect URI exactly:

https://app.norn.so/v1/sso/oidc/callback

The provider must return a stable sub claim and an email address. Request openid email profile unless the provider requires different scope names. If you will map an administrator group, include the scope needed for the provider to return group membership.

Keep the provider's client ID and client secret for the next step. Do not put the client secret in source control, support requests, or screenshots.

Configure Norn​

Choose OpenID Connect, then enter:

  • Issuer URL — the provider's issuer, including any tenant or realm path.
  • Client ID and Client secret — from the application registered above.
  • Scopes — space-separated. Norn always includes openid; the default is openid email profile.
  • Groups claim — only when group membership is returned in a non-default claim.
  • Administrator group — optional; an exact matching group makes the person a workspace administrator at each sign-in.

Use Discover to load the authorization, token, JWKS, and user-info endpoints from the issuer. If the provider does not publish discovery metadata, turn on manual endpoints and supply the authorization endpoint, token endpoint, and JWKS URI. The user-info endpoint is optional because Norn can read claims from the ID token.

Turn on Create accounts on first sign-in only if everyone accepted by the provider should be allowed to join the workspace. Save the provider, then select Test connection and finish the provider round trip.

OpenID Connect settings screenshot placeholder for a completed discovery

The workspace sign-in URL is:

https://app.norn.so/sso?workspace=your-workspace-slug

SAML 2.0​

Add the identity provider to Norn​

Choose SAML 2.0. Norn can read the provider configuration from:

  • a metadata URL;
  • pasted metadata XML; or
  • an entity ID, sign-in URL, and signing certificate entered manually.

For manual configuration, the certificate can be PEM or bare Base64. Norn reads its expiry date and reports it in the Authentication page.

The assertion must contain a durable NameID and an email address. If no email attribute is mapped, Norn recognizes common email, mail, LDAP, and Microsoft claim names, and can use an email-shaped NameID. Name and groups mappings are optional. Set explicit attribute names when the provider uses custom claims.

Leave Allow identity provider-initiated sign-in off unless the provider must start the flow. Provider-initiated requests cannot be tied to a sign-in request created by Norn, so the default is the safer service provider-initiated flow.

Save the provider. Norn creates a signing key pair for the workspace on the first save and then shows its service provider metadata URL.

Add Norn to the identity provider​

Use the values shown by Norn. Their format is:

Provider fieldNorn value
Metadata URLhttps://app.norn.so/v1/sso/saml/your-workspace-slug/metadata
Entity IDThe same metadata URL
Assertion consumer service (ACS) URLhttps://app.norn.so/v1/sso/saml/your-workspace-slug/acs

Importing the metadata is preferred because it includes the ACS URL and Norn signing certificate. If the provider requires service provider values before Norn can be saved, enter the deterministic URLs above first, save Norn, and then import or update the provider from Norn's metadata.

Configure the provider to sign assertions and release a durable subject and email. Release the group attribute too when using Administrator group. Return to Norn and complete Test connection.

SAML settings screenshot placeholder showing Norn metadata and certificate status

Account creation and identity linking​

With Create accounts on first sign-in off, only existing workspace members can sign in. An administrator must invite a person before their first SSO attempt. With it on, a person accepted by the provider gets an active Norn account and joins the workspace on first sign-in.

An existing account that has a password, or belongs to another workspace, cannot be claimed by matching its email address alone. The person must sign in normally and choose Connect your provider in workspace settings. After linking, Norn identifies OIDC users by issuer and sub, and SAML users by provider and NameID—not by a later email match.

When Administrator group is set, Norn applies that role at every sign-in. People outside the group are members. Norn will not demote the workspace's last administrator.

Require SSO​

After completing the safe rollout, turn on Require single sign-on in the Authentication page. A Norn password will no longer open that workspace. Password access to other workspaces is unchanged, and API tokens and agents continue to work.

SSO enforcement screenshot placeholder without recovery codes

If the provider becomes unavailable, a recovery code lifts the workspace requirement so passwords work again. Disabling enforcement invalidates all remaining codes.

Change or remove a provider​

Saving a configuration change requires another successful test before enforcement can be enabled. Choosing the other protocol and saving replaces the current provider. Removing the provider stops new SSO sign-ins immediately, but does not terminate existing sessions. Confirm that affected people have another way to sign in before replacing or removing it.

Troubleshooting​

OIDC discovery or redirect fails​

  • Confirm the issuer is exact, including its tenant or realm path.
  • Confirm the provider allows the exact Norn callback URL; path and scheme differences matter.
  • If discovery is unavailable, verify the authorization, token, and JWKS endpoints individually.
  • On a self-hosted instance, confirm NORN_APP_BASE_URL is the public HTTPS origin and that the Norn processes can reach the provider.

Sign-in succeeds at the provider but Norn rejects it​

  • OIDC must return a stable sub and email. SAML must return a durable NameID and email.
  • Confirm the configured email, name, and groups claim names match the assertion or token.
  • If just-in-time account creation is off, invite the person first.
  • If an existing password account is not linked, sign in with the password and use Connect your provider.

SAML validation fails​

  • Refresh provider metadata after a certificate rotation, or replace the manual certificate.
  • Confirm assertions are signed and intended for Norn's entity ID and ACS URL.
  • Keep the Norn host and provider clocks synchronized. Norn allows at most three minutes of clock skew when validating assertion conditions.
  • Retry from Norn unless provider-initiated sign-in was deliberately enabled.

Enforcement is unavailable​

The Authentication page states which prerequisite is missing: a saved provider, a successful test of the current configuration, or a linked administrator. Complete that item and reload the page.