Setting up single sign-on

Everything is set up in Settings → choose the organisation → the “Single sign-on” section. The section is available only to the organisation owner.

Setup has two steps, in any order: register Buff with the provider and enter the provider’s details in Buff. The values for the first step are in the “Values for setting up the provider side” block at the bottom of the section; each value is copied with one button.

OIDC

Register a confidential client (with a secret) with the provider for the Authorization Code flow; Buff always uses PKCE (S256) — if the provider requires it to be turned on explicitly, turn it on. Give the provider:

Then in Buff:

On saving, Buff fetches the discovery document from the provider: an unreachable address or a wrong secret returns an error at once, not at an employee’s first sign-in.

Keycloak

Clients → Create client: type OpenID Connect, Client authentication On, Standard flow On, Direct access grants Off. Valid redirect URIs — our Redirect URI. The Issuer URL for Buff is https://<keycloak>/realms/<realm>; the Client secret is on the Credentials tab. On the Advanced tab you can set Proof Key for Code Exchange Code Challenge Method = S256.

Microsoft Entra ID

App registrations → New registration; the Redirect URI of the Web platform — our Redirect URI. Certificates & secrets → New client secret. Issuer URL — https://login.microsoftonline.com/<tenant-id>/v2.0, Client ID — Application (client) ID. Make sure the token contains email (Token configuration → Add optional claim → ID → email), otherwise Buff requests it through userinfo.

AD FS

By default AD FS issues minimal ID tokens: it is easier to connect over SAML (below). For OIDC, create an Application Group of the Server application + Web API type, allow the openid and email scopes, add claim issuance rules for email; the Issuer URL is https://<adfs>/adfs.

SAML 2.0

Register a Service Provider with the provider (a Relying Party Trust in AD FS, a SAML client in Keycloak, an Enterprise application in Entra ID) with our values:

The easiest way is to give the provider a ready-made file: after the SAML connection is saved, the section shows a “Download SP metadata” button — an XML file with the Entity ID and the ACS address.

Then in Buff:

Keycloak

Clients → Create client: type SAML, Client ID = our Entity ID. Settings: Valid redirect URIs and Master SAML Processing URL = our ACS; Name ID format = persistent; Force POST binding = On. Keys: Client signature required = Off. Signature and Encryption: Sign assertions = On, Signature algorithm RSA_SHA256. Client scopes → add a mapper of the User Property type: Property email, SAML Attribute Name email, Name Format Basic. The realm signing certificate is in Realm settings → Keys → RS256 → Certificate (this is the PEM body without headers: add the -----BEGIN CERTIFICATE----- / -----END CERTIFICATE----- lines) or in /realms/<realm>/protocol/saml/descriptor.

AD FS

Add Relying Party Trust → Enter data manually → Identifier = our Entity ID; SAML 2.0 WebSSO, Relying party SAML 2.0 SSO service URL = our ACS. Claim Issuance Policy: an LDAP Attributes rule → E-Mail-Addresses → E-Mail Address; a Transform rule → E-Mail Address → Name ID with the Persistent Identifier format (or keep the email as the NameID — then choose the emailAddress format in Buff). Certificate — Service → Certificates → Token-signing → export as Base-64 X.509. SSO URL — https://<adfs>/adfs/ls/.

Microsoft Entra ID

Enterprise applications → New application → Create your own → Integrate any other application (Non-gallery) → Single sign-on → SAML. Identifier = our Entity ID, Reply URL = our ACS. Attributes & Claims: Unique User Identifier — user.objectid or user.mail; add an email claim = user.mail. SAML Signing Certificate → Certificate (Base64). The Login URL goes into the Provider SSO URL field.

Test sign-in

After saving, the “Test sign-in” link opens the SSO sign-in screen in a new tab with the organisation name already filled in. Sign in as a test employee: if the provider returned an error, it is shown in words — see Troubleshooting. Every step — setup, the start of sign-in, the result — is visible in the organisation’s audit log.

Changing the provider and turning SSO off

Switching the protocol or the provider is done in the same section: save the new details; accounts created earlier remain, but the “employee at the provider ↔ account” links are re-established at the next sign-in (by email — see Company domains).

“Switch off SSO” deletes the connection, the verified domains and the links to the provider. The employees’ accounts remain members of the organisation; they can sign in with a password after setting one through “Forgot your password?” (accounts created through SSO had no password).