***
title: Microsoft Entra Installation Guide (OIDC)
excerpt: ''
deprecated: false
hidden: false
metadata:
title: ''
description: ''
robots: index
next:
description: ''
---------------
# Prerequisites
Before you edit your SSO configuration, make sure you are logged into MyMoveworks. Otherwise, you will not be able to log in and update your SSO configuration details.
**Microsoft Entra Prerequisites**
* Ensure you have **Access to the Azure Admin Portal** with the appropriate IAM permissions in Azure to **register a new Enterprise Application**.
**Moveworks SSO Prerequisites**
* Your Moveworks Environment should be initialized in order to continue. (Verify with your Account Team if this has been completed)
* Note the following values.
* `data_center_domain` - the data center where your organization is hosted (see table below).
| Data Center | data\_center\_domain |
| :----------------------- | :---------------------------- |
| United States (default) | moveworks.com |
| Canada | am-ca-central.moveworks.com |
| EU | am-eu-central.moveworks.com |
| Australia / Asia Pacific | am-ap-southeast.moveworks.com |
| Government Secure Cloud | moveworksgov.com |
* `subdomain` - your organization's login subdomain. This should match your `customer_id`, which can be [verified from the General Information Page](/service-management/administration/organization-information).
Make sure to use the unique subdomain. For example, if you're organization's login subdomain is **acme.moveworks.com**, then your `subdomain` is **acme** and your `data_center_domain` is **moveworks.com** which is part of the US Data center.
* `customer_id` - The unique identifier for your organization . This is stored as **Org Name** under **Organization Details > General Information**
In exceptional cases where you would like Moveworks to support your organisation with a different subdomain value. Please reach out to Moveworks Support.
# Configuration Steps
## Create OIDC Application
***We recommend setting up a new/separate app registration for this step instead of reusing the App-reg created for the Teams bot setup***
1. Go to [https://portal.azure.com/](https://portal.azure.com/)
2. Find the **App Registrations** service
3. Select **New Registration**
4. Register the Application
* **Name**: `Moveworks`
* **Supported account types**: `Accounts in this organizational directory only`
5. Select **Register**
## Configure Moveworks Settings
1. Go to **Manage > Branding & properties** and update the following:
* **Upload new logo**:
* **Home Page URL**: `https://{{subdomain}}.{{data_center_domain}}`
2. Go to **Manage > Authentication**, Select **Add a Platform** and choose **Web**
3. Add your **Redirect URI** as `https://{{subdomain}}.{{data_center_domain}}/login/sso/oidc`
## Add User Permission
1. Go to **Manage > API permissions**. Select **Add a permission** and choose **Microsoft Graph**
2. Choose **Application permissions**
3. Toggle on the **User.Read.All** permission
4. Click **Add permissions** and ensure that the permission is Admin consented.
## Enable User Access
1. Go to **Enterprise Applications**
2. Find the application you created
3. Go to **Security > Permissions** and click **Grant admin consent for \{\{your company}}.**
## Generate Client Secret
1. Navigate back to the **App Registration** page. The following settings are not available on the Enterprise Application page
2. Go to **Certificates & secrets**.
3. Click **New client secret**.
4. Add *Description* and *Expires*. We recommend selecting 24 months as the expiration policy.
5. Write down the **Value** as your `idp_secret`
6. Go to the **Overview** tab and note down your **Application (client) ID**. This is your `idp_client_id`
7. Click **Endpoints > OpenID Connect metadata document** and paste it in your browser
8. 
Copy the `issuer` from the resulting JSON. This is your `idp_issuer`
## Add SSO Configuration in MyMoveworks
9. Navigate to SSO Settings in MyMoveworks
10. If you already see a `studio` config, edit it. Otherwise, choose **Create**.
11. Add your configuration using the values you've noted above
* **Moveworks Product**: `studio`
* **Select Connector**: `ms_graph`
* **Authentication Protocol**: `OIDC`
* **IDP Redirect URL**: `https://{{subdomain}}.{{data_center_domain}}/login/sso/oidc`
* e.g. [https://acme.am-eu-central.moveworks.com/login/sso/oidc](https://acme.am-eu-central.moveworks.com/login/sso/oidc)
* **IDP Issuer**: `idp_issuer`(from Step 7)
* e.g. [https://login.microsoftonline.com/9ed5798c-9bbe-471c-8005-7658c9846400/v2.0](https://login.microsoftonline.com/9ed5798c-9bbe-471c-8005-7658c9846400/v2.0)
* **IDP Client Id**: `idp_client_id` (from Step 5)
* **IDP Client Secret**: `idp_client_secret` (from Step 4)
12. Click **Submit**.
13. Wait a few minutes, then attempt to log into your instance at `https://{{subdomain}}.{{data_center_domain}}`
# FAQ
## Does Moveworks support reading user data such as 'upn' from a custom scope / additional claim?
1. No - Moveworks will only request the openid, email, and profile scopes during the authentication process. By default, Moveworks will use the 'Mail' field from Entra to determine the logging in user. By default the email address from the user's 'Mail' field in Entra **must** match their **email\_addr** field in their Moveworks User Record for the login to My Moveworks or Web Bot to be successfull.
1. If the Entra **mail** value does not match the **email\_addr** value in the Moveworks user record, follow these steps to map **mail** to the Moveworks **idm\_user\_id** field and change the SSO configuration in Moveworks to perform the user lookup on the **idm\_user\_id** field.
1. **Map the Entra mail field to idm\_user\_id:**
1. In Moveworks Setup navigate to **user identity > import users** and edit the existing configuration.
2. Click next once to get to the **Configure selected sources** screen and toggle into advanced mode in the top right.
3. Scroll to the **Source-Specific User Attribute Mapping** under the **ms\_graph** Integration Id. You should see a section like the below which defines the mapping on **user\_id\_info.user\_idm\_id\_info**
4. ```
"user_id_info.user_idm_id_info": [
{
"integration_id": "\"ms_graph\"",
"system": "\"MS_GRAPH\"",
"idm_user_id": "userPrincipalName",
"external_id": "id"
}
],
```
5. Update the mapping for **idm\_user\_id** to **mail**
```
"user_id_info.user_idm_id_info": [
{
"integration_id": "\"ms_graph\"",
"system": "\"MS_GRAPH\"",
"idm_user_id": "mail",
"external_id": "id"
```
* The change will reflect in users' records following the next user import flow. After 24 hours, confirm the change has succeeded in Moveworks Setup by navigating to**user identity > imported users**. Enter a users name in **Find Users** to view their record. Click **view profile** and scroll down to the **System Integration Attributes**. Under Azure AD confirm the **Idm User Id** value has been updated to match the **mail** value in Entra.
2. **Update the SSO configuration to user idm\_user\_id as the user lookup field:**
1. In Moveworks Setup, navigate to **Tenant Settings > Single Sign-on (SSO)** and edit the existing SSO configuration.
2. Under **Identifier Type** select **IDM\_USER\_ID**
## How do I assign users to an Entra Application?
1. Go to **Enterprise Applications** in Azure
2. Find the application you just registered.
3. From there, click **Manage > Properties** as shown below.
4. From the Properties page, toggle the **Assignment required** field to **Yes**, and **Visible to users** field to **Yes** as shown below.
5. Navigate to the Users and groups section and assign the app to all users that need access to it either directly or via a group.
6. When your users navigate to the [MyApps Portal](https://myapps.microsoft.com/) after a few minutes, they should be able to see the app and login directly from there.
