Skip to content

Single Sign-On (SSO)

Let employees sign in to BongoShield with the identity provider (IdP) your organization already runs — Microsoft Entra ID, Google Workspace, Zoho, or any SAML 2.0 IdP (ADFS, Okta, …). No new passwords, and the daily security question still meets them right after login.

You configure this yourself in Settings → Single sign-on. Everything the IdP needs from BongoShield — the redirect URI (OIDC) or the ACS and SP-metadata URLs (SAML) — is shown on screen with a copy button once you save the provider. You must be a BongoShield Owner or Admin.

What SSO does + email-first routing

Each enabled provider federates one or more email domains. When someone enters their email at the BongoShield sign-in page, BongoShield looks at the domain:

  • Domain matches an enabled SSO provider → the user is redirected to that IdP to authenticate, then bounced back to BongoShield for the daily question.
  • Domain matches an LDAP/AD directory → the local/LDAP password form is used (see LDAP / Active Directory).
  • Otherwise → the local-account password form.

There is one login page for everyone; the server resolves the route from the email. Local accounts and LDAP directories keep working alongside SSO — turning on a provider never disables the others. The break-glass Owner account always uses a local password so you are never locked out if the IdP is unreachable.

New users who arrive through SSO start with the user role. IdP groups never grant BongoShield roles — promote people on the Users page.

Public email domains are rejected

You cannot federate gmail.com, outlook.com, or other consumer domains — only domains your organization owns. This prevents a stranger with a public address from being routed into your tenant.

Auto-enrol new users (JIT)

At the top of Settings → Single sign-on is the Auto-enrol new users (JIT) setting. It controls whether an unknown employee gets a BongoShield account the first time they arrive through SSO:

Mode Behaviour
All New users auto-enrol on first Microsoft sign-in (web and Outlook add-in).
Web login only Auto-enrol only when a user deliberately signs in on the web login; the add-in gates existing users only.
Off No self-enrolment — only admin-added users get accounts.

Existing users always sign in regardless of this setting. Auto-enrolment never exceeds your licence's seat cap — see Licensing & Seats.

Microsoft Entra ID (OIDC)

There are two ways to connect Microsoft. Pick one.

  • One-click (recommended for cloud/pooled SaaS) — BongoShield's own Microsoft app does the work; you consent once as a Microsoft admin. Fastest path.
  • Your own app registration — you register an app in Entra and paste its details into BongoShield. Use this if your security policy requires the app to live in your own tenant, or for a dedicated/on-prem install.

Option A — One-click "Connect with Microsoft"

  1. In BongoShield go to Settings → Single sign-on.
  2. Click Connect with Microsoft (one-click) and complete the Microsoft admin-consent prompt as a Microsoft global administrator.
  3. You are returned to BongoShield with a green Connected to Microsoft card showing the connected domains. The card displays a Redirect URI (register once in Entra) — this stable URI never changes across disconnect/reconnect, so you only ever register it once if Microsoft asks for it.
  4. Use Disconnect on the card to unbind, or Reconnect to refresh consent.

That's it — no app registration required.

Option B — Your own Entra app registration

