# SSO Handbook

## Microsoft Azure SSO (SAML) Setup Guide

### 1. Prerequisites

* The user must have a **Microsoft Azure account** for their company
* After logging in, go to the **“Enterprise Applications”** page

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FP3iv2oNcrbjgHRl5WysH%2Fimage.png?alt=media&#x26;token=3fa66511-8319-4796-b074-282e48443a86" alt=""><figcaption></figcaption></figure>

***

### 2. Create an Application

1. Click **“Create your own application”**
2. Give your application a name

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2F4N3d44XeoeZQ6A4yB7Rr%2Fimage.png?alt=media&#x26;token=c7678672-ef23-4119-b2af-d1d681d9bcec" alt=""><figcaption></figcaption></figure>

3. Choose **“Set up single sign-on”** and select **SAML** as the login method

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FVaFmaBbpns2B4nt9I294%2Fimage.png?alt=media&#x26;token=4dab0565-dca0-4a44-9698-3908f95ad09e" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FC3wdk1Ht7jb2tRIxkvDf%2Fimage.png?alt=media&#x26;token=b2ecbfcc-4ba4-4faa-ae77-5ef95d7910b0" alt=""><figcaption></figcaption></figure>

***

### 3. Permission Requirements

* Only **Team Owners** or **Super Team Admins** have access to the SSO configuration page

***

### 4. SSO Configuration Details

#### **1. Enable SSO**

* SSO is **disabled by default**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FQjrxO4q7FlhHpvdzEhLG%2Fimage.png?alt=media&#x26;token=04d23d77-fe4f-4498-927d-2264b648cfaf" alt=""><figcaption></figcaption></figure>

#### **2. Configuration Item Details**

**✅ Identity Provider (IdP)**

* Currently, **only Microsoft Entra** is supported

**✅ SSO Protocol**

* Currently, only **SAML** is supported

**✅Login Method Options**

There are **two options** for how users log in:

1. **Single Sign-On (SSO) & Username/Password (default)**

Users can log in using either SSO or their account credentials.

2. **SSO Only**

Users can only log in via Single Sign-On; password login will be disabled.

**✅Add Domain(s)**

* Enter **your company email suffixes** (e.g., <mark style="color:red;">**`yourcompany.com`**</mark>)
* **Multiple domains** can be added

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FiNnjhX0Xl7hVaNuASDm9%2Fimage.png?alt=media&#x26;token=f075b8a8-d9d0-4e60-9792-1ecd42ffa328" alt=""><figcaption></figcaption></figure>

**✅ Service Provider (SP) Configuration**

* **Recommended method:**

&#x20;     a. Download the XML file from the D5 Team Management backend

&#x20;     b. In the Azure portal, open the SSO configuration module and go to **“Set up Single Sign-On”**

&#x20;     c. Click **“Upload metadata file”** and import the downloaded XML file

*   **Manual method:**

    a. In Azure’s “Basic SAML Configuration” section, manually fill in the following:

&#x20;            \- Copy the **Identifier (Entity ID)** from the D5 backend and paste it into the corresponding field

&#x20;            \- Copy the **Assertion Consumer Service URL (ACS URL)** and paste it accordingly

&#x20;       b. Click “Save” to apply

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FrIigU3QRCCu9lECjlcQn%2Fimage.png?alt=media&#x26;token=81dd6c96-0b6a-4272-bd32-a1959d64a64e" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2Fq3LxaJZU7FhvX5OXk8mh%2Fimage.png?alt=media&#x26;token=6b2d0d26-57e6-4d5e-bfda-ecb244a4971e" alt=""><figcaption></figcaption></figure>

**✅ Identity Provider (IdP) Information**

1. In the Azure portal’s SSO module, go to the **“Set up Single Sign-On”** section
2. Under the **SAML Certificates** area, download the **“Federation Metadata XML”**
3. Upload this file to the D5 Team Management backend
4. The system will parse the content and automatically fill in the IdP login URL

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FmF9aApPD483ekUzeJsPW%2Fimage.png?alt=media&#x26;token=3582700d-6ebb-4b92-8c96-b4a88cca937c" alt=""><figcaption></figcaption></figure>

