# Set up SAML single sign-on

For IT admins: connect DraftPilot to Microsoft Entra ID or Okta with SAML, test sign-in, and move your users to single sign-on.

SAML single sign-on (SSO) lets your users sign in to DraftPilot, in Word and in the browser, with their normal work account. Their password, MFA and access policies stay in your identity provider, and DraftPilot never sees a password.

This guide covers Microsoft Entra ID (formerly Azure AD) and Okta. Other SAML 2.0 identity providers work the same way: create a SAML app with the values below, then give DraftPilot its metadata URL.

To create, update and suspend DraftPilot accounts automatically from your directory, set up [SCIM provisioning](/knowledge-base/how-to-set-up-scim-provisioning) as well.

## Before you start

You need:

-   **A DraftPilot admin account.** Only organization admins can open [Organization settings](https://app.draftpilot.ai/organization-settings?tab=sso).
-   **Admin access to your identity provider**, enough to create an enterprise application (Entra ID) or app integration (Okta) and assign users to it.
-   **Single sign-on on your DraftPilot plan.** If the **Single sign-on (SSO)** tab shows a **Contact us** button, SSO isn't enabled for your organization yet. Click **Contact us**, or email [support@draftpilot.ai](mailto:support@draftpilot.ai), and we'll turn it on.

DraftPilot doesn't create accounts for unknown email addresses. Someone can sign in with SSO only if they already have a DraftPilot account, or a pending invitation, under the email address your identity provider sends. Invite people from the Users page, or let [SCIM provisioning](/knowledge-base/how-to-set-up-scim-provisioning) create their accounts.

## DraftPilot values to copy

Your identity provider needs these values to recognise DraftPilot. They're also shown, with copy buttons, in the first step of the setup checklist. Use the column for the region your organization's data is hosted in. If you're not sure, copy them from the checklist, which always shows your region's values.

| Field | EU | US |
| --- | --- | --- |
| Entity ID (Identifier, Audience URI) | `https://api.draftpilot.ai/saml` | `https://api-us.draftpilot.ai/saml` |
| ACS URL (Reply URL, Single sign-on URL) | `https://api.draftpilot.ai/auth/saml/callback` | `https://api-us.draftpilot.ai/auth/saml/callback` |
| Metadata URL | `https://api.draftpilot.ai/auth/saml/metadata` | `https://api-us.draftpilot.ai/auth/saml/metadata` |

If your identity provider asks for a metadata file instead of individual values, click **Download metadata XML** in the checklist.

Both regions use the same web app, [app.draftpilot.ai](https://app.draftpilot.ai).

## Open the setup checklist

1.  Sign in to DraftPilot in your browser and open [Organization settings > Single sign-on (SSO)](https://app.draftpilot.ai/organization-settings?tab=sso).
2.  If you haven't connected an identity provider yet, you'll see **Set up single sign-on**. Click **Set up SAML**.

The checklist has four steps:

1.  **Add DraftPilot to your identity provider.** Shows the values above and a short guide for Microsoft Entra ID and Okta.
2.  **Connect your identity provider.** Where you paste your identity provider's metadata URL.
3.  **Test sign-in.** Creates a test sign-in link.
4.  **Migrate users to SSO.** Switches existing users from passwords to SSO.

A status badge at the top of the panel shows **Not configured**, **Off** or **Connected**.

## Set up Microsoft Entra ID

### Create the enterprise application

1.  Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) or the [Azure portal](https://portal.azure.com).
2.  Go to **Enterprise applications** and click **New application**.
3.  Click **Create your own application**.
4.  Name it `DraftPilot`, select **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.

### Configure single sign-on

1.  In the new application, open **Single sign-on** and select **SAML**.
2.  In **Basic SAML Configuration**, click **Edit** and enter:
    -   **Identifier (Entity ID):** your DraftPilot Entity ID
    -   **Reply URL (Assertion Consumer Service URL):** your DraftPilot ACS URL
3.  Leave the other fields empty and click **Save**.

### Check the claims

1.  In **Attributes & Claims**, click **Edit**.
2.  Set **Unique User Identifier (Name ID)** to `user.mail`.
3.  Keep the default email address claim (`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`) set to `user.mail`.

DraftPilot matches people by email address. It reads the Name ID first, then the email claim, so at least one of them must contain the address the person's DraftPilot account uses. The name claims are optional. DraftPilot takes each person's name from their invitation or from SCIM, not from the sign-in.

### Copy the metadata URL

1.  In **SAML Certificates**, find **App Federation Metadata Url** and copy it. It starts with `https://login.microsoftonline.com/`.
2.  Leave the signing option as **Sign SAML assertion** (the default) or **Sign SAML response and assertion**. DraftPilot rejects responses whose assertion isn't signed.

### Assign users

1.  Open **Users and groups** and click **Add user/group**.
2.  Assign the people or groups who should use DraftPilot. Include yourself so you can run the test sign-in.

Now [connect your identity provider to DraftPilot](#connect-your-identity-provider-to-draftpilot).

## Set up Okta

### Create the SAML app

1.  Sign in to the Okta Admin Console.
2.  Go to **Applications > Applications** and click **Create App Integration**.
3.  Select **SAML 2.0** and click **Next**.
4.  Set **App name** to `DraftPilot` and click **Next**.

### Configure SAML

1.  On the **Configure SAML** step, enter:
    -   **Single sign-on URL:** your DraftPilot ACS URL. Leave **Use this for Recipient URL and Destination URL** selected.
    -   **Audience URI (SP Entity ID):** your DraftPilot Entity ID
2.  Set **Name ID format** to **EmailAddress** and **Application username** to **Email**.
3.  Under **Attribute Statements**, add `email` with the value `user.email`. A name statement is optional. DraftPilot doesn't read it.
4.  Click **Next**. On the **Feedback** step, choose **I'm an Okta customer adding an internal app** and click **Finish**.

### Copy the metadata URL

1.  Open the app's **Sign On** tab.
2.  Copy the **Metadata URL**.

### Assign users

1.  Open the **Assignments** tab.
2.  Click **Assign > Assign to People** or **Assign to Groups**, and assign everyone who should use DraftPilot. Include yourself so you can run the test sign-in.

## Connect your identity provider to DraftPilot

1.  In the checklist, expand **Connect your identity provider**.
2.  Paste the metadata URL into **Identity provider metadata URL** and click **Fetch**.
3.  Check that **Identity provider entity ID**, **Identity provider SSO URL** and **Identity provider certificate** are filled in. You can't edit them by hand. They always come from your metadata.
4.  Turn on the **Enable SAML SSO** switch at the top of the panel.
5.  Click **Save SAML settings** and wait for **SAML settings saved successfully**. The switch doesn't take effect until you save.

Switching SAML on doesn't change how anyone signs in yet. People who use a password keep using it until you [migrate them](#move-users-to-single-sign-on).

## Test sign-in

1.  Expand **Test sign-in** and click **Test SAML login**.
2.  Click **Copy URL** and open the link in a private or incognito window, or in a different browser. Your current browser may already be signed in to your identity provider, which hides problems a signed-out user would hit.
3.  Sign in at your identity provider as yourself. If it works, you land in DraftPilot.

The test signs you in with your own DraftPilot account, so your account must be assigned to the app in your identity provider. A successful test also switches your own account to SSO sign-in.

## Move users to single sign-on

Users created after SSO is set up get your organization's default sign-in method. Existing users who signed in with a password keep doing so until you move them.

1.  Expand **Migrate users to SSO**. It shows how many users already sign in with SSO.
2.  Click **Migrate users to SSO** (the button shows how many users will move) and confirm.

From then on, those users see **Connect to SSO** on the DraftPilot sign-in screen and are sent to your identity provider. Super admins and external users (people from other organizations you've invited) are skipped and keep their passwords.

To undo this, use **Revert users to email auth** in the same step. Reverted users sign in with a DraftPilot password again. Anyone who never had one can set it with **Forgot password?**.

Tell your users what's changing. [Signing in to DraftPilot](/knowledge-base/signing-in-to-draftpilot) explains the SSO sign-in screen from their side.

## Optional: require reauthentication

Once SSO is configured, you'll see **Require reauthentication on every sign-in**. Turn it on to make your identity provider ask for credentials each time someone signs in to DraftPilot, even if they're already signed in there. Your identity provider decides how they reauthenticate, for example with a password, passkey or authenticator app.

DraftPilot's own two-factor authentication requirement doesn't apply to users who sign in with SSO. Use your identity provider's MFA for them.

## Troubleshooting

### "Failed to fetch metadata. Please check the URL and try again."

-   The URL must start with `https://`.
-   Use the **metadata** URL, not the sign-in or login URL. In Entra ID it's **App Federation Metadata Url**. In Okta it's the **Metadata URL** on the **Sign On** tab. Copy all of it, including any query string such as `?appid=...`.
-   DraftPilot's servers fetch the URL over the internet, so a metadata URL that only works inside your network or VPN won't work. If you can't publish one, email [support@draftpilot.ai](mailto:support@draftpilot.ai).

### Saving doesn't show "SAML settings saved successfully"

SAML can't be switched on until the entity ID, SSO URL and certificate are filled in. Click **Fetch** first, then save again.

### "Could not generate SAML test URL"

SAML must be switched on and saved before you can test. Turn on **Enable SAML SSO**, click **Save SAML settings**, then try again. If it still fails, click **Fetch** again in case your identity provider's certificate has changed.

### "No account found for this email address"

DraftPilot has no account or pending invitation for the email the user typed. Check that they're using their work email, then invite them or provision them with SCIM. Also check they're signing in to the right region: when an email has accounts in both, DraftPilot asks the user to pick **EU** or **US**.

### "SAML authentication is not configured for your organization"

The user's account is set to SSO, but SAML is switched off for your organization. Turn on **Enable SAML SSO** and click **Save SAML settings**, or revert those users to email sign-in.

### "Authentication failed. Please try again." after signing in at the identity provider

DraftPilot received a sign-in from your identity provider but rejected it. Common causes:

-   **The email doesn't match.** Neither the Name ID nor the email claim contains an address that has an account or invitation in your organization. In Entra ID this usually means the Name ID is the user's UPN (for example `name@corp.example.net`) and the user has no `mail` attribute. Set the Name ID to `user.mail` and check the user's email in your directory.
-   **The assertion isn't signed.** Use **Sign SAML assertion** or **Sign SAML response and assertion** in Entra ID. Okta signs assertions by default.
-   **The certificate changed or expired.** When your identity provider rotates or renews its signing certificate, click **Fetch** again and then **Save SAML settings**. DraftPilot rejects sign-ins signed with an expired certificate.
-   **The Entity ID or ACS URL is wrong**, for example the EU values used for a US organization.

### "Invalid SAML response format."

The response from your identity provider contained no email address, in either the Name ID or an email claim. Check your claims setup above.

### Some users still get a password prompt

They haven't been migrated. Run **Migrate users to SSO** again. If newly invited or provisioned users keep arriving on password sign-in, ask [support@draftpilot.ai](mailto:support@draftpilot.ai) to set your organization's default sign-in method to SAML single sign-on.

### Someone's email address is changing

The email your identity provider sends must match the user's DraftPilot account. If your organization is changing email domains, email [support@draftpilot.ai](mailto:support@draftpilot.ai) and we'll update the accounts to match.

## Need help?

Email [support@draftpilot.ai](mailto:support@draftpilot.ai) with your organization name, your identity provider, and the exact error message. A screenshot of your identity provider's SAML settings helps too. Never send passwords or private keys.