Single Sign On

Single Sign-On (OIDC)

BBS supports Single Sign-On via OpenID Connect (OIDC), allowing users to authenticate with an external identity provider instead of a local username and password.

Supported Providers

Any OIDC-compliant identity provider works, including:

• Keycloak
• Authentik
• Microsoft Entra ID (Azure AD)
• Google Workspace
• Okta
• Auth0
• Authelia
• Cloudflare Access

Setup

1. Create an Application in Your Identity Provider

In your identity provider, create a new application/client with these settings:

Setting	Value
Application type	Web application
Grant type	Authorization Code
Redirect/Callback URL	https://your-bbs-server/login/oidc/callback
Scopes	openid email profile

Note the Client ID and Client Secret — you'll need these in the next step.

2. Configure BBS

Go to Settings > Authentication and fill in:

• Enable OIDC Single Sign-On — toggle on
• Provider URL — your provider's base URL for OIDC discovery
  • Keycloak: https://keycloak.example.com/realms/your-realm
  • Authentik: https://authentik.example.com/application/o/your-app/
  • Azure AD: https://login.microsoftonline.com/your-tenant-id/v2.0
  • Google: https://accounts.google.com
  • Okta: https://your-domain.okta.com
• Client ID — from your identity provider
• Client Secret — from your identity provider (encrypted at rest in BBS)
• Button Label — text shown on the login page (e.g. "Login with Company SSO")
• Scopes — usually openid email profile (default)

3. Configure New User Handling

When someone authenticates via SSO for the first time and doesn't have a BBS account, you control what happens:

Option	Behavior
Deny access	The user must already exist in BBS with a matching email address. Unknown users see an error message. This is the safest option.
Create user, pending approval	A new account is created but marked as "Pending." The user sees a message that their account is awaiting approval. An admin approves from the Users page.
Copy permissions from a template user	A new account is created and automatically receives the same client access and permissions as the selected template user. Useful when most team members need the same access level.

4. Optional: Enable OIDC Logout

When enabled, logging out of BBS also redirects the user to the identity provider's logout endpoint. This signs them out of all applications connected to that provider. Disabled by default — most users prefer to only log out of BBS while staying signed into other apps.

How It Works

1. User clicks the SSO button on the login page
2. BBS redirects to the identity provider's authorization endpoint
3. User authenticates with the provider (password, MFA, etc.)
4. Provider redirects back to BBS with an authorization code
5. BBS exchanges the code for tokens, verifies the ID token, and extracts the email
6. BBS matches the email to a local user account (or creates one per the policy)
7. A session is created and the user is logged in

User Matching

BBS matches SSO users by email address. The email from the OIDC provider's email claim is compared to the email field in BBS's user table.

• If a match is found, the user logs in with their existing permissions
• If no match is found, the new-user policy applies

SSO Users vs Local Users

Feature	Local Users	SSO Users
Login method	Username + password	Identity provider
Two-factor auth	Managed in BBS	Managed by identity provider
Password tab in profile	Visible	Hidden
2FA tab in profile	Visible	Hidden
Permission management	Same	Same
Force 2FA setting	Enforced	Skipped (IdP handles auth strength)

SSO does not change how permissions work. Client access, backup plan management, and all other permissions are assigned the same way regardless of authentication method.

Login Page

When SSO is enabled, the login page shows an SSO button above the standard username/password form:

• Users with SSO click the button to authenticate via their identity provider
• Users with local accounts continue using username and password
• Both methods can coexist — a user whose email matches can use either

Managing SSO Users

Approving Pending Users

If the new-user policy is set to "pending approval":

1. Go to Users in the sidebar
2. Pending SSO users show a yellow Pending badge
3. Click the green Approve button to activate their account
4. Once approved, they can log in via SSO

User Badges

The Users page shows these badges for SSO users:

• SSO (blue) — user authenticates via OIDC
• Pending (yellow) — awaiting admin approval

Editing SSO Users

On the user edit page, SSO users show an "SSO (OIDC)" badge instead of a password field. All other settings (role, client access, permissions) work identically to local users.

Provider-Specific Notes

Keycloak

1. Create a new Client in your realm
2. Set Access Type to "confidential"
3. Set Valid Redirect URIs to https://your-bbs-server/login/oidc/callback
4. Copy the Client ID and Secret from the Credentials tab
5. Provider URL: https://keycloak.example.com/realms/your-realm

Authentik

1. Create a new OAuth2/OpenID Provider
2. Set Redirect URIs to https://your-bbs-server/login/oidc/callback
3. Create an Application linked to the provider
4. Provider URL: https://authentik.example.com/application/o/your-app/

Azure AD / Microsoft Entra ID

1. Register a new application in Azure Portal > App Registrations
2. Add a Web redirect URI: https://your-bbs-server/login/oidc/callback
3. Create a client secret under Certificates & Secrets
4. Provider URL: https://login.microsoftonline.com/your-tenant-id/v2.0
5. Scopes may need: openid email profile User.Read

Google Workspace

1. Create OAuth 2.0 credentials in Google Cloud Console
2. Set authorized redirect URI to https://your-bbs-server/login/oidc/callback
3. Provider URL: https://accounts.google.com

Troubleshooting

Problem	Solution
SSO button doesn't appear	Verify OIDC is enabled and Provider URL, Client ID are filled in (Settings > Authentication)
"SSO error" after clicking button	Check Provider URL is correct and accessible from the BBS server
"OIDC provider did not return an email"	Ensure the email scope is included and the user has an email set in the IdP
"No account found with this email"	New-user policy is set to "deny" — create the user in BBS first with the matching email
Redirect loop after login	Check that the callback URL in your IdP exactly matches https://your-server/login/oidc/callback
Session lost after redirect	Ensure your BBS server uses HTTPS — cookies may not persist on HTTP with some browsers

Related Documentation

• User Management — Creating users and assigning permissions
• Security — General security settings
• Two-Factor Authentication — 2FA for local users