> ## Documentation Index
> Fetch the complete documentation index at: https://staging.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 26 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).

## 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 charges NZD 0, 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**. The domain's chip changes from **Pending** 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>
      Don't reuse an existing app registration, such as the one used for "Continue with Microsoft". SAML needs its own enterprise application.
    </Warning>
  </Step>

  <Step title="Fill in the Basic SAML Configuration">
    In the new application, open **Single sign-on** and 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**.
  </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, turn **Enable SAML SSO** off and save first, then turn it on again with the new URL and save. Changing the URL in place fails with "Failed to update SSO provider with identity service".
    </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**. Pick a test user whose sign-in address is on your verified domain and click **Assign**.
  </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 **Sender** profile. 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**, and click **Get started**. Set **Provisioning Mode** to **Automatic**, paste the **SCIM base URL** into **Tenant URL** and the token into **Secret token**. Click **Test connection**, then **Save**.

    <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">
    Under **Mappings**, click **Provision Microsoft Entra ID Groups**, set **Enabled** to **No**, and click **Save**. Flowsign provisions users only.
  </Step>

  <Step title="Provision the test user on demand">
    From the application's left 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.
  </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">
    Set **Provisioning Status** to **On** and save. Entra then syncs users on its automatic cycle, about every 40 minutes.
  </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                                                                                                          |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| "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. |
| "Failed to update SSO provider with identity service."                       | You changed the metadata URL to a different identity provider in place. | Turn **Enable SAML SSO** off and save, then turn it on with the new URL and save again.                      |
| "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).                            |

## Related

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