# Set up Microsoft Entra ID

## Overview

Configure single sign-on (SSO) for your <code class="expression">space.vars.product\_acronym</code> environment using Microsoft Entra ID. This integration allows you to authenticate <code class="expression">space.vars.product\_acronym</code> resources through your existing Microsoft accounts.

## Prerequisites

Before you begin, ensure you have:

* Administrative access to Microsoft Entra ID
* Administrative access to your <code class="expression">space.vars.product\_acronym</code> environment
* A Linux system with Python 3 installed
* Your <code class="expression">space.vars.product\_acronym</code> domain FQDN (fully qualified domain name)

#### Step 1: Create an Enterprise Application in Entra ID

Create a new enterprise application in Microsoft Entra ID to handle the SSO integration.

1. Sign in to the Microsoft Entra admin center.
2. Navigate to **Entra ID > Enterprise apps > All applications**.
3. Select **New application**.

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-6850f7d62310cb531d9bc151a3346ee5032abdfc%2Fkv5gcisr8qzgx41iue4wev1cekras536vwpohn23m7lm3p3aimb37l4j6zcdaf4s.png?alt=media" alt=""><figcaption></figcaption></figure>

4. On **Browse Microsoft Entra Gallery** select **Create your own application**.

You see options for cloud platforms, on-premises applications, and featured applications.

4. Enter a name that you want to use to recognize the instance of the application.
5. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-f94063216e1b05c75581e675614836f3f1260531%2F4upcid4e3boolgiedkv9183rlmhiclc9d0a9e7s5oz5rk2bm9tb5a0r7wofwajtu.png?alt=media" alt=""><figcaption></figcaption></figure>

6. Select **Create**.

#### Step 2: Enable SAML single sign-on

Enable SAML single sign-on for your enterprise application and configure the connection settings between Entra ID and your <code class="expression">space.vars.product\_name</code> environment, while assigning user account to the application.

1. Sign in to the **Microsoft Entra admin center** and then navigate to **Browse to Entra ID > Enterprise apps > All applications**.
2. Enter the name of the existing application in the search box, and then select the application from the search results.
3. Navigate to **Manage** and then select **Single sign-on**
4. Select **SAML** as the single sign-on method.

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-26bb061ea00ab4f734c3b8ed32640e9049461e82%2Fa8gl98kjz6ycv9cv9crzcd5afeaz1znbm4hlvur3p31vqm6yc3krbspz4fnkx3w0.png?alt=media" alt=""><figcaption></figcaption></figure>

5. On **Basic SAML Configuration,** select **Edit** and then configure the following required fields.

| Field                                           | Description                                             |
| ----------------------------------------------- | ------------------------------------------------------- |
| **Identifier (Entity ID)**                      | https\://\<DU\_FQDN>/keystone                           |
| **Reply URL (Assertion Consumer Service URL)**: | https\://\<DU\_FQDN>/sso/IDP1/Shibboleth.sso/SAML2/POST |

{% hint style="info" %}
**NOTE**

Replace `<DU_FQDN>` with your actual domain FQDN **without** the region name.

e.g. use `companyx` instead `companyx-regionone`
{% endhint %}

Optionally, you can choose to enter information to the optional fields.

5. Select **Save**.
6. On the **Attributes & Claims**, select **Add a group claim** and then configure the group settings according to your requirements.

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-f0e6f3b461e86d186753c1b0c584218e95d15185%2Fvrc0iwi8el4f6w6zmoiorco8rzjabsjscoxuxa6u645huetrdkked0v47q0n5g4a.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-1e67e4cd460b3578f4e254b758f84f2ec30f0aa4%2Fptsxhnvr56t2e226gn1qyxwhkh81qroicpvwma4bsmw1qs8zuqsxc0dpzyhjkt67.png?alt=media" alt=""><figcaption></figcaption></figure>

5. Copy and securely save the **App Federation Metadata URL** value. You will require this URL during the <code class="expression">space.vars.product\_acronym</code> environment configuration.

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-869fabbb93434775e5b6c23455e21d84f805ffb2%2F4bbr1mb6tc1e152wmzo3pl6qshgo5csmnppli38nrijd5nh38fmbhp1hqdvenzvt.jpeg?alt=media" alt=""><figcaption></figcaption></figure>

6. To assign users or groups to the application, perform the following steps.

* Navigate to **Entra ID > Enterprise apps > All applications**
* Select **Users and groups** and then select **Add user/group**

After assigning the user to the application, ensure that the application is set to be visible to the user. To make it visible to assigned users, select **Properties** and then set **Visible to users?** to **Yes**.

