# Setting up single sign-on

> The “Single sign-on” section: OIDC or SAML 2.0, values for the provider, SP metadata, a test sign-in. Examples for Keycloak, AD FS and Entra ID.

Everything is set up in [Settings](/en/docs/settings) → choose the organisation → the **“Single sign-on”** section. The section is available only to the **organisation owner**.

_Illustration: The “Single sign-on” section: the protocol, the provider fields, the member policy and — below — our values for setting up the provider side._

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:

| Parameter at the provider | Value |
| --- | --- |
| Redirect URI (callback) | from the “Values for setting up” block — like `https://buff.systems/app/sso/callback` |
| Grant / flow | Authorization Code |
| PKCE | S256 |
| Scopes | `openid email profile` |

Then in Buff:

| Field | What to enter |
| --- | --- |
| **Issuer URL** | the provider’s address at which `/.well-known/openid-configuration` is available. Buff reads the document automatically: endpoints, signing keys. |
| **Client ID** | the identifier of the registered client |
| **Client secret** | its secret. It is stored encrypted and **never shown** back; to change it, type a new one; to keep it, leave the field alone |
| **Scopes** | `openid email profile` by default; `openid` is required, `email` is needed to create accounts and link existing ones |

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.

_Illustration: The OIDC connection is saved: the secret is not shown; below — “Test sign-in” and the values for the provider._

### 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:

| Parameter at the provider | Value |
| --- | --- |
| Entity ID / Identifier / Audience | from the “Values for setting up” block — like `https://buff.systems/app/saml/<organisation>` (each organisation has its own) |
| Assertion Consumer Service (ACS, Reply URL), binding **HTTP-POST** | from the “Values for setting up” block — like `https://buff.systems/app/sso/saml/acs` |
| Signature | **the Assertion must be signed**, SHA-256 algorithm. Signing the whole response is not required |
| NameID | a stable identifier — the `persistent` format (recommended) or another immutable one |
| Attributes | `email` — required (attribute name `email`, `mail` or the standard claim URI); name — optional |
| Signing of requests from Buff | not required (Buff does not sign the AuthnRequest) |

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:

| Field | What to enter |
| --- | --- |
| **Provider SSO URL** | the single sign-on address (SingleSignOnService with the HTTP-Redirect binding), for example `https://<keycloak>/realms/<realm>/protocol/saml` or `https://<adfs>/adfs/ls/` |
| **Provider Entity ID** | optional; if given, the assertion issuer is checked |
| **NameID format** | which format to request from the provider; persistent by default |
| **Provider’s signing certificate (PEM)** | the certificate the provider signs assertions with. You can paste several in a row — the old and the new one during rotation |

_Illustration: A SAML 2.0 connection: the single sign-on address, the provider’s certificate; below — the Entity ID, ACS and SP metadata for the provider._

### 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](/en/docs/sso/troubleshooting). Every step — setup, the start of sign-in, the result — is visible in the organisation’s [audit log](/en/docs/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](/en/docs/sso/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).