In the Microsoft Entra admin center (https://entra.microsoft.com):

  1. Identity → Applications → App registrations → New registration.
  2. Name it (e.g. BongoShield), choose Accounts in this organizational directory only (single tenant), and click Register.
  3. On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID — you'll need both.
  4. Certificates & secrets → Client secrets → New client secret. Give it a description and expiry, click Add, and copy the secret Value immediately (it is shown only once).

  5. API permissions → Add a permission → Microsoft Graph → Delegated permissions. Add only the least-privilege scopes below, then click Grant admin consent for <your tenant>.

    Scope Why Never use
    openid Sign the user in via OpenID Connect —
    profile Read the user's name —
    email Match the user to their BongoShield account by email —
    User.Read Read the signed-in user's own basic profile not User.Read.All or any .All

    BongoShield never needs an application (app-only) permission or any .All scope for login. If you see .All creeping into the request, stop — that is over-privileged for SSO.

In BongoShield (Settings → Single sign-on):

  1. Click Add provider. Under Quick setup, click Microsoft to prefill the display name and issuer.
  2. Set the Issuer URL to https://login.microsoftonline.com/<tenant-id>/v2.0, replacing <tenant-id> with the Directory (tenant) ID you copied.
  3. Paste the Client ID and Client secret.
  4. Under Allowed email domains, add each domain this provider should handle (e.g. corp.example.com) — press Enter or comma to add each one.
  5. Leave Enabled on and click Add provider.
  6. The saved provider card now shows a Redirect URI — https://<your-api-host>/api/v1/auth/oidc/<provider-id>/callback/. Click the copy button.
  7. Back in Entra: App registration → Authentication → Add a platform → Web, paste the redirect URI into Redirect URIs, and Save.

Test it

Ask a user (or use a test account) whose email is on an allowed domain to sign in at the BongoShield login page. They should be redirected to Microsoft, sign in, and land on the daily security question. If it fails, see Troubleshooting below.

Editing a provider later

The client secret is write-only — BongoShield never displays it again, so the edit form starts blank. Leave the secret field blank to keep the current value, or paste a new one to rotate it.

Google Workspace (OIDC)

In the Google Cloud console (https://console.cloud.google.com):

  1. APIs & Services → OAuth consent screen — configure it as Internal (your Workspace org only) if not already done.
  2. APIs & Services → Credentials → Create credentials → OAuth client ID.
  3. Application type: Web application. Name it BongoShield.
  4. You'll add the redirect URI here in a moment — first create the provider in BongoShield to obtain it (step 6), then return and paste it under Authorized redirect URIs.
  5. Copy the Client ID and Client secret.

In BongoShield (Settings → Single sign-on):

  1. Add provider → Quick setup → Google. This prefills the issuer as https://accounts.google.com.
  2. Paste the Client ID and Client secret, add your Workspace email domain(s) under Allowed email domains, and click Add provider.
  3. Copy the Redirect URI shown on the saved provider card (https://<your-api-host>/api/v1/auth/oidc/<provider-id>/callback/).
  4. Return to Google Cloud → your OAuth client → Authorized redirect URIs → paste it → Save.

Test with a Workspace user on an allowed domain.

Zoho and other OIDC providers

The same flow works for Zoho (Quick setup → Zoho prefills issuer https://accounts.zoho.com; change .com to .eu, .in, .com.au, .jp or .ca for a regional Zoho data centre) and for any OpenID Connect provider — the backend resolves every endpoint from the issuer's discovery document, so you only ever paste an issuer, client ID and secret, then register the redirect URI.

SAML 2.0

Use SAML for IdPs that speak SAML rather than OIDC — ADFS, Okta, or Entra ID's legacy SAML mode. BongoShield acts as the service provider (SP); your IdP authenticates the user and posts a signed assertion back.

In BongoShield (Settings → Single sign-on):

  1. Add provider, then set Protocol to SAML 2.0 (this is fixed once the provider is created).
  2. Fill in:
    • IdP Entity ID — e.g. https://sts.windows.net/<tenant-id>/.
    • IdP SSO URL — e.g. https://login.microsoftonline.com/<tenant-id>/saml2.
    • IdP signing certificate — paste the PEM-encoded X.509 certificate (-----BEGIN CERTIFICATE----- … -----END CERTIFICATE-----). This is required so BongoShield can validate the signed assertion.
    • IdP metadata URL (optional) — your IdP's federation metadata XML URL.
    • Allowed email domains — the domains this provider handles.
  3. Click Add provider. The saved provider card now shows two URLs, each with a copy button:
    • ACS URL (Assertion Consumer Service) — https://<your-api-host>/api/v1/auth/saml/<provider-id>/acs/
    • SP metadata URL — https://<your-api-host>/api/v1/auth/saml/<provider-id>/metadata/

In your IdP: register BongoShield as a relying party / SAML app and paste the ACS URL as the Assertion Consumer Service / Reply URL. Many IdPs can import the SP metadata URL directly to fill this in automatically. Ensure the IdP releases an email attribute (NameID or a claim) that matches the user's BongoShield email.

Signing certificate rotation

Like the OIDC client secret, the signing certificate is write-only. On the edit form, leave it blank to keep the current certificate, or paste a new one when your IdP rotates its signing key.

Test with a user on an allowed domain.

Troubleshooting

Symptom Likely cause Fix
Microsoft/Google returns redirect_uri_mismatch (or "reply URL does not match") The redirect URI in the IdP app doesn't exactly match BongoShield's Copy the Redirect URI from the saved provider card and paste it verbatim into the IdP (Entra → Authentication → Web; Google → Authorized redirect URIs). It must match exactly, including the trailing slash.
User isn't redirected to the IdP — sees the password form instead Their email domain isn't in Allowed email domains, or the provider is disabled Add the domain to the provider and confirm the provider shows Enabled.
"Public domains are rejected" when adding a domain You tried to federate a consumer domain (gmail.com, outlook.com, …) Only add domains your organization owns.
Login fails at the token exchange right after the IdP Wrong or expired client secret Edit the provider and paste a fresh secret (Entra → Certificates & secrets → new client secret). Blank means "keep current", so you must paste the new value.
Microsoft prompt says admin approval / consent required Admin consent wasn't granted for the delegated scopes In Entra → API permissions, click Grant admin consent for openid, profile, email, User.Read.
One-click connect fails or the card doesn't turn green Consent was declined, or done by a non-admin Re-run Connect with Microsoft as a Microsoft global administrator; the error code is shown in the toast.
SAML login fails with a signature/validation error Missing or wrong IdP signing certificate Edit the SAML provider and paste the current PEM certificate from your IdP.
SAML user signs in but no account is matched The IdP isn't releasing an email that matches BongoShield Configure your IdP to send the user's email (matching their BongoShield address) in the assertion.
New SSO users aren't being created Auto-enrol (JIT) is set to Off (or Web login only for add-in arrivals), or you're at your seat cap Set JIT to All, or add users manually; check remaining seats on the Licence tab.