Your SAML single sign-on configuration is complete.

#### Step 3: Generate Attribute Mapping Files

Create the required attribute mapping files using the federation metadata from your Entra ID application.

1. On your Linux system with Python 3, download the federation metadata using the wget command:

{% tabs %}
{% tab title="Bash" %}

```bash
wget https://login.microsoftonline.com/YOUR_TENANT_ID/federationmetadata/2007-06/federationmetadata.xml?appid=YOUR_APP_ID
```

{% endtab %}
{% endtabs %}

Replace `YOUR_TENANT_ID` and `YOUR_APP_ID` with the actual values from your App Federation Metadata URL.

2. Download the [metadata parsing script](https://github.com/platform9/support-locker/blob/master/sso/adfs-metadata-parse.py)
3. Generate the attribute mapping file by running the following script against the federation metadata XML file.

{% tabs %}
{% tab title="Bash" %}

```bash
./adfs-metadata-parse.py federationmetadata.xml > attribute_map.xml
```

{% endtab %}
{% endtabs %}

3. Verify the generated file contains the correct attribute mappings.

Your attribute mapping file is ready.

#### Step 4: Configure <code class="expression">space.vars.product\_acronym</code> SSO Settings

Configure your <code class="expression">space.vars.product\_acronym</code> environment to use the Entra ID SSO integration.

1. Log in to your <code class="expression">space.vars.product\_acronym</code> administrative interface.
2. Navigate to **Settings** > **Enterprise SSO**.
3. On the **Enterprise SSO**, enable SSO and configure the following settings.

| Field                                 | Description                                                                       |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| **SSO Provider**                      | Selection from the available options                                              |
| **Entity ID**                         | Copy the Microsoft Entra Identifier from your Entra ID application configuration. |
| **SAML Metadata URL**                 | Enter the App Federation Metadata URL from your Entra ID application.             |
| **SSO Provider Attribute MAP in XML** | Copy and paste the contents of the `attribute_map.xml` file you generated         |

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-a5006f43e9ad9eb5eec5d0bf1312bec59eb31832%2F70siq9smrfk24wqnp4jot3m7kb5ng8r8zf8d3jkwt9elqfws0s1fx7muj7zdkfkd.png?alt=media" alt=""><figcaption></figcaption></figure>

4. Select **Save**.
5. Select **SAML Groups**.
6. Select **Add Group** to create a new SAML group.
7. Configure the SAML group settings.

| **Field**           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Group Settings**  | <p>When setting up SAML for your product, fill in the following required fields under Group Settings:<br><br>- <strong>Name</strong>: Enter a unique name for the group.<br>- <strong>Description</strong>: Provide a brief description of the group.<br>- <strong>SAML Attribute Key for First Name</strong>: Enter the attribute key for the user's first name, (for example, <code>givenname</code>).<br>- <strong>SAML Attribute Key for Last Name</strong>: Enter the attribute key for the user's last name (for example, <code>surname</code>).<br>- <strong>SAML Attribute Key for Email</strong>: Enter the attribute key for the user's email address (for example, <code>email</code>).<br><br>The attribute keys must match those configured in your identity provider’s <code>attribute\_map.xml</code> file.</p> |
| **Group Mapping**   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Tenants & Roles** | Assign users to appropriate tenants and roles (Administrator or Self-Service User)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

<figure><img src="https://1100565312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYcmHH6U169jTwihxwwy%2Fuploads%2Fgit-blob-0f6fc1d57a0d8eded87c5ac7e3513c0266268fc3%2Fkfdt7cgc6pk429m6vph8iwxx44m1by9uu440tdbzp8nl66x7ab12cgktdymfdls9.png?alt=media" alt=""><figcaption></figcaption></figure>

8. Select **Save**.

Your <code class="expression">space.vars.product\_acronym</code> SSO configuration is now complete.

#### Step 5: Test Your SSO Configuration

Verify that your SSO integration works correctly.

1. Log out of your current <code class="expression">space.vars.product\_acronym</code> session.
2. Open a new private or incognito browser window.
3. Navigate to your <code class="expression">space.vars.product\_acronym</code> login page.
4. Select **Sign In with SSO**.
5. Complete the authentication process using your Microsoft credentials.
6. Verify you can access <code class="expression">space.vars.product\_acronym</code> resources according to your assigned role.

You have now successfully configured SSO integration between <code class="expression">space.vars.product\_acronym</code> and Microsoft Entra ID. Users can now authenticate using their existing Microsoft accounts and access <code class="expression">space.vars.product\_acronym</code> resources based on their assigned roles and permissions.