# Azure Entra ID

This guide will walk you through setting up automatic user provisioning between Azure Entra ID (formerly Azure Active Directory) and stacksync.

### Overview

By the end of this guide, you will have:

* ✅ SAML-based Single Sign-On configured
* ✅ Automatic user provisioning via SCIM
* ✅ Role-based access control
* ✅ Users automatically created/updated/deactivated in stacksync

**Estimated time:** 30-45 minutes

***

### Prerequisites

Before you begin, ensure you have:

* [ ] **Azure Entra ID admin access** with at least **Cloud Application Administrator** role
* [ ] **stacksync owner account**
* [ ] Your company's **email domain** (e.g., `acme.com`)
* [ ] List of users who should have access

***

### Part 1: Create Enterprise Application in Azure

#### Step 1.1: Navigate to Enterprise Applications

1. Sign in to the **Azure Portal**: <https://portal.azure.com>
2. In the search bar at the top, type **"Microsoft Entra ID"** and select it
3. In the left sidebar, click **Enterprise applications**

<figure><img src="/files/vBUL8uLQ2Xlx6iXaQwEY" alt=""><figcaption></figcaption></figure>

#### Step 1.2: Create New Application

1. Click **+ New application** (top left)
2. Click **+ Create your own application**
3. Enter the application name: **stacksync-example**
4. Select: **"Integrate any other application you don't find in the gallery (Non-gallery)"**
5. Click **Create**

<figure><img src="/files/4wvv9wuZ2rguOVbcrBgo" alt=""><figcaption></figcaption></figure>

Wait a few seconds for Azure to create the application.

***

### Part 2: Configure SAML Single Sign-On

#### Step 2.1: Start SAML Setup

1. In your **stacksync-example** enterprise application, click **Single sign-on** in the left sidebar
2. Click the **SAML** tile

<figure><img src="/files/i2JHxPLMBe1fY7wR2Eib" alt=""><figcaption></figcaption></figure>

#### Step 2.2: Download Azure Metadata

**Before** configuring anything, download your Azure metadata file:

1. Scroll down to section **"3. SAML Certificates"**
2. Under **"Token signing certificate"**, click **Edit** (pencil icon on the right)
3. Click the **three dots menu (...)** next to the Active certificate
4. Select **"Download federated certificate XML"** from the dropdown menu
5. Save the file (e.g., `AzureMetadata.xml`)

<figure><img src="/files/YEFCk9RjibcrsbaZfVX5" alt=""><figcaption></figcaption></figure>

#### Step 2.3: Configure SSO in your workspace

The SSO configuration should only be done once per company domain. All domains will be connected under the same SSO configuration

1. Navigate to your workspace settings&#x20;
2. Choose Azure AD (Entra ID) as your identity provider
3. Upload the federated certificate XML file you downloaded from Azure in the step above
4. You can choose to "Restrict login to SSO only for this domain" using the checkbox. This will make it so users with this domain will only be able to login via the SSO flow
5. Click continue

<figure><img src="/files/WjPYrlerU5znQ9a81MEk" alt=""><figcaption></figcaption></figure>

6. You should now see a page with all the necessary info to continue the setup in Azure.

<figure><img src="/files/CAqszzqCx4lSc7Y5tscF" alt=""><figcaption></figcaption></figure>

***

#### Step 2.4: Configure Basic SAML Settings

Once you have terminated the SSO configuration in your workspace you can continue with the setup in Azure:

1. Go back to your Azure SAML setup page
2. Click **Edit** on section **"1. Basic SAML Configuration"**
3. Fill in the values **provided by stacksync support**:

**Identifier (Entity ID):**

```
urn:auth0:stacksync:companydomain-com-sso-azure-ad
```

*(Use the exact value from the above step)*

**Reply URL (Assertion Consumer Service URL):**

```
https://auth.stacksync.com/login/callback?connection=companydomain-com-sso-azure-ad
```

*(Use the exact value from the above step)*

**Sign on URL (optional):**

```
https://stacksync.com/login
```

4. Click **Save**
5. Close the panel by clicking **X**

<figure><img src="/files/Qgy1FkFTw0h8x2JKOBGh" alt=""><figcaption></figcaption></figure>

#### Step 2.5: Configuring email claim&#x20;

This is needed because some emails could have upper case letter making the SSO login not work as expected.

1. Edit the Attributes & Claims section

<figure><img src="/files/eAfxNcKbiKfBMXflD7nl" alt=""><figcaption></figcaption></figure>

2. Click on the user.mail claim to start editing it

<figure><img src="/files/kaaCiihM9ynN1q8rAOYP" alt=""><figcaption></figcaption></figure>

3. Change the source radio button to Transformation (this action should open a side pabel)
4. In the Transformation field drop down choose ToLowercase()
5. In the Attribute name field dropdown choose user.mail
6. Click add and then Save on the main page

<figure><img src="/files/YdAxlSWOoPXz6M3zh2jK" alt=""><figcaption></figcaption></figure>

***

### Part 3: Set Up Automatic User Provisioning (SCIM)

#### Step 3.1: Generate a api token for your workspace

1. In your stacksync workspace settings scroll down to "Stacksync Workspace API Key"
2. Create a api key for scim use.

