> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.formester.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Set up single sign-on (SSO) with Microsoft Entra

Connect a Microsoft Entra directory to Formester once, then use it to protect forms, to sign your own team in to Formester, or both.

**Available on:** Enterprise. **You'll need:** a Formester owner or admin, and a Microsoft Entra administrator for the directory you are connecting.

## Choose a route

There are two ways to connect a directory. Both produce the same connection.

* **Formester's app (recommended).** Nothing to register in Azure, no client secret to manage or rotate. A Microsoft administrator approves Formester in the directory once.
* **Your own app registration.** Choose it when your organization requires that apps in its directory are registered and owned internally. It is longer, and four separate things must all be right or sign-in fails with no clue as to which one.

## Route 1: Formester's app

1. Go to **Single Sign-On** in the left menu and select **Add connection**.
2. Enter a **Connection name**. Only your team sees this, so name it after the directory it points at, such as **Contoso staff directory**.
3. Leave **Connection type** as **Formester's app (recommended)**.

There is nothing else to fill in. Formester detects which directory you are connecting from the first successful test sign-in.

![The Add Microsoft Entra connection form with Formester's app selected, showing only a connection name field](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/01-add-connection_ae9xf0.png)

4. Decide whether to turn on **Allow guest accounts**. Leave it off unless people invited into the directory from outside it, such as contractors, should be able to sign in.
5. Select **Add connection**.

### Get the directory approved

1. In the **Add these in Azure** panel, select **Approve Formester in your directory**.

![The connection page showing Test connection, Activate connection, and the Approve Formester in your directory link](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/02-approve-panel_1y6ghd4.png)

2. Sign in as a Microsoft administrator for that directory.
3. On the Microsoft **Permissions requested** screen, check that **Consent on behalf of your organization** is ticked. It is ticked for you when you arrive through the link above.

Leave it ticked. If it is cleared, only you are approved and everyone else is prompted to approve Formester for themselves.

![The Microsoft permissions screen with the organization consent checkbox ticked](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/03-consent-screen_1rgsy5r.png)

4. Select **Accept**. You are returned to the Formester connection page.

Microsoft labels Formester as unverified, with the note "This application is not published by Microsoft." That is expected and does not affect what the app can do.

Now go to **Test and activate** below.

## Route 2: your own app registration

Four things must all be right or sign-in fails, usually with no clue as to which one: the redirect URI, the client secret **Value**, the **acct** optional claim, and the Microsoft Graph email permission. Do not skip one because it looks optional.

### Before you begin

1. In Formester, go to **Single Sign-On**, select **Add connection**, and set **Connection type** to **Your own app registration**. An **Add these in Azure** panel appears with a **Redirect URI** and a copy button. Copy that value, you need it in the next step. Do not type it from memory.
2. Keep the Formester tab open. You come back to it at the end.

### Register the application

1. In the Microsoft Entra admin center, go to **App registrations** and select **New registration**.
2. Enter a **Name** your team will recognize, such as **Formester**.
3. Leave **Supported account types** as **Single tenant only**.
4. Under **Redirect URI**, set the platform to **Web**, then paste the redirect URI you copied from Formester.

The platform must be **Web**. Any other choice makes sign-in fail after the person has already logged in.

![The Register an application form with the Web platform selected and the redirect URI pasted](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/01-register_tx9sry.png)

5. Select **Register**.

### Copy the two IDs

On the **Overview** page, copy these two values from **Essentials**:

* **Directory (tenant) ID**
* **Application (client) ID**

![The app registration Essentials panel showing where the tenant and client IDs appear](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/02-copy-ids_qj2bu8.png)

Ignore **Object ID**. Formester does not use it.

### Create a client secret

1. In the left menu, select **Certificates & secrets**, then **New client secret**.
2. Enter a **Description** such as **Formester SSO**, and leave **Expires** on the recommended period.
3. Select **Add**.
4. Copy the **Value**, not the **Secret ID**.

![The client secrets table with the Value column highlighted next to the Secret ID column](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/03-client-secret_t4yzp9.png)

Microsoft shows the **Value** only now. Leave this page before copying it and you have to delete the secret and create another one. Note the **Expires** date too, Formester asks for it.

### Add the optional claims

1. In the left menu, select **Token configuration**, then **Add optional claim**.
2. Set **Token type** to **ID**.
3. Tick **acct** and **email**.
4. Tick **Turn on the Microsoft Graph email permission (required for claims to appear in token)**.

Miss this tick and the email claim never reaches Formester, with no error to tell you why.

![The Add optional claim panel with acct and email ticked and the Graph email permission checkbox highlighted](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/04-optional-claims_1b88v59.png)

5. Select **Add**.

**acct** tells Formester whether someone is a member of your directory or a guest invited into it. Without it Formester cannot tell the difference, and a connection that does not allow guests refuses everyone, including your own staff.

**email** is how Formester identifies the person. Signing in to Formester itself cannot work without it, because the email address is the account key.

### Grant admin consent

1. In the left menu, select **API permissions**.
2. Select **Grant admin consent for your directory**, then confirm.
3. Leave the page and come back to it.

The **Status** column does not refresh in place. Once you return, both permissions read **Granted for your directory**.

![The API permissions table showing both permissions granted](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/05-consent-granted_1cw19eg.png)

Consent is what stops every person being asked to approve Formester on their first sign-in. Where a directory blocks people from approving apps themselves, sign-in fails outright without it.

### Finish the connection in Formester

Back in the Formester tab, fill in:

* **Connection name**, a label only your team sees
* **Microsoft Entra tenant ID**, the **Directory (tenant) ID** you copied
* **Application (client) ID**
* **Client secret**, the **Value** you copied
* **Secret expires on**, the **Expires** date from the secret

![The Formester connection form filled in, with the redirect URI panel beside it](https://storage.crisp.chat/users/helpdesk/website/-/1/5/6/e/156e23ff3485c400/06-formester-connection_10ko6ij.png)

Decide whether to turn on **Allow guest accounts**, then select **Add connection**.

## Test and activate

1. Select **Test connection** and sign in with an account from the directory.

Formester shows **The connection passed its test and is ready to activate.**

2. Select **Activate connection**.

Only active connections can be put on a form or used to sign in to Formester.

## Use the connection

The connection does nothing on its own. Choose what it is for:

* **Protect a form**, so only that directory's staff can open it. Respondents who sign in this way never get a Formester account.
* **Sign your team in to Formester**, so your own staff open the Formester dashboard with their work account.

One connection can do both.

## Rotating the secret

This applies to your own app registration only. Formester's app has no secret for you to manage.

Client secrets expire, and Formester warns owners and admins as the date you recorded approaches. To rotate, create a new client secret in Entra, then in Formester open the connection, select **Replace** next to **Client secret**, paste the new **Value**, and update **Secret expires on**.

Test the connection afterwards. Changing credentials returns a connection to an untested state, so it has to pass its test again.

## Troubleshooting

| What you see | What to do |
| ---- |
| The test never passes, and sign-in reports needing admin approval | Admin consent has not been granted, or was granted for one administrator rather than the organization. Repeat the consent steps for your route. |
| The test fails immediately, before any Microsoft sign-in page appears | Check the **Microsoft Entra tenant ID**. A wrong or mistyped tenant ID means Formester cannot find the directory at all. |
| Sign-in completes and then fails on return | Compare the **Redirect URI** in the Formester panel against the one on the app registration, character for character, and confirm its platform is **Web** rather than SPA or public client. |
| Formester reports the secret is wrong although you just pasted it | You probably pasted the **Secret ID**. Copy the **Value** column instead. If the value is no longer shown, delete that secret and create a new one. |
| Your own staff are refused, and turning on guest accounts lets them in | The **acct** claim is missing. Repeat the optional claims steps, then turn guest accounts back off. |
| Only some people are refused | Under **Enterprise applications**, open Formester and check **Assignment required** in **Properties**. When it is **Yes**, only assigned users and groups can sign in. |