# 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://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%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://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%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://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%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.

For example, 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://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%2Fuploads%2Fgit-blob-f0e6f3b461e86d186753c1b0c584218e95d15185%2Fvrc0iwi8el4f6w6zmoiorco8rzjabsjscoxuxa6u645huetrdkked0v47q0n5g4a.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%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://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%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://2024299496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiSZnkU6CpFC5IRPBBGAZ%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** by filling in the following required fields:

| **Field**                           | **Description**                                                                                                                                                                                                       |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                                | Enter a unique name for the group                                                                                                                                                                                     |
| Description                         | Provide a brief description of the group                                                                                                                                                                              |
| Username Attribute Mapping Template | Enter a template that defines how the username should be constructed using SAML attributes. Use the format `{attributeKey}` where attributeKey corresponds to the attributes available in your identity provider      |
| Email Attribute Mapping Template    | Enter a template that defines how the email address should be constructed using SAML attributes. Use the format `{attributeKey}` where attributeKey corresponds to the attributes available in your identity provider |

Template Examples:

* `{firstName} {lastName}` - Combines first and last name with a space
* `{firstName}-{lastName}` - Combines first and last name with a dash
* `{firstName}xxxx{lastName}` - Combines first and last name with custom characters
* `{email}` - Uses the email attribute directly

The attribute keys must match those configured in your identity provider's attribute\_map.xml file.

8. On Group Settings continue with additional configuration as follows:

| **Field**       | **Description**                                                                    |
| --------------- | ---------------------------------------------------------------------------------- |
| Group Mapping   | Configure tenant and role assignments                                              |
| Tenants & Roles | Assign users to appropriate tenants and roles (Administrator or Self-Service User) |

8. Select **Add Group**.

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.