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

# Example: Microsoft Entra

> Set up enterprise SSO and SCIM provisioning step by step in Microsoft Entra's generic SAML application

This walkthrough uses Microsoft Entra as the identity provider. It configures Entra's generic (non-gallery) SAML application, the same generic setup any SAML 2.0 provider uses, so the steps map directly onto [SAML and SCIM settings](https://docs.connectly.ai/enterprise-sso/saml-and-scim-settings.md). Connectly has run it end to end both ways, with a setup link and manually.

> [!WARNING]
>
> Create an **Enterprise application** with SAML single sign-on. An **App registration** does not work with Connectly.

***

## Before you start in Entra

| Topic | What is needed | If it is not met |
| - | - | - |
| Licence | Assigning people one by one works in every Entra ID edition. For which edition covers single sign-on and provisioning to a non-gallery application, see [Microsoft Entra licensing](https://learn.microsoft.com/en-us/entra/fundamentals/licensing). | Assigning or provisioning groups needs Entra ID P1 or P2. Without it, Entra says groups are not available for assignment: assign people individually. |
| Admin role | Cloud Application Administrator, Application Administrator or Global Administrator, to create and configure the application. | A Cloud Application Administrator cannot create users or edit a user's Email. A User Administrator does that. |
| Email address | Entra's default email source, `user.mail`, is empty for people without a mailbox. | Set each person's Email in Entra, or send the user principal name as the email (Steps 1 and 3). |

Where a step differs between the two ways Connectly hands over the values, it says **Setup link** or **Manual**. With a setup link, keep the wizard open next to Entra: its Single Sign-On part belongs to Step 1 and its Provisioning part to Step 3.

***

**1. Create the Entra application and set up sign-in**

1. In the Microsoft Entra admin center (or the Azure portal), open **Enterprise applications** and click **New application**.
2. Click **Create your own application**, name it (for example `Connectly`), choose **Integrate any other application you don't find in the gallery (Non-gallery)** and click **Create**.
3. Open **Single sign-on** and choose **SAML**.
4. In **Basic SAML Configuration**, click **Edit** and enter the **Identifier (Entity ID)**, **Reply URL** and **Sign on URL**. Leave **Relay State** and **Logout URL** empty, then **Save**.
5. In **Attributes & Claims**, keep **Unique User Identifier (Name ID)** as `user.userprincipalname`. The `emailaddress` claim defaults to `user.mail`: keep it if every person has an Email in Entra, otherwise change its source attribute to `user.userprincipalname`.
6. In **SAML Certificates**, give Connectly your application's metadata (below).
7. In **Properties**, set **Assignment required** to **Yes**, so only people you assign can sign in. With **Visible to users** set to **Yes**, people also get a Connectly tile in My Apps that opens the Sign on URL.

> [tab] Setup link
>
> * The **Identifier** is the wizard's **Service Provider Entity ID** and the **Reply URL** is its **Single Sign-On URL**, both on the wizard's **Create Application** page. The **Sign on URL** comes from Connectly.
> * Copy Entra's **App Federation Metadata Url** into **Metadata URL** on the wizard's **Configure Connection** page, **Automatic** tab. Leave **Advanced Settings** as they are, click **Create Connection** and confirm with **Proceed**.
> * Keep **Attribute Mapping** as it is. On **Test SSO** you can click **Enable Connection**, then **Proceed**, without testing: Step 4 tests the sign-in end to end.

> [tab] Manual
>
> * Connectly sends the **Identifier**, **Reply URL** and **Sign on URL**.
> * Download the **Federation Metadata XML** and send the file to Connectly.

**2. Assign people and confirm your domain**

1. In the application, open **Users and groups**, click **Add user/group**, select the people who will use Connectly and click **Assign**. Only assigned people can sign in, and only assigned people are provisioned.
2. If you prove your domain by DNS, publish the TXT record Connectly sent you at your DNS provider and tell Connectly when it is live. Connectly looks it up itself; nothing needs to be uploaded.
3. Connectly verifies the domain and links your connection to your Connectly business. You hear back when sign-in is switched on.

**3. Set up provisioning (SCIM)**

Skip this step if you do not use SCIM; see [SSO without SCIM](https://docs.connectly.ai/enterprise-sso/without-scim.md).

1. In the application, open **Provisioning**. In the classic view, click **Get started** and set **Provisioning Mode** to **Automatic**; in the new view, open **Connectivity**.
2. Under **Admin Credentials**, choose **Bearer authentication**. Paste the SCIM endpoint into **Tenant URL** and add `?aadOptscim062020` at its end, which turns on Microsoft's SCIM 2.0 compliance fixes. Paste the SCIM token into **Secret Token**. Click **Test Connection**, wait for Entra to confirm the credentials are authorized, then **Save**.
3. Open **Attribute mapping** (classic view: **Provision Microsoft Entra ID Users**; new view: the **Users** tab) and check the mappings against the table below. If you assign groups, turn off provisioning of the groups themselves (classic view: **Provision Microsoft Entra ID Groups**, **Enabled** **No**). Their members are still provisioned.
4. Under **Settings**, set **Scope** to **Sync only assigned users and groups**.
5. Do not start provisioning yet. Test with one person first (Step 4).

> [tab] Setup link
>
> The endpoint and the token are on the wizard's **Provisioning** page. The SCIM endpoint is its **Provisioning Endpoint URL** without the final slash. **Generate Token** shows the token once: click **Copy And Close** and paste it into Entra right away. The attributes the wizard lists are already in Entra's default mapping. When Entra has saved the credentials, click **Done** on that page.

> [tab] Manual
>
> Connectly sends the SCIM endpoint, and the token over a secure channel.

| Connectly field (SCIM) | Entra source | Note |
| - | - | - |
| `userName` | `userPrincipalName` (default) | Must equal the sign-in Name ID. Do not change it. |
| `emails[type eq "work"].value` | `mail` (default) | Change to `userPrincipalName` if your people have no Email, as for the `emailaddress` claim. |
| `displayName` | `displayName` (default) | The name Connectly shows, cut to 32 characters. |
| `externalId` | `mailNickname` (default) | Keep the default. |
| `active` | `Switch([IsSoftDeleted], ...)` (default) | Becomes `false` when a person is unassigned, disabled or deleted in Entra. |

**4. Test with one person, then turn provisioning on**

1. In **Provisioning**, open **Provision on demand**, pick one assigned person and click **Provision**. Entra should report that the user was created, and list the values it sent.
2. Tell Connectly. We confirm the person is in your Connectly business with the agreed role.
3. That person opens the Sign on URL in a private browser window and signs in with their Microsoft account. They land in your Connectly business. A first Microsoft sign-in may ask them to change a temporary password or register MFA.
4. When the test works, open the provisioning **Overview** and click **Start provisioning**. Entra provisions everyone assigned, then repeats on its own schedule (Microsoft runs an incremental cycle roughly every 40 minutes). **Provision on demand** stays available for anyone who cannot wait.

> [!TIP]
>
> Test sign-ins from a browser that is not already signed in to Microsoft as someone else. Microsoft reuses the session it has, often the admin's own, and Connectly then refuses that account with `error=jit_disabled`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.