Skip to main content

Single sign-on (SSO)

Single sign-on lets your team sign in to Berrybell with your company identity provider — Okta, Microsoft Entra, Google Workspace, or anything else that speaks OIDC or SAML.

This is about your team, not your app's users

SSO covers how your people sign in to Berrybell. How the end users of an app you build sign in is a different thing entirely — see Sign-in for your app's users. An identity provider you connect here is for your team only; your app's users can't sign in through it.

SSO is a Business-plan capability, set up by an admin or owner in workspace settings.

Two protocols​

Open the Single sign-on tab in workspace settings, choose OIDC or SAML under Connect your identity provider, fill in the fields and click Register provider. Both protocols ask for the Email domain your team's addresses use. A workspace has one SSO provider; to change to a different one, remove the current one first.

  • OIDC — Issuer URL, Client ID and Client secret. The client secret is stored on the server and never shown again. Your identity provider's OIDC app also asks for Berrybell's sign-in redirect URI, which the Single sign-on tab doesn't show yet — contact support for it after you register. That makes SAML the protocol you can set up entirely from the tab today. OIDC connections can't be edited: to change one, for example to rotate the client secret, Remove it and register again. The new connection gets a new TXT record and redirect URI, so SSO sign-in for your domain stays off until you update your identity provider, publish the record and verify the domain again.
  • SAML — the values from your identity provider's SAML app screen:
    • IdP entity ID — copy it verbatim, because every response from your identity provider is checked against it. It must be a URL or a URN.
    • Sign-in page URL
    • Sign-out page URL (optional) — stored, but signing out of Berrybell doesn't end your session at the identity provider.
    • Change password URL (optional) — stored and shown on the settings card only.
    • Verification certificate — paste it, or use Upload certificate. See Certificates.

SAML sign-in is SP-initiated only: start from the Berrybell sign-in screen. Assertions sent unprompted from the identity provider are refused.

Verifying your domain​

Registering a provider gives you a DNS TXT record to publish at your DNS provider for your email domain. The provider card shows its name and value, each with a copy button:

  • Name: _berrybell-sso-<id>.<your domain>
  • Value: starts with _berrybell-sso-<id>=, followed by a token

<id> identifies your connection; the card shows the real values to copy. Until the record is found, the card reads Awaiting DNS verification and sign-in for that domain stays inactive. Once you've published the record, click Verify domain. When Berrybell finds it, the status changes to Verified and the tab says "Domain verified — members can now sign in with SSO."

DNS can take a few minutes to propagate, so verifying immediately may fail with "TXT record not found yet — DNS changes can take a few minutes to propagate. Double-check the record and try again." Wait and try again. The record's value stays the same for 7 days; if the domain still isn't verified after that, the tab shows a new value to publish.

Enter the email domain bare, like example.com — not a URL or an email address. A domain that one workspace has verified cannot be claimed by another: registering it shows "That domain is already verified by another workspace."

Only owners and admins can register, edit, verify or remove a provider, and only they see the TXT record. Other members see the provider card read-only.

The values your IdP needs (SAML)​

After you register a SAML provider, the Single sign-on tab in workspace settings prints the three values to paste into your IdP console, each with a copy button:

  • ACS URL
  • SP entity ID
  • SP metadata URL

Use exactly what the tab shows. Guessing these is the most common reason a SAML app never matches. Until a SAML app with these values exists in your identity provider and is switched on for the member signing in, the identity provider rejects the sign-in — Google Workspace reports app_not_configured_for_user.

On connections registered before late August 2026, owners and admins may see a warning on the card: "This connection is publishing your IdP's entity ID as BerryBell's…". To repair it, click Edit beside IdP details, then Save IdP details without changing anything, and paste the corrected SP entity ID into your identity provider.

If you Remove a provider and register again, the new connection gets a new ACS URL, SP entity ID and TXT record, so the SAML app in your identity provider has to be updated and the domain verified again.

Certificates​

SAML connections pin your identity provider's signing certificate; this section doesn't apply to OIDC.

