# Single sign-on (SAML)

Connect your SAML 2.0 identity provider so your team signs in to Screeb with SSO.

Screeb supports **SAML 2.0** Single Sign-On (SSO). Your team signs in to Screeb through your company's Identity Provider (IdP), such as Okta, Microsoft Entra ID (Azure AD), Google Workspace, OneLogin, Ping Identity or JumpCloud, instead of using a separate Screeb password.

This page explains the setup and who owns each step.

> [!TIP]
> Screeb also supports OIDC, and it is usually quicker to set up. Both give the same result for your users. See [Single Sign-On (OIDC)](https://developers.screeb.app/api-and-connectors/sso-oidc).
>
> Every Screeb user can already use the **Sign in with Google** and **Sign in with Microsoft** buttons, with no setup on your side. A dedicated SSO connection is for when you want your own IdP, automatic routing of your users to it, or SSO as the only way in.

## Who is involved

Setting up SAML SSO takes a short back-and-forth between two people:

- **Someone on your side** with admin access to your Identity Provider, who can create and configure an application there.
- **Someone on the Screeb side** (your Customer Success contact, or [support@screeb.app](mailto:support@screeb.app)), who creates the matching connection in Screeb.

No code or integration work is needed on your end. Everything happens in your IdP's admin console.

## Overview of the process

| Step | Who          | What happens                                                                                                                      |
| ---- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 1    | **You**      | Create a SAML application for Screeb in your IdP. Send Screeb its **metadata** and the **email domains** your team signs in with. |
| 2    | **Screeb**   | Creates your SSO connection and sends you its **SP metadata URL**, **Entity ID** and **ACS URL**.                                 |
| 3    | **You**      | Enter these values in your IdP application, configure the attributes and assign your users.                                       |
| 4    | **Screeb**   | Confirms your email domains and enables SSO for your organization.                                                                |
| 5    | **Both**     | Test a real sign-in together before rolling it out.                                                                               |
| 6    | **Optional** | Make SSO mandatory for your domains.                                                                                              |

## Step 1: Create the application and send your metadata

In your IdP's admin console, create a new SAML 2.0 application for Screeb. Most IdPs have a generic "SAML 2.0 application" template. Once it exists, your IdP lets you download its **metadata XML** or copy its **metadata URL**. This metadata describes your IdP's sign-in endpoint and signing certificate, and it is what Screeb needs to trust your IdP.

Send your Screeb contact:

- the **metadata XML file** (or the metadata URL);
- the **email domains** your users sign in with (for example `acme.com` and `acme.fr`).

You don't need to fill in the Screeb-specific fields (Entity ID, ACS URL) yet. That comes in step 3.

> [!NOTE]
> Some IdPs, or internal IAM policies, require the Service Provider's details before an application can be created. Ask your Screeb contact: we can send you our SP details first, and steps 1 to 3 then run in the reverse order.

## Step 2: Screeb creates your connection

Screeb registers your IdP and sends you back the values that identify Screeb to it. They are specific to your connection:

| Value                                    | What it looks like                                           |
| ---------------------------------------- | ------------------------------------------------------------ |
| **SP metadata URL**                      | `https://auth.screeb.app/idps/<connection-id>/saml/metadata` |
| **SP Entity ID**                         | The same URL as the SP metadata URL                          |
| **ACS URL** (Assertion Consumer Service) | `https://auth.screeb.app/idps/<connection-id>/saml/acs`      |
| **ACS binding**                          | HTTP-POST                                                    |

`<connection-id>` is a number generated when your connection is created. Your Screeb contact sends you the exact values. If your organization is hosted on a dedicated Screeb platform, the domain is that platform's own (your Screeb contact will tell you which one).

The SP metadata URL is public. Most IdPs can import it directly, which fills in the Entity ID, the ACS URL and Screeb's signing certificate in one go.

## Step 3: Configure your IdP application

Back in your IdP admin console, edit the Screeb application from step 1.

### Service Provider values

Import the SP metadata URL if your IdP supports it. Otherwise fill in:

- the **SP Entity ID** as the "Audience URI", "Entity ID" or "Identifier" (naming varies by IdP);
- the **ACS URL** as the "Reply URL", "ACS URL" or "Single sign-on URL".

### NameID

The NameID identifies the user to Screeb, and Screeb uses it to recognize the same person on every sign-in. It must be **stable**: always the same value for a given user.

- **Persistent** (recommended), or **Email address** if your users' email addresses never change.
- If your IdP can only send a **transient** NameID, tell your Screeb contact: we then need an extra attribute that carries a stable user ID.

### Attributes

Configure the attributes your IdP sends in the assertion (usually the "Attribute Statements" or "Attributes & Claims" section). **Attribute names must match exactly**, without any namespace prefix:

| Attribute name | Required?    | Value                    | Purpose                                                               |
| -------------- | ------------ | ------------------------ | --------------------------------------------------------------------- |
| `email`        | **Required** | The user's email address | Matches the sign-in to the Screeb user. Without it, sign-in fails.    |
| `given_name`   | Recommended  | First name               | Fills in the user's first name in Screeb when the account is created. |
| `family_name`  | Recommended  | Last name                | Fills in the user's last name in Screeb when the account is created.  |

The standard names most IdPs send by default are accepted too:

| Attribute     | Also accepted                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `email`       | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, `urn:oid:0.9.2342.19200300.100.1.3` |
| `given_name`  | `firstName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`, `urn:oid:2.5.4.42`        |
| `family_name` | `lastName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`, `urn:oid:2.5.4.4`            |

Any other name is ignored. If no name is sent, sign-in still works and the name stays blank until the user sets it in Screeb.

Send the `email` attribute **even if your NameID is already the email address**: Screeb reads the address from the attribute, not from the NameID.

### Signatures

- The IdP must **sign the SAML assertion** (or the whole response). RSA-SHA256 is recommended.
- Screeb can sign its authentication requests. Tell your Screeb contact whether your IdP requires signed requests, and which signature algorithm it expects.
- Assertion encryption is not required. If your security policy mandates it, mention it so we check it during the test.

### Assign users

Assign the users or groups who should have access to Screeb to the application. Users who are not assigned are refused by your IdP.

### Notes for common IdPs

- **Microsoft Entra ID**: by default, Entra sends claims with long names such as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. In **Attributes & Claims**, add claims named `email` (source `user.mail`), `given_name` (`user.givenname`) and `family_name` (`user.surname`) with an **empty namespace**.
- **Okta**: under **Attribute Statements**, add `email` to `user.email`, `given_name` to `user.firstName` and `family_name` to `user.lastName`, with the **Unspecified** or **Basic** name format.
- **Google Workspace**: under **Attribute mapping**, map **Primary email** to `email`, **First name** to `given_name` and **Last name** to `family_name`.

## Step 4: Screeb enables SSO for your organization

Once your IdP application is configured, let your Screeb contact know. Screeb then:

- confirms the **email domains** that belong to your organization;
- enables your SSO connection for your organization.

Your connection is private to your organization. It never appears on the public login page, and it is never offered to users outside your organization.

## Step 5: Test the login

Before rolling SSO out to your whole team, we schedule a short call to test a real sign-in end to end and check that the email and names come through correctly.

## Step 6 (optional): Make SSO mandatory

By default, SSO is **added** to the existing login methods: your users can still sign in with their password, Google or Microsoft.

On request, Screeb can make SSO **the only way in** for addresses on your confirmed domains. Password sign-in, password sign-up, Google, Microsoft and any other SSO connection are then refused for those addresses. Passwords are not deleted: if SSO-only is switched off later, they work again.

People whose email is on another domain (agencies, contractors) are not affected and keep their usual login method.

We recommend switching SSO-only on once your existing users have signed in with SSO at least once (see the one-time confirmation below). Users who signed in with a password can still complete that confirmation afterwards, but users who only ever used Google or Microsoft would first have to set a password through **Forgot password**, because those methods are refused once SSO is mandatory.

## What your users will see

**Signing in.** Users open the Screeb login page, enter their work email and click **Continue**. Screeb recognizes the domain and sends them straight to your IdP, so they never see a password field. After signing in with your IdP, they land back in Screeb, signed in.

**First SSO sign-in for an existing Screeb user.** If someone already has a Screeb account (with a password, Google or Microsoft), Screeb asks them, **once**, to confirm the account by signing in with their existing method. Their SSO identity is then connected to the account, and from then on SSO alone is enough. This protects accounts: a sign-in from an IdP is never enough, on its own, to take over an account that already exists. The confirmation must happen within 10 minutes, and is cancelled after 3 wrong passwords (the user then simply starts again from the SSO sign-in).

**New users.** Someone who has no Screeb account yet gets one automatically on their first SSO sign-in. To give them access to your workspaces, invite them from Screeb, or ask your Screeb contact about automatic join for your email domains.

**Invited users.** Invitations work as usual. When SSO applies, the invitation link sends the person through your IdP, with no password to create.

**Starting from your IdP's app portal.** Sign-ins must start from Screeb (SP-initiated). Sign-ins that start from an IdP dashboard tile (IdP-initiated) are not supported. To keep a tile in your app portal, point it at your connection's direct sign-in link, which your Screeb contact can give you. In Microsoft Entra ID, this goes in the **Sign on URL** field. In Okta, use a **Bookmark App**.

## FAQ

**Which attributes are required from the IdP?**
Only `email`. `given_name` and `family_name` are recommended. See the attribute table in step 3.

**Our IAM team needs Screeb's SP details before creating the application. Can you provide them?**
Yes. Ask your Screeb contact: we send you the SP metadata URL, Entity ID and ACS URL first. You then create the application and send us your IdP metadata.

**What if our IdP doesn't provide a metadata file, only URLs and certificates?**
That's fine. Send us your IdP's Entity ID, its SSO URL and its signing certificate, and we build the configuration from them.

**Can we keep password login alongside SSO?**
Yes, that is the default. SSO only becomes mandatory if you ask for it (step 6).

**Our IdP signing certificate is about to expire. What should we do?**
Send your Screeb contact the new metadata (or the new certificate) **before** the old certificate expires, so we can update the connection without interrupting sign-ins.

**How do we enforce multi-factor authentication?**
Through your IdP: Screeb relies on it to authenticate your users, so your IdP's MFA policy applies to every SSO sign-in.

**What happens when someone leaves the company?**
Once they are disabled or unassigned in your IdP, they can no longer sign in to Screeb. A Screeb session that is already open can stay valid for up to 30 days, so to cut access immediately, also remove the person from your organization's members in Screeb. Automatic provisioning (SCIM) is not supported.

**Does signing out of Screeb sign the user out of our IdP?**
No. Signing out of Screeb ends the Screeb session only. Single Logout (SLO) is not supported.

**A user sees an error after signing in with our IdP. What should we check?**

| What the user sees                                                    | Most likely cause                                                                                                                                             |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Sign-in failed. Please try again..."                                 | The assertion has no attribute named exactly `email`, or the IdP signature no longer matches (expired or rotated certificate).                                |
| "Your identity provider sent an address that is not a valid email..." | The `email` attribute holds something other than a single email address (a username, for example).                                                            |
| "Your organization signs in with single sign-on..."                   | SSO is mandatory for this address, and the user tried another method (password, Google, Microsoft). They should enter their work email and continue with SSO. |
| "This platform is invitation-only..."                                 | The platform only accepts invited users, and this person has not been invited yet.                                                                            |
| Your IdP itself refuses the sign-in                                   | The user isn't assigned to the Screeb application in your IdP.                                                                                                |

**Who do we contact if something isn't working?**
Your Customer Success contact, or [support@screeb.app](mailto:support@screeb.app).
