SSO, SCIM and forward auth

What you can do

• Sign members in through an OIDC identity provider for your email domains.
• Provision and deactivate members from your directory with SCIM.
• Put an Application’s Domain behind a sign-in at your identity provider, with forward auth.
• On a self-hosted instance, turn off password sign-in for everyone.

Set up single sign-on

Open Settings > Single sign-on.

1. Prove your email domain (Hosted)

   Under Proven domains, type the part of your people’s addresses after the @, such as northwind.example. Publish the TXT record it shows at your DNS provider and press Check now. Nothing polls, so press it again once the record is published, until the domain reads Proven.

   cloudgate.octabyte.app/settings/sso

   

2. Trust the provider's origin

   Under Trusted origins, add the scheme and host of your provider, such as https://login.northwind.example, and press Trust it. On the Hosted instance it must be a public address.

3. Add the provider

   Under Identity providers, press Add a provider. In Add an OIDC provider, fill in:

   • Provider id: lower-case letters, numbers and dashes, unique on the whole instance. It cannot be changed later.
   • Issuer URL, Client id and Client secret from your provider.
   • Email domains: comma separated, such as northwind.example. Members on these domains sign in through this provider.
   • Scopes and endpoints only if your provider needs them; left empty, its own defaults apply.

4. Register the redirect URI

   Copy the Redirect URI the dialog shows into your identity provider’s application settings.

People on your proven domains now sign in through your provider. Someone who arrives through SSO joins only that provider’s Organization.

Provision members with SCIM

1. Add a SCIM provider

   Under Directory provisioning (SCIM), press Add a provider, give it a Provider id and continue. Have somewhere to paste the token first.

2. Copy the base URL and token

   Copy the SCIM base URL and the Bearer token into your directory. The token is shown once.

Your directory now creates members and deactivates leavers. A member deactivated over SCIM cannot sign in, and only the directory can reactivate them. Removing a SCIM provider stops its token working immediately.

Put an Application behind forward auth

Forward auth runs an authentication proxy (oauth2-proxy) on a Server’s Traefik, so visitors to a Domain must sign in at your identity provider first. It needs an OIDC provider under Single sign-on.

1. Set an authentication domain

   Open Settings > Forward auth. For the Server, press Set an authentication domain, enter a host such as auth.northwind.example and its certificate, then Save the domain. Its parent domain becomes the cookie domain, so it must share one with the Applications it protects, and it needs DNS pointing at the Server like any other Domain.

2. Deploy the proxy

   Press Deploy the proxy, choose the provider under Authenticate against, and press Deploy it. Only OIDC providers are listed.

3. Gate a Domain

   Open the Application’s Domains tab and turn on the sign-in switch beside the host, such as shop.northwind.example.

What you cannot do

Related pages

• Members and roles: roles and grants for people who sign in.
• Domains: the Domains forward auth protects.
• Billing: moving to the Business plan.
• Instance settings: the Enterprise license on a self-hosted instance.
• Plans and prices and security.

Questions

Which identity providers work?

Any OpenID Connect provider, such as Okta, Entra ID, Auth0 or Keycloak. SAML providers cannot be added or edited in the console.

Why must I prove my domain?

On the Hosted instance, a provider signs in only addresses in a domain its Organization has proven with a DNS TXT record, so nobody can sign in as people at a domain they do not own.

What happens when the plan or license lapses?

SSO sign-in stops, so SSO-only people use Forgot password to get in. SCIM refuses new members. Forward auth keeps protecting what it already protects but refuses new setups and changes.