Custom Identity Provider

Your organization can connect its own OpenID Connect identity provider, so your team, your customer portal, or an individual customer signs in to Distr with accounts they already have. Provisioning, password policies and multi-factor authentication then stay in that identity provider.

Note

A custom identity provider is available on the Business plan and requires a custom domain, because a provider is only offered on the domain it is attached to. See the pricing page for a comparison.

Where a provider applies

Every domain carries its own set of providers. Nothing is inherited between them, so a user’s sign-in options are decided entirely by the host they open:

Domain	Providers configured by	Applies to
Your app domain, e.g. app.your-company.com	you	your own team
Your customer portal domain	you	all of your customers, including ones created later
A customer’s own portal domain	you or that customer	that one customer

All three are configured under Settings → Organization → Custom Domains & Identity Provider, which is also where the domains themselves are registered. A customer’s own domain additionally needs the Custom Identity Provider feature, which you grant per customer in the customer list.

Domains added anywhere show a status panel next to them — green once the CNAME resolves to the expected target, red with the reason otherwise — so you can tell without leaving the page whether a provider is actually reachable yet.

Requirements

1. A custom app domain (e.g. app.your-company.com) set up under Settings → Organization → Custom Domains & Identity Provider, and an organization slug, because both are part of every provider’s URLs.
2. An identity provider that serves an OpenID configuration under <issuer>/.well-known/openid-configuration. Microsoft Entra ID, Google Workspace, Okta, Auth0, Keycloak, JumpCloud, Authentik and any other OpenID Connect provider work with the same fields.
3. An application (client) registered with that provider, using the authorization code flow.

Connecting your identity provider

Go to Settings → Organization → Custom Domains & Identity Provider and add a provider:

1. Display name: Shown on the sign-in button, e.g. Acme SSO.
2. Slug: Identifies the provider in its URLs, unique within your organization, e.g. acme-sso. Changing it later changes both URLs, so your provider needs the new redirect URI.
3. Issuer URL: The provider’s issuer. Distr fetches its OpenID configuration when you save, verifies that the document belongs to that host, and stores the issuer exactly as the provider states it. So a URL that is a little off is corrected rather than rejected.
4. Client ID and Client secret: From the application you registered. The secret is never shown again; leave the field empty when editing to keep it.
5. Copy the Callback URL and register it as a redirect URI with your provider.

The URLs of a provider are built from your organization slug and the provider slug:

https://app.your-company.com/api/v1/auth/oidc/custom/<organization-slug>/<provider-slug>
https://app.your-company.com/api/v1/auth/oidc/custom/<organization-slug>/<provider-slug>/callback

The additional scopes (profile email by default) and PKCE are prefilled sensibly: PKCE is used automatically when the provider announces support for it.

Issuer URLs for the most common providers:

Provider	Issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant-id>/v2.0
Google	https://accounts.google.com
Okta	https://<your-org>.okta.com (or /oauth2/<server-id>)
Auth0	https://<your-tenant>.eu.auth0.com/
Keycloak	https://<your-host>/realms/<realm>

Microsoft Entra ID needs your tenant ID

The common, organizations and consumers endpoints cannot be used: their OpenID configuration does not name a tenant, so the tokens they issue cannot be verified against a single issuer. Use the single-tenant issuer with your directory (tenant) ID.

Customer portal domain

A customer portal domain (e.g. portal.your-company.com) is the host all of your customers sign in on. Register it in the Customer Portal section of the Custom Domains & Identity Provider tab and create the shown CNAME record.

Once it exists, it replaces your app domain in everything sent to a customer user: invitation links, password resets, email verification and notification mails. Your own team keeps the app domain, and agent manifests, connect commands and the artifact registry keep using it as well.

Providers you attach to this domain apply to every customer at once. You cannot single out one customer here; a customer that needs its own provider gets its own domain instead.

No automatic provisioning on the shared portal domain

A provider on the shared customer portal domain cannot create accounts on first sign-in. Nothing in an OpenID response says which of your customers a new user belongs to, so there is no organization to create them in. Invite them, or give that customer its own portal domain.

Letting a customer bring its own provider

Grant a customer the Custom Identity Provider feature in the customer list. Its administrators then get a Settings page of their own, where they register their own portal domain and connect their own provider. You can reach the same page from the Settings button in the customer list and configure it on their behalf.

A provider on a customer’s own domain only ever authenticates users of that customer, and accounts created on first sign-in join that customer organization and count against its user limit rather than your billed seats.

The feature can only be granted while your own plan includes custom identity providers.

Who can sign in

Distr matches an account either by an identity it has connected before or by the email address the provider asserts. Two rules make sure a provider never reaches an account outside the organization it belongs to:

• An account that is also a member of another Distr organization cannot sign in through a custom provider. Such members keep their password login. The settings page reports how many of your members this affects, so you can see it before you switch anyone over.
• An account that has signed in through a custom provider cannot create another organization or be invited into one, and it cannot be invited into your organization if it already belongs to another one.

Two consequences worth planning for

These rules are what stops a provider from reaching another organization’s data, so they apply to every custom provider, including a customer’s own. Two things follow that are easy to be surprised by:

• A person who is a customer user of two Distr vendors is a member of two organizations and can therefore use single sign-on at neither of them. They keep their password login at both.

• As soon as any provider is configured in your organization, including one configured by a single customer, you can no longer invite anyone who is already a member of another Distr organization. Removing that member from the other organization, or deleting the provider, makes the invitation possible again.

Provisioning accounts automatically

With Create accounts on first sign-in, everyone the provider authenticates gets an account with the role you select, so you do not have to invite people one by one. Where such an account lands depends on the domain the provider is attached to: your app domain creates a member of your own team, a customer’s own portal domain a user of that customer.

• Allowed email domains are therefore required for this: an account created this way is not something to hand out to every address an identity provider can assert. Accounts are only created for addresses in the domains you name here; existing members sign in regardless of their address.
• Accounts for your own team are created up to your billed user seats, accounts for a customer up to that customer’s user limit. Limits are never raised automatically: beyond them, sign-in fails until an administrator raises them.
• The shared customer portal domain cannot provision accounts at all, as described above.

Making a provider the default

With Sign in with this provider automatically, the login page on that domain redirects to the provider without asking. Only one provider per domain can do this.

This is usually not recommended: everyone reaching the domain is sent to the provider and never sees the login form, even though some of them have a password rather than an account in that directory.

https://app.your-company.com/login?manual=1 still shows the login form. That is how anyone with a password gets in while the provider is unavailable, so keep at least one administrator with a password and a working recovery method.

Signing in on app.distr.sh

Your users can sign in on app.distr.sh with their password as before; they are then forwarded to your custom domain. Your own identity provider is only offered on your domain, because the login page of the shared host cannot know which organization a visitor belongs to before they identify themselves.

Removing a provider

Deleting a provider removes the connected identities with it. Everyone who signed in through it loses that login, and users who never set a password have to reset it before they can sign in again.