> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowsign.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Flowsign is one word with a lowercase s.
> The REST API base URL is https://my.flowsign.app and every endpoint lives under /api/v1.
> When answering API questions, cite the HTTP method and endpoint path.
> API access needs the Enterprise plan and an API key with the API access permission.

# Microsoft Entra ID setup

> Connect Microsoft Entra ID to Flowsign so members sign in with single sign-on and are provisioned automatically.

<Note>
  Validated against the Microsoft Entra admin centre on 28 September 2026. Microsoft changes these screens, so if a step looks different, check Microsoft's documentation for the current name.
</Note>

This guide is for the organisation Owner connecting Microsoft Entra ID to Flowsign. Work through it top to bottom. Every step is required unless it is marked optional, and the order matters: several steps depend on a value or setting from the one before.

Keep the [Microsoft Entra admin centre](https://entra.microsoft.com) open alongside Flowsign, because values are copied from one to the other. For what each Flowsign setting does, see [Organisation security](/guides/settings/security).

<Frame caption="Organisation security, where the verified domain and SAML SSO cards live.">
  <img src="https://mintcdn.com/doc-a97e5290/PTzM8Xl3JBDj-Kc9/images/guides/settings/security.png?fit=max&auto=format&n=PTzM8Xl3JBDj-Kc9&q=85&s=239c46058fd634d8e064535740b476a6" alt="The organisation security settings page showing verified domains and the Single Sign-On (SAML) card" width="2880" height="1800" data-path="images/guides/settings/security.png" />
</Frame>

## Before you start

<Steps>
  <Step title="Check your Flowsign plan and role">
    Single sign-on and user provisioning need the **Enterprise** plan, and only an **Owner** can change these settings.
  </Step>

  <Step title="Use a Microsoft work account with Global Administrator">
    You need a Microsoft work account that is a **Global Administrator** of the Entra tenant.

    A personal Microsoft account (Outlook, Hotmail, or a Gmail address used to sign up for Azure) can open the Entra admin centre, but the Microsoft 365 admin centre refuses it, and that is where licences live. If all you have is a personal login, create a work user in Entra, for example `admin@yourcompany.com`, give it the **Global Administrator** role, and use that account from here on.
  </Step>

  <Step title="Get a Microsoft Entra ID P1 or P2 licence">
    Non-gallery SAML applications need a **Microsoft Entra ID P1** or **P2** licence on the tenant.

    To start a free trial, go to the [Microsoft 365 admin centre](https://admin.microsoft.com), then **Billing**, **Purchase services**, search for "Entra", choose **Microsoft Entra ID P2** and click **Start free trial**. Microsoft asks for a card to confirm your identity but doesn't charge it, and the trial expires rather than converting to a paid subscription.

    <Note>
      The **Licenses** page in the Entra admin centre shows a greyed-out Try/Buy button. Go through the Microsoft 365 admin centre instead.
    </Note>
  </Step>

  <Step title="Verify your email domain in Entra">
    In the Entra admin centre, open **Custom domain names** and verify your email domain, such as `yourcompany.com`.

    A domain can be verified in one Entra tenant only. If verification fails even though the DNS record is in place, another tenant already holds the domain, often one from an older Azure signup. Open `https://login.microsoftonline.com/<your-domain>/.well-known/openid-configuration` in a browser: the response includes the id of the tenant that owns it.
  </Step>
</Steps>

## Part 1: Verify your domain in Flowsign

Do this first. SSO can't be turned on in Flowsign until a domain is verified, and Entra must send addresses on that domain.

<Steps>
  <Step title="Add the domain">
    In Flowsign, go to **Settings**, then **Organisation security**. The **Verified domains** card is first on the page for this reason. Enter your domain in **Add an email domain** and click **Add domain**.
  </Step>

  <Step title="Add the TXT record">
    Copy the TXT record Flowsign shows, `flowsign-verification=<token>`. At your DNS provider, add it as a TXT record with the host `@` (or the domain name itself, if your provider asks for it).

    This is the same DNS ownership check Microsoft, Google and Okta use.
  </Step>

  <Step title="Check DNS">
    Back in Flowsign, click **Check DNS**. While the page is open, Flowsign also checks on its own and the domain shows **Waiting for DNS**. The domain's chip changes to **Verified** once the record is found. DNS changes can take a while to appear, so check again later if it isn't found straight away.
  </Step>
</Steps>

## Part 2: Create the SAML application in Entra

<Steps>
  <Step title="Create a non-gallery enterprise application">
    In the Entra admin centre, go to **Enterprise applications**, click **New application**, then **Create your own application**. Give it a name such as "Flowsign", choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.

    <Warning>
      Pick the **Non-gallery** option, not **Register an application to integrate with Microsoft Entra ID (App you're developing)**. That option creates an app registration, which Entra locks to OpenID Connect: its **Single sign-on** page shows **OIDC-based Sign-on** with no SAML choice, and it can't be switched. Don't reuse an existing app registration either, such as the one used for "Continue with Microsoft".
    </Warning>
  </Step>

  <Step title="Fill in the Basic SAML Configuration">
    In the new application, open **Single sign-on**. You should see a choice of methods: choose **SAML**. In box 1, **Basic SAML Configuration**, click **Edit** and copy these values from the **Single Sign-On (SAML)** card in Flowsign's **Organisation security** page:

    * **Identifier (Entity ID)**: the **Entity ID / SP metadata URL**.
    * **Reply URL (Assertion Consumer Service URL)**: the **ACS URL**. Leave **Index** blank.
    * **Sign on URL**: the **App tile URL**.

    Click **Save**.
  </Step>

  <Step title="Set the Name ID claim">
    In box 2, **Attributes & Claims**, click **Edit**. Click the row **Unique User Identifier (Name ID)**, set **Name identifier format** to **Email address** and **Source attribute** to `user.userprincipalname`, then click **Save**.

    These are Entra's defaults, so the row may already read `user.userprincipalname [nameid-format:emailAddress]`. If it does, leave it.

    <Warning>
      Edit the existing rows in this step and the next. Don't use **Add new claim**, and don't change a claim's **Name** or **Namespace**. Only the **Source attribute** changes.
    </Warning>
  </Step>

  <Step title="Change the email address claim">
    Still in **Attributes & Claims**, click the row that starts with `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Change **Source attribute** from `user.mail` to `user.userprincipalname` and click **Save**.

    Cloud-only users with no mailbox have an empty `mail` attribute. Flowsign matches members by the email address the identity provider sends, and that address must be on your verified domain, so an empty value fails sign-in.

    Leave the `givenname`, `surname` and `name` claims as they are.
  </Step>

  <Step title="Copy the metadata URL">
    In box 3, **SAML Certificates**, copy the **App Federation Metadata Url**. You paste it into Flowsign next.
  </Step>
</Steps>

## Part 3: Connect Flowsign

<Steps>
  <Step title="Turn on SAML SSO">
    In Flowsign, go to **Settings**, **Organisation security**, and the **Single Sign-On (SAML)** card. Turn on **Enable SAML SSO** and paste the **App Federation Metadata Url** into **IdP metadata URL**.
  </Step>

  <Step title="Save">
    Click **Save changes**. Flowsign shows "SSO enabled successfully", and the card's chip changes to **Enabled**. The chip only shows **Enabled** once the change is saved.

    <Note>
      If you are replacing a different identity provider, paste the new URL over the old one and save. Flowsign swaps the provider for you. If the new URL can't be registered, the old provider stays in place.
    </Note>
  </Step>
</Steps>

## Part 4: Assign users and test sign-in

<Steps>
  <Step title="Assign a test user">
    In Entra, open the application, then **Users and groups**, and click **Add user/group**. Under **Users and groups**, click **None Selected**, search for a test user whose sign-in address is on your verified domain, tick them and click **Select**, then click **Assign**. The role stays greyed out as **User**, which is expected.

    Entra assigns whoever created the application automatically, so you may see your admin account listed too.

    If you need a test user, create one under **Users**, **New user**, **Create new user**, with the user principal name on your verified domain. Entra only shows the password once. If you didn't copy it, open the user and click **Reset password** for a new temporary one.

    Don't test with a Flowsign Owner who uses two-factor authentication. Flowsign turns them away with "Owners with two-factor sign in with their password and code, not SSO."
  </Step>

  <Step title="Sign in with SSO">
    Open the Flowsign sign-in page in a private browser window. Type the test user's email or your company domain in the SSO box, click **Continue with SSO**, and sign in at Microsoft.
  </Step>

  <Step title="Check the new member">
    The first sign-in adds the person as a member of the default workspace with the **Viewer** profile, named from the name claims Entra sends. No invitation is needed. Check that they appear under **Settings**, **Members**.

    If the user already had a Flowsign password account with the same email, SSO is linked to that account rather than creating a second one.

    Leave **Require SSO** off until this sign-in works.
  </Step>
</Steps>

## Part 5: User provisioning with SCIM (recommended)

With provisioning on, Entra adds members before they first sign in, keeps their names in sync, and deactivates them in Flowsign when they are disabled in Entra. Without it, SSO only adds members when they first sign in, and never removes anyone.

<Steps>
  <Step title="Generate a SCIM token in Flowsign">
    In the **User provisioning (SCIM)** card, click **Generate token** and copy the token straight away, because it is shown once. Copy the **SCIM base URL** too.
  </Step>

  <Step title="Connect provisioning in Entra">
    In Entra, open the application, then **Provisioning**. If Entra offers **Get started** or **Connect your application**, click it. Then open **Connectivity** from the provisioning menu:

    * **Select authentication method**: **Bearer authentication**.
    * **Tenant URL**: the **SCIM base URL**.
    * **Secret token**: the token.

    Click **Test connection**, then **Save** straight away. **Save** stays greyed out until the test passes.

    <Warning>
      Once saved, Entra hides the token behind a placeholder. Clicking **Test connection** again without pasting the token fails with "Invalid or missing SCIM token", even though the saved token still works.
    </Warning>

    <Warning>
      If the Flowsign [IP allowlist](/guides/settings/security#ip-allowlist) is on, allow Entra's provisioning addresses, otherwise Flowsign refuses every provisioning call.
    </Warning>
  </Step>

  <Step title="Turn off group provisioning">
    Flowsign provisions users only. Microsoft's newer provisioning screen has no switch for this, so use the legacy one: from the provisioning menu, open **Attribute mapping** and click **Click here to switch to the legacy experience** in the banner. Expand **Mappings**, click **Provision Microsoft Entra ID Groups**, set **Enabled** to **No**, and click **Save**.

    Leave the **Users** mappings as they are.
  </Step>

  <Step title="Provision the test user on demand">
    From the provisioning menu, open **Provision on demand** and run it for your test user. All four steps should succeed, and the member appears in Flowsign with their display name filled in, before they ever sign in.

    If the test user already signed in with SSO in Part 4, **Perform action** says the user was updated rather than created. Entra has matched the existing member, so there's no duplicate. Don't invite them in Flowsign: from now on, add people by assigning them to the application in Entra.
  </Step>

  <Step title="Test offboarding (optional)">
    In Entra, set the test user's **Account enabled** to **No**, then run **Provision on demand** again. In Flowsign, the member shows under **Deactivated**, and the audit log has a deactivation entry. Re-enable the user in Entra afterwards if you still need them.
  </Step>

  <Step title="Turn on automatic provisioning">
    Open **Provisioning** from the provisioning menu, set **Provisioning Status** to **On** and save. Entra then syncs users on its automatic cycle, about every 40 minutes.
  </Step>
</Steps>

### Replacing the SCIM token

Do this after you rotate or revoke the token in Flowsign, or if provisioning starts failing with "Invalid or missing SCIM token".

<Steps>
  <Step title="Generate a new token in Flowsign">
    In the **User provisioning (SCIM)** card, click **Rotate token** (or **Generate token** if none is active) and copy it. The old token stops working immediately.
  </Step>

  <Step title="Paste it into Entra">
    In Entra, open the application, then **Provisioning**, then **Connectivity**. Clear **Secret token**, paste the new token, click **Test connection**, then **Save**. Leave **Tenant URL** as it is: the SCIM base URL is the same for every organisation.
  </Step>

  <Step title="Restart provisioning if the organisation changed">
    If the token belongs to a different Flowsign organisation from before, open **Overview** in the provisioning menu and click **Restart provisioning**. Entra otherwise keeps sending updates for members it created in the old organisation, and they fail.
  </Step>
</Steps>

## Part 6: Require SSO (optional)

<Steps>
  <Step title="Turn on Require SSO">
    Once a test sign-in works, turn on **Require SSO** in the **Single Sign-On (SAML)** card. Members on your verified domains must then sign in through Entra, and other members' current sessions end, so let them know first.

    <Note>
      Owners can still sign in with their password when **Require SSO** is on, so you can't lock yourself out if Entra is unavailable.
    </Note>
  </Step>
</Steps>

## Troubleshooting

| Message                                                                                           | What it means                                                                                           | Fix                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Single sign-on** shows **OIDC-based Sign-on** with no SAML option                               | The application was created as an app registration ("App you're developing").                           | Create a new one with the **Non-gallery** option, see [Part 2](#part-2-create-the-saml-application-in-entra). Delete the old one under **App registrations**.                 |
| Sign-in fails with `saml_assertion_no_email`, "SAML Assertion does not contain an email address"  | The email claim still reads `user.mail`, which is empty for users without a mailbox.                    | Change the email address claim's **Source attribute** to `user.userprincipalname`, see [Part 2](#part-2-create-the-saml-application-in-entra). Retry in a new private window. |
| "No Flowsign organisation is set up for that identity provider."                                  | The address Entra sent is not on a verified domain.                                                     | Fix the claims in [Part 2](#part-2-create-the-saml-application-in-entra), or verify that domain in Flowsign.                                                                  |
| "Owners with two-factor sign in with their password and code, not SSO."                           | You signed in through SSO as an Owner who has two-factor authentication turned on.                      | Sign in with your password and code, and test SSO with a different member.                                                                                                    |
| "We couldn't complete SSO sign-in. Please try again."                                             | Usually a stale session in that browser.                                                                | Retry in a private browser window.                                                                                                                                            |
| "Switch to an account that has permission" in the Microsoft 365 admin centre                      | You are signed in with a personal Microsoft account.                                                    | Sign in with a work account that is a Global Administrator.                                                                                                                   |
| "Unable to verify domain name" in Entra, with the TXT record present                              | Another Entra tenant already owns the domain.                                                           | Find that tenant with the discovery URL in [Before you start](#before-you-start).                                                                                             |
| "Invalid or missing SCIM token" on **Test connection**                                            | The **Secret token** box holds the hidden placeholder, an old token, or something other than the token. | Paste the current token again, test, then save. See [Replacing the SCIM token](#replacing-the-scim-token).                                                                    |
| **Provision on demand** skips the user with **RedundantSoftDelete** and **IsActive** set to False | The user is disabled in Entra, often left over from the offboarding test.                               | Turn **Account enabled** back on for the user in Entra and run **Provision on demand** again.                                                                                 |

## Related

* [Organisation security](/guides/settings/security)
* [Setting up your organisation](/guides/organisation-setup)
* [Members](/guides/settings/members)