## Microsoft Azure SCIM Configuration Guide

### 1. Setup in D5 Myspace - Team Management Backend

Enable Provisioning

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FaRq9GbbBBhPMUk4AS7ow%2Fimage.png?alt=media&#x26;token=c5fe788a-69ae-4619-8a86-ac4a7d16c4bc" alt=""><figcaption></figcaption></figure>

***

### 2. Setup in Microsoft Azure

* Go to **Enterprise Applications > SSO Control Module > Provisioning**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FI8XHvFmf0eoiBEqh84Gz%2Fimage.png?alt=media&#x26;token=c19869ba-e804-4e2d-b9c4-24f8473b70d7" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FnLxXKS0pJSZPVGNyf7U9%2Fimage.png?alt=media&#x26;token=9aa689dc-1d66-4886-86d3-09de36fbbae4" alt=""><figcaption></figcaption></figure>

* Click **Add a new configuration**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FO1tfLhN63YhE4X8SzuTb%2Fimage.png?alt=media&#x26;token=1beb3209-80b2-426c-a6e7-f4601a29190a" alt=""><figcaption></figcaption></figure>

* Enter the **SCIM endpoint and access token** provided in the D5 Team Management Backend. Click **Test Connection**, and after the test is successful, click **Create**.

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FeR6B7UJ059Q0QoFB1d5n%2Fimage.png?alt=media&#x26;token=b7893f3c-498a-4fb2-ab3b-bfc10a89cce8" alt=""><figcaption></figcaption></figure>

* Click **Settings**, enable the provisioning switch, and click **Save**.

> 💡 If the access token changes in the future:
>
> * Navigate to **Provisioning > Settings > Admin Credentials**
> * Set the **Provisioning Status** to **On**
> * Click **Save**
> * Finally, **enable provisioning** to sync user accounts

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FAJvZoO3LG1COk1gw19vk%2Fimage.png?alt=media&#x26;token=b4e53585-8870-4dde-be73-c2063a3d8fab" alt=""><figcaption></figcaption></figure>

* Click **Mappings**, then select **Provision Microsoft Entra ID Users**.

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FvEDMoIMWEVqbT0jmFHeD%2Fimage.png?alt=media&#x26;token=8e2f9485-f267-4ef2-a175-1443843f1245" alt=""><figcaption></figcaption></figure>

* On the attribute mapping page, click **Add New Mapping.**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FSZ0nZZkIFsjNDlIqjX6t%2Fimage.png?alt=media&#x26;token=eaaeed11-3bb6-461b-ab1b-6313b59f10c9" alt=""><figcaption></figcaption></figure>

* Configure the new mapping with the following steps. After completing the configuration, click **Save:**

> - Set **Mapping type** to **Expression**
> - Enter the following **Expression:** <mark style="color:red;">`SingleAppRoleAssignment([appRoleAssignments])`</mark>
> - Set **Target attribute** to <mark style="color:red;">`roles[primary eq "True"].value`</mark>
> - Set **Match objects using this attribute** to **Yes**
> - Set **Matching precedence** to **2**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FFKVAk3WEhgxwAEyLaCG4%2Fimage.png?alt=media&#x26;token=d995d0b0-fdf6-4200-a5de-14a75f810990" alt=""><figcaption></figcaption></figure>

* Return to the attribute mapping page and click **Save.**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FF9tlmeHboP0PguTtsJ8y%2Fimage.png?alt=media&#x26;token=96216c0c-8512-4ff1-a48e-3b5aab3e48b9" alt=""><figcaption></figcaption></figure>

* Return to the **Overview (Preview)** page to confirm whether provisioning has started. If it hasn't, click **Start Provisioning.**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FS8JHDBhqOt6WUjVsTfLt%2Fimage.png?alt=media&#x26;token=1786991a-d9a2-4cbd-893b-c592e85f5e65" alt=""><figcaption></figcaption></figure>

***

### 3. Creating Application Roles

* Go to **Enterprise Applications > SSO Control Module > Properties**
* Click **“App Registrations”**
* After entering, go to the **“App Roles”** section
* You can **add new roles** here as needed