Upload the IdP signing certificate with Upload certificate — a .pem, .crt, .cer, .cert, .der or .txt file, text or binary — or paste it into the box as a PEM or as a bare base64 body. Berrybell checks it when you click Register provider or Save IdP details, rather than at your users' first sign-in, so a wrong certificate is caught while you still have the IdP console open:

  • RSA only. A certificate with any other key type is refused.
  • Not expired. An expired certificate is refused. One that isn't valid yet is accepted.
  • One certificate. A file or paste holding more than one is refused — a connection pins one certificate at a time.

The card then shows the pinned certificate back to you — subject, fingerprint, key type and validity — and warns you about its dates (your certificate's dates appear in place of these examples):

  • Within 30 days of expiry: "Expires in 12 days (Oct 3, 2026) — get the replacement from your IdP before then."
  • Once expired: "Expired on Oct 3, 2026 — your IdP is no longer signing with this certificate. Upload the current one."
  • Before its start date: "Not valid until Oct 3, 2026."

You can edit the IdP details in place: click Edit beside IdP details, change the entity ID, URLs or certificate, and click Save IdP details. Leave Verification certificate blank to keep the one on file. Saving a new certificate shows "IdP details saved — the new certificate is pinned from the next sign-in."

Because only one certificate is pinned at a time, sign-in fails between your identity provider switching to its new certificate and you saving that certificate here, so save it as soon as the switch happens. What editing in place spares you is registering again and re-verifying your domain: the ACS URL, SP entity ID and TXT record stay the same.

Changing the email domain requires removing the provider and registering again, whichever protocol you use.

Signing in​

On the Berrybell sign-in screen, type your work email and press Continue. If the address is at a verified connection's domain, or at a subdomain of it, Continue with SSO is offered first, ahead of any other way the account signs in. If single sign-on is the account's only way in, it's the only option shown. The small Use single sign-on (SSO) link appears only when Berrybell can't check the address.

After one successful SSO sign-in, the browser offers Continue with example.com — named after your company's domain — at the top of the sign-in screen for 30 days, which takes you to your identity provider without typing your email. The whole sign-in screen is covered in Signing in to Berrybell.

SSO signs in existing Berrybell accounts only. Signing in with SSO from the Berrybell sign-in screen never creates an account, and SSO never adds anyone to your workspace. The person needs a Berrybell account at exactly their work address — normally the one they created by accepting your invitation, as described in Team & roles — and their first SSO sign-in links it automatically, as long as they've confirmed their email address. An unconfirmed account can't be linked: the sign-in returns to the sign-in screen with "That verification link is invalid or has expired. Sign in and we'll send you a fresh one." Have them confirm their email first. An address typed on the sign-in screen that has no account stops at "No account for you@example.com."

When SSO sign-in fails​

If single sign-on doesn't complete, you're returned to the sign-in screen with a message:

What happenedThe message
The sign-in was started from your identity provider, not from Berrybell"Single sign-on has to start from this page. Enter your work email and use “Continue with SSO” rather than opening Berrybell from your identity provider."
The response didn't match a sign-in Berrybell started, or took too long"That single sign-on attempt could not be verified — it may have taken too long. Try signing in again."
The same response arrived twice"That single sign-on response has already been used. Start a fresh sign-in."
The connection's settings are wrong"Single sign-on is not configured correctly for your domain — ask your administrator to check the connection.", followed by an error code and description in brackets
Berrybell couldn't match the person your identity provider signed in to a confirmed Berrybell account at that address"That verification link is invalid or has expired. Sign in and we'll send you a fresh one."
Most other failures"Single sign-on failed (…). Try again, or ask your administrator to check the connection.", with an error code and description in the brackets

The last message also covers a response signed with a certificate other than the pinned one, which shows as "Single sign-on failed (saml_error: Invalid SAML response)…" — usually a sign that your identity provider has switched certificates. The verification-link message can appear even when the address you typed has an account, if your identity provider signs in someone else — for example a different account already signed in there.

When you ask your administrator or support for help, quote the error code from the brackets.

If the plan lapses​

Without an active Business subscription (a trial counts), the Single sign-on tab shows "Single sign-on is available on the Business plan." and an Upgrade button in place of your provider. The provider's details are hidden, and you can't register, edit, verify or remove a provider until the workspace is back on a Business plan. Sign-in keeps working the whole time — a lapsed subscription never locks your team out.

Next steps​