DocsEnterprise
Single sign-on
People sign in to the console through your identity provider, with OIDC or SAML 2.0, and their roles follow their groups. Guides for Okta, Microsoft Entra ID, Google Workspace and Keycloak.
How it works
- The console's sign-in dialog offers Sign in with SSO (OIDC) and Sign in with SAML, for whichever is set up. Both can be.
- Signing in leaves an HTTP-only session cookie, valid for 8 hours (
BBM_ATLAS_EE_SESSION_HOURS). It counts only on the console's own requests, so another site can't use it. - A user is created the first time they sign in, in the organisation the method names (
default, unless…_ORGANIZATIONsays otherwise). - With a role mapping or default roles configured, a user's roles are set from their groups at every sign-in, so manage those people's roles in the provider. Without either, sign-in never changes roles: new users start with none, and an administrator gives them roles.
- Serve BBM-Atlas over HTTPS: the cookie is then marked
Secure.
OIDC
The authorisation-code flow with PKCE. Register BBM-Atlas with your provider as a confidential web client, with this redirect URL exactly: https://<your host>/api/v1/enterprise/sso/callback.
BBM_ATLAS_EE_OIDC_ISSUER=https://id.example.com/realms/acmeBBM_ATLAS_EE_OIDC_CLIENT_ID=bbm-atlasBBM_ATLAS_EE_OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secretBBM_ATLAS_EE_OIDC_REDIRECT_URL=https://atlas.example.com/api/v1/enterprise/sso/callbackBBM_ATLAS_EE_OIDC_ROLE_MAPPING='{"atlas-admins": "administrator", "engineering": "developer"}'BBM_ATLAS_EE_OIDC_DEFAULT_ROLES='["read_only"]'Scripts can send the provider's access tokens as bearer tokens, checked against the provider's keys; their audience must be BBM_ATLAS_EE_OIDC_AUDIENCE (the client id by default). The email comes from the email claim (BBM_ATLAS_EE_OIDC_EMAIL_CLAIM) and the groups from groups (BBM_ATLAS_EE_OIDC_GROUPS_CLAIM).
| Provider | Set-up |
|---|---|
| Okta | Issuer: an authorisation server such as https://<org>.okta.com/oauth2/default, not the bare org URL. An OIDC Web Application with the Authorization Code grant. Add a groups claim to the authorisation server. For bearer tokens set the audience to the server's (api://default). |
| Microsoft Entra ID | Issuer https://login.microsoftonline.com/<tenant-id>/v2.0. A registration with a Web redirect URI and a client secret; add a groups claim (it sends group object IDs, so map those) and the optional email claim, or set the email claim to preferred_username. For bearer tokens, expose an API and set accessTokenAcceptedVersion to 2 in the manifest. |
| Google Workspace | Issuer https://accounts.google.com. A Web application OAuth client with an Internal consent screen. Google sends no groups: leave the mapping empty and give roles in BBM-Atlas. Its access tokens aren't JWTs, so scripts use API keys. |
| Keycloak | Issuer https://<host>/realms/<realm>. A confidential client with the standard flow and PKCE (S256). A Group Membership mapper (claim groups, full group path off); an Audience mapper for bearer tokens. |
SAML 2.0
BBM-Atlas is the service provider. It sends the browser to your identity provider, which posts a signed response back to BBM-Atlas's assertion consumer service (ACS). Give the provider BBM-Atlas's entity id and ACS URL, or its metadata at /api/v1/enterprise/saml/metadata.
BBM_ATLAS_EE_SAML_IDP_ENTITY_ID=https://idp.example.com/samlBBM_ATLAS_EE_SAML_IDP_SSO_URL=https://idp.example.com/saml/ssoBBM_ATLAS_EE_SAML_IDP_CERTIFICATE_FILE=/run/secrets/saml_idp_certificate.pemBBM_ATLAS_EE_SAML_SP_ENTITY_ID=https://atlas.example.com/api/v1/enterprise/saml/metadataBBM_ATLAS_EE_SAML_ACS_URL=https://atlas.example.com/api/v1/enterprise/saml/acsBBM_ATLAS_EE_SAML_ROLE_MAPPING='{"atlas-admins": "administrator", "engineering": "developer"}'BBM_ATLAS_EE_SAML_DEFAULT_ROLES='["read_only"]'- Who someone is. The email comes from the NameID, requested as an email address, or from an attribute (
BBM_ATLAS_EE_SAML_EMAIL_ATTRIBUTE). - Groups and names. Groups come from the
groupsattribute (BBM_ATLAS_EE_SAML_GROUPS_ATTRIBUTE);BBM_ATLAS_EE_SAML_NAME_ATTRIBUTEnames one holding a display name. - Certificates. The file may hold several certificates, one after another, while the provider rotates its key.
- What is checked. The response or the assertion must be signed with SHA-256 or stronger, answer the sign-in BBM-Atlas started, and be addressed to its ACS and entity id. Validity times allow two minutes' clock skew (
BBM_ATLAS_EE_SAML_CLOCK_SKEW_SECONDS).
| Provider | Set-up |
|---|---|
| Okta | A SAML 2.0 app integration: Single sign-on URL = the ACS URL, Audience URI = the entity id, Name ID format EmailAddress, a Group Attribute Statement named groups. Take the SSO URL, issuer and X.509 certificate from its set-up instructions. |
| Microsoft Entra ID | A non-gallery enterprise application with SAML: Identifier = the entity id, Reply URL = the ACS URL, the unique user identifier user.mail as an email address. Entra sends group object IDs in http://schemas.microsoft.com/ws/2008/06/identity/claims/groups: set that as the groups attribute and map the IDs. |
| Google Workspace | A custom SAML app: BBM-Atlas's ACS URL and entity id, Name ID the primary email, and Group membership mapped to an attribute named groups. Turn the app on for the people who should sign in. |
| Keycloak | A SAML client whose id is the entity id, the ACS URL as its POST binding URL, documents and assertions signed, client signature not required, Name ID format email (forced), and a Group list mapper named groups. The SSO URL is https://<host>/realms/<realm>/protocol/saml. |
Signing out
Sign out in the console ends the session in BBM-Atlas. Disabling a user in BBM-Atlas stops their sessions and keys at once. Disabling them only in the provider stops new sign-ins, while a session already open lasts until it expires.