> ⚠️ If no roles are configured, synced users will default to **Team Member** role

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FSlhLZSTBXaR3c3imrm3a%2Fimage.png?alt=media&#x26;token=6cc3ca59-61ed-435b-b5b2-d55bff02c4e2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FjXVLVmJgPhebfb1Z97QW%2Fimage.png?alt=media&#x26;token=0b04ef38-4828-473b-aa9c-30493f078676" alt=""><figcaption></figcaption></figure>

***

### 4. Start provisioning

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FXe3DPYsmPC8otuwzSeAo%2Fimage.png?alt=media&#x26;token=baa7d3b9-536b-48de-aa10-43b7768101a6" alt=""><figcaption></figcaption></figure>

### 5. SCIM Sync Behavior

* When **SCIM is enabled,** the following features will be **disabled** in the D5 Team Management Backend:
  * Manually **editing team member roles**
  * **Modifying member account attributes**
  * **Inviting users to the team**
  * **Removing members from the team**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FVvazWYc1OpA8dIYZl3eD%2Fimage.png?alt=media&#x26;token=7ddcac59-6860-438e-95a9-832cd86040ea" alt=""><figcaption></figcaption></figure>

* In **Group Management**, the following options will also be hidden:
  * **Invite to Team**
  * **Remove from Team**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2F8PCl09RMVgllLFc0Jokx%2Fimage.png?alt=media&#x26;token=f4d78b95-8672-4d1a-9a1e-55e971216651" alt=""><figcaption></figcaption></figure>

* Sync Status and Frequency
  * **Sync Frequency:** Once every **40 minutes**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FcnYr6tT1kyiNaenNuzxP%2Fimage.png?alt=media&#x26;token=2cc84522-8d0f-4cda-8c60-1fbfb7482f6a" alt=""><figcaption></figcaption></figure>

* **View Sync Results:**
  * In the Azure backend, click on sync logs
  * You can see **each step of the sync** and any **failure reasons**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FJA32YpviiN4JOmUXQWCf%2Fimage.png?alt=media&#x26;token=5a6fb86a-af3b-4e67-8131-c49ca3f62aff" alt=""><figcaption></figcaption></figure>

Example Case

* A new user is added in the IdP (who has **never registered** in D5)
* After waiting for the sync cycle, the user will automatically appear in the team

| <div><figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FFnuuft3EXlRw4SNmCidQ%2Fimage.png?alt=media&#x26;token=94db4277-d84b-4506-9c76-c964d0f37c40" alt=""><figcaption></figcaption></figure></div> | <div><figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2Fg21RqS7zzaASaSP66xbY%2Fimage.png?alt=media&#x26;token=06ddcdb6-ef9c-491d-b667-b19212897bd6" alt=""><figcaption></figcaption></figure></div> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <div><figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FPYc8RZ4yg28AIrtUSHiQ%2Fimage.png?alt=media&#x26;token=51dd4488-00b9-4203-9412-eb598522c663" alt=""><figcaption></figcaption></figure></div> | <div><figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2FvjRfbR0nWrq1WPJJ2IAV%2Fimage.png?alt=media&#x26;token=c8cf96cc-377a-4b21-99cd-a7cb4dce4f09" alt=""><figcaption></figcaption></figure></div> |

***

### 6. Sync Failure Scenarios

* **Team Seat Limit Reached**

If an existing D5 account is being synced while the team's seat quota is full, the sync will fail, and the account will **not be added to the team.**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2Fh6IFNBUKnPOlVRv07fVr%2Fimage.png?alt=media&#x26;token=6c2c22f8-cd08-4a4d-806d-10f269c0fd6b" alt=""><figcaption></figcaption></figure>

* **Backend Deployment in Progress**

If the D5 backend is undergoing a release during the sync process,the sync will fail.

The account will **not be created nor added to the team.**&#x20;

It will be retried in the **next scheduled sync.**

<figure><img src="https://3611830798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MjbN1iGmN_HBnj_fyU9%2Fuploads%2Fqp7kKRqS6a6D48wps3BB%2Fimage.png?alt=media&#x26;token=9e63b296-7be2-4d0a-87b1-26a40b42761b" alt=""><figcaption></figcaption></figure>