<figure><img src="/files/Phjadzje89hSDK5m0PN0" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/PDOIJsQygT6zl1paN8Lj" alt=""><figcaption></figcaption></figure>

#### Step 3.2: Enable Automatic Provisioning

1. In your **stacksync** enterprise application, click **Provisioning** in the left sidebar
2. Click **+ New configuration** button (at the top)
3. On the "New provisioning configuration" page:
   * **Select authentication method:** Bearer authentication (default)
   * **Tenant URL:** Paste the URL provided by stacksync support

```
     https://api.stacksync.com/v1/workspaces/[your-workspace-id]/scim/v2
```

* **Secret Token:** Paste the token that you generated in your workspace

4. Click **Test connection**
   * You should see: ✅ "Connection test for 'stacksync-example' was successful"
5. Click **Create** (bottom left)

<figure><img src="/files/gNVDmcwB3pdWm6nNYW5Z" alt=""><figcaption></figcaption></figure>

***

### Part 4: Create App Roles for stacksync

App Roles define which permission level users have in stacksync (viewer or editor).

#### Step 4.1: Navigate to App Registrations

1. In the Azure Portal search bar, type: **"App registrations"**
2. Click **App registrations**
3. Click the **"View all applications in directory"** button
4. Find and click **stacksync-example**

<figure><img src="/files/FrSTm0z39xSXYeK437r9" alt=""><figcaption></figcaption></figure>

#### Step 4.2: Create "viewer" Role

1. In the left sidebar, click **App roles**
2. Click **+ Create app role**

Fill in:

* **Display name:** `viewer`
* **Allowed member types:** Users/Groups
* **Value:** `viewer`
* **Description:** `Viewer with read-only access`
* **Do you want to enable this app role?** ✅ Checked

3. Click **Apply**

<figure><img src="/files/sw2d4OrxLEAIDQCaqcDE" alt=""><figcaption></figcaption></figure>

#### Step 4.3: Create "editor" Role

1. Click **+ Create app role** again

Fill in:

* **Display name:** `editor`
* **Allowed member types:** Users/Groups
* **Value:** `editor`
* **Description:** `Editor with standard access`
* **Do you want to enable this app role?** ✅ Checked

2. Click **Apply**

***

### Part 5: Configure Attribute Mappings

#### Step 5.1: Access Attribute Mappings

1. Go back to **Enterprise applications** → **stacksync-example**
2. Click **Provisioning** in the left sidebar
3. Under **Attribute Mappings**, click **Provision Microsoft Entra ID Users**

<figure><img src="/files/39Pq7hDatKdPO3a17Mul" alt=""><figcaption></figcaption></figure>

#### Step 5.2: Add Roles Mapping

1. Scroll to the bottom and click **Add New Mapping**

Fill in:

* **Mapping type:** Expression
* **Expression:**

```
  SingleAppRoleAssignment([appRoleAssignments])
```

* **Target attribute:** `roles[primary eq "True"].value`
* **Default value if null:** `viewer`
* **Apply this mapping:** Always
* **Match objects using this attribute:** No

2. Click **OK**
3. Click **Save** at the top

<figure><img src="/files/o0TT8Uc3SummwkBpN1GS" alt=""><figcaption></figcaption></figure>

***

### Part 6: Start Provisioning

#### Step 6.1: Enable Provisioning

1. Go back to the main **Provisioning** page (Preview
2. Click **Start provisioning**

<figure><img src="/files/9iVJdOWUFCoFo0nNdM7H" alt=""><figcaption></figcaption></figure>

Azure will now start provisioning users. The initial sync takes **5-10 minutes**.

***

### Part 7: Assign Roles to Users

#### Step 7.1: Assign a Role to a User

1. Go to **Users and groups** in the left sidebar
2. Click **+ Add user/group**
3. Under **Users**, click **None Selected**
4. Select a user
5. Click **Select**
6. Under **Select a role**, click **None Selected**
7. Choose either **viewer** or **editor**
8. Click **Select**
9. Click **Assign**

<figure><img src="/files/4ipHyz6weT5gaghJZjU8" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/MP0nWdDRjTFFfYhEwPn3" alt=""><figcaption></figcaption></figure>

**Repeat this for each user, assigning them the appropriate role.**

***

### Part 8: Test the Setup

#### Step 8.1: Test Provisioning

1. Go to **Provisioning** → **Provision on demand** (if available)
2. Select a test user (you'l need to search for the user)
3. Click **Provision**
4. Verify the user is successfully created in your stacksync workspace

***

### Troubleshooting

#### Users Not Provisioning

**Check:**

* Provisioning Status is **On**
* Users are **assigned** to the stacksync application
* Users have a **role assigned** (viewer or editor)
* User has email property
* Wait 10-40 minutes for initial sync

**View logs:**

* Go to **Provisioning** → **View provisioning logs**

#### Wrong Role Assigned

**Check:**

* Role is assigned correctly in **Users and groups**
* Roles attribute mapping includes default value `viewer`
* App roles display names are lowercase: `viewer`, `editor` (not `Viewer`, `Editor`)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacksync.com/security-and-other-resources/identity-and-access-management/sso/azure-entra-id.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.