# Microsoft Entra ID

## Prerequisites

Ensure you have access to the following:

* An active Open Loyalty instance.
* Administrator access to your Microsoft Entra ID tenant.
* Basic understanding of OIDC and SSO concepts.

## Step-by-Step Configuration

### Verify Settings in Open Loyalty

{% stepper %}
{% step %}

#### Verify Admin Email Addresses

Ensure that the email address you want to use for SSO login does not already exist in the Open Loyalty portal.

{% hint style="danger" %}
If an email address for the admin already exists in Open Loyalty, the SSO login will not function for that account. To enable SSO for a user, ensure there are no conflicts. 

For instance, you could deactivate admin users logging in with email and password, update their email addresses by adding a suffix (e.g., "-old"), and then ask the admin users to log in via SSO.
{% endhint %}
{% endstep %}

{% step %}

#### Configure the Default Role

1. Log in to the Open Loyalty admin panel.
2. Go to **Settings** > **Roles**.
3. Choose the role you want to set as a default role. Click on **Edit**.
4. Set a **Default Role** for new users logging in through SSO. This role will be assigned to newly created users and can be changed later if needed.

<figure><img src="https://123136216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgIv2CyIIYf7vRfuhMKQ6%2Fuploads%2F457yU5IYhDwkgODc1cS9%2Fimage.png?alt=media&#x26;token=35567864-74ce-4aeb-bf72-fd31129332bd" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### Configure Microsoft Azure ID

{% stepper %}
{% step %}

#### **Sign in to the Azure Portal**

Navigate to `https://portal.azure.com` and sign in with an administrator account.
{% endstep %}

{% step %}

#### **Register the Application**

* In the Azure portal, go to **Microsoft Entra ID** > **App registrations**.
* Click **+ New registration**.
* Fill out the form:
  * **Name**: e.g. Open Loyalty
  * **Supported account types**: Select **Accounts in this organizational directory only (Single tenant)** (unless multi-tenant access is required).
  * (Optional) set up **Redirect URI**
    * Under **Select a platform**, Select **Single-page application (SPA)**
    * Under **URI**, enter your Open Loyalty's platform URL
* Click **Register**.​

{% hint style="warning" %}
Ensure that the redirect URIs match exactly, including the scheme (`http` or `https`) and are case-sensitive.
{% endhint %}
{% endstep %}
{% endstepper %}

### Share Details with Open Loyalty

{% stepper %}
{% step %}

#### Share SSO Details with Open Loyalty

* Provide the Open Loyalty team with the following details:
  * **Application (client) ID**
  * **Directory (tenant) ID**
* The Open Loyalty team will enable SSO using the provided details.
  {% endstep %}

{% step %}

#### Test the Integration

1. Use the **Continue with SSO** button on the login page.
2. Authenticate with SSO using a user account.
3. Verify that the user is successfully logged in and has been assigned the default role.

<figure><img src="https://123136216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgIv2CyIIYf7vRfuhMKQ6%2Fuploads%2FOEZw6RPSBvPPxLhq04xE%2Fimage.png?alt=media&#x26;token=b889a6c8-3f43-45a4-8ff7-f395f351870d" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Notes

* Ensure that the **Default Role** is configured appropriately to avoid granting unintended permissions to new users.
* If an email address already exists in Open Loyalty, the SSO login will not work for that account. Ensure there are no conflicts before enabling SSO for a user.
* **Authorization Flow**: It's recommended to use MSAL.js 2.0 or later, which supports the authorization code flow with PKCE, enhancing security for single-page applications.
* **Redirect URI Restrictions**: Redirect URIs must begin with the scheme `https`. They are case-sensitive and must match the case of the URL path of your running application.

## Troubleshooting

* If login fails, double-check the URL and Client ID configuration.
* Ensure the callback URL is correctly set in Microsoft Azure ID.
* Verify that the Microsoft Azure ID application has been configured to allow the Open Loyalty URL.