Skip to main content

Company SSO & Sign-In Buttons

A company can have its own identity providers, linked through the company's organization. Only that company's users are routed through them, and when the company has its own login domain those providers appear on the login page as one-click sign-in buttons — so those users never type an email address or a password.

Identity providers are linked to a company through that company's organization, not on the provider itself. Beak keeps organizations in Keycloak, and the link is stored there — so one place decides which providers a company uses.

  1. Open Companies and find the company.
  2. Choose Manage Organization.
  3. Add the identity providers that company signs in with. Remove any that no longer apply.

Once a company's organization links at least one provider, only those providers serve that company's users. A provider the organization does not link is never used for them, even if its allowed email domains would otherwise match.

A company whose organization links no providers does not narrow anything — the tenant's enabled providers apply, exactly as before organizations were configured. So a tenant that has not set up organizations is unaffected.

Note: There is no separate scope field on the Identity Provider itself. A provider serves whichever companies' organizations link it; the Identity Providers page is where you configure the provider, and the Companies page is where you decide who uses it.

How a user is matched to a company​

When someone signs in by email, Beak determines their company in this order:

  1. The user's own record — a provisioned user is already assigned to a company.
  2. The email domain — for an address with no user record yet, the company whose verified email domains claim that domain.

If neither resolves, or the company's organization links no providers, the tenant's enabled providers apply.

Sign-in buttons on the login page​

When a user opens a login domain that belongs to a company, the login card shows one button per provider that company can use — labelled Continue with <provider name>. Clicking one sends the user straight to that provider.

This uses the same hostname matching as branding (see Login Branding & Custom Domains), so the buttons on the card always belong to the company whose logo and colors are on screen.

  • Only the providers that company's organization links are offered — no others from the tenant.
  • The email field stays. A company usually has both SSO users and local ones — contractors, break-glass administrators — so the password route is always available below the buttons.
  • On the platform login page there are no buttons. A hostname not tied to a company or tenant shows the standard email-first form.

What you need for buttons to appear​

  1. A company with a custom login domain — see Set a custom domain.
  2. At least one enabled identity provider linked to that company's organization.

Nothing else is required. Providers are picked up on the next page load; the response is briefly cached (about a minute).

Note: If the providers cannot be loaded, the login page silently falls back to the email form rather than blocking sign-in.

Controlling who gets an account​

An identity provider's Auto-create users setting decides what happens when someone authenticates successfully but has no Beak user record yet:

  • On — the user record is created automatically on first sign-in.
  • Off — sign-in is refused and the user is returned to the login page with "That account isn't set up for this workspace yet." An administrator must add them first.

This matters most with sign-in buttons. A button on a public login domain means anyone holding an account in your directory can attempt to sign in, so turn Auto-create users off for any provider where membership of the directory should not by itself grant access to Beak.

Note: A user who signs in with a button chooses their account at the identity provider, and that choice is what Beak uses. Because no email address is typed first, there is nothing for Beak to check the returned account against — the account chooser at your provider is the control point.

Every sign-in screen is a Beak screen​

Beak signs users in through an identity platform that runs behind the scenes. Its own screens are never shown to your users — every page in the sign-in journey is Beak's, carrying your login branding.

Two things follow from that, and both are worth knowing before you configure SSO.

An SSO user who has to finish setting up their account does it on the Beak login page​

If a user's account still needs something before they can be signed in, they are returned to the Beak login page to complete it rather than being handed to another screen:

  • Missing profile details — they are asked for them on Complete your account, and sign-in continues once supplied.
  • Two-factor setup, when the tenant requires it and the user has not enrolled — they are taken to Set up two-factor and scan the code there.

Until the step is finished, the user does not hold a session. The requirement cannot be skipped by closing the page and returning; the next sign-in asks again.

SSO users are never asked to set a password. They sign in through your identity provider and have no Beak password, so the password step does not appear for them.

Clearing a step for a user who is stuck​

If a user cannot get past one of these steps — most often an account carrying a leftover requirement from an earlier setup — an administrator can clear it:

  1. Open Users and find the user.
  2. Choose Clear pending login blocks.

That removes every outstanding sign-in requirement on the account, so their next sign-in proceeds. Use it when a requirement no longer applies; it does not change the tenant's own policies, so anything the tenant still mandates — two-factor, for instance — is asked for again on the next sign-in.

SSO is only offered for domains you have configured​

If someone enters an email address whose domain no enabled identity provider covers, Beak says so on the login page and leaves them on the password form:

Single sign-on isn't set up for this email domain. Sign in with your password below, or ask your administrator to configure SSO.

That is the same outcome as before for local users — but it now explains itself instead of failing quietly. If your users see this unexpectedly, check the provider's allowed email domains, and the company's verified domains if the provider is linked to a company organization.

Letting Beak act as the person at your provider​

When someone signs in through your identity provider, that provider issues a token for them. Beak normally discards it once the sign-in is done. Provider tokens on the identity provider's settings keeps it instead, so a Beak service can later call that provider as that person rather than through one shared account — meaning the provider applies their own permissions, and its audit log shows them rather than a service identity.

There are two switches, and they do different things:

  • Keep this provider's tokens — Beak stores the token the provider issued for each person who signs in through it.
  • Let Beak services read them back — permits a Beak service to retrieve a stored token. Without this, tokens are kept but nothing can use them.

Three things behave in ways worth knowing before you turn this on:

  • Only sign-ins from now on are kept. Turning it on stores nothing retroactively — anyone already signed in has to sign out and back in before a token exists for them.
  • The second switch only covers people who link to the provider afterwards. Anyone who already signs in through this provider does not gain access to their stored token by turning it on, and has to be granted it separately. Ask your Beak contact if you need that for existing users.
  • What the token can do is set at your provider, not in Beak. It carries only the permissions your provider issued it, which for a normal sign-in is usually enough to identify the person and no more. Anything further — reading your directory, changing group membership — has to be granted and consented at the provider first, and applies to every sign-in through it.

Note: This stores your provider's access tokens inside Beak, for every person who signs in through that provider. Treat it as you would the provider's own credentials: turn it on for a provider you have a reason to, rather than as part of routine setup. It is off unless you switch it on, and existing providers are unaffected.

Per-person access still applies on top. A stored token carries the signing-in person's own permissions at the provider, so a colleague without the necessary role there is refused by the provider itself — not by Beak. Expect some calls to start being refused for exactly that reason; that is the intent.

Inviting a user who signs in with SSO​

When you invite a user, choose how they will sign in:

  • Single sign-on — no password is created and none is emailed. They receive a "your account is ready" message telling them to sign in with their organization account.
  • Password — a temporary password is created and emailed, and they must replace it the first time they sign in.

Getting this right matters: a user marked as signing in with a password, who actually signs in through your provider, is left holding a temporary password they will never use.

For the same reason, Require password reset does not apply to an SSO user — there is no Beak password to reset, and the action is refused with an explanation. To interrupt an SSO user's access, disable the account or remove it at your identity provider.

Best Practices​

  • Link a provider to a company's organization as soon as that company brings its own directory. Until it is linked, the tenant's providers remain candidates for its users.
  • Share one provider across companies by linking it to each organization, rather than creating a duplicate provider per company.
  • Turn off Auto-create users on any provider reachable from a public login domain unless directory membership is genuinely sufficient for access.
  • Set the company's email domains. They are what routes an unprovisioned address to the right company's provider.
  • Give the provider a name your users will recognise — it appears verbatim on the button as "Continue with …".
  • Invite SSO users as single sign-on, not password. It skips a temporary password they would never use, and sends them the right instructions.