Sign in with Active Directory

​

Pre-requisites

First, you’ll need to enable user authentication within Mage. You can find out more about this in the Overview page.

​

Enable Microsoft sign in

There are two ways to enable Microsoft sign in. You can either register an application in your organization’s own Microsoft Entra ID, or use the default Mage application. We recommend registering your own application unless there is a specific reason you cannot do so.

Register and use your own Mage application

You will need to register an application in your organization’s Microsoft Entra ID.

1

Log into your Azure Portal

2

Click into the Microsoft Entra ID service

3

Navigate to the tenant you want users to sign into

4

Click App registrations on the left sidebar

5

Register a new application for Mage

Click the “New registration” button at the top of the page, and fill in the details for your application.

Make sure you add the following web redirect URI: http(s)://<your-mage-url>/oauth.

6

Create client secret for the application

Click into the application you created, and click “Certificates & secrets” in the left sidebar.

Copy the “Application (client) ID” and the “Directory (tenant) ID” values.

Create a new client secret and copy the value.

7

Set environment variable for Mage

Once you have registered your application, you will need to set the following environment variables in your Mage setup.

Name	Value
ACTIVE_DIRECTORY_DIRECTORY_ID	<tenant_id>
ACTIVE_DIRECTORY_CLIENT_ID	<application_client_id>
ACTIVE_DIRECTORY_CLIENT_SECRET	<application_client_secret>

You should now see the “Sign in with Microsoft” button when you start Mage and attempt to sign in. You may need to restart your Mage server for the changes to take effect.

Use the default Mage application

You will need to get your organization’s Tenant ID. You can find this in the Azure Portal:

1

Log into your Azure Portal

2

Click into the Microsoft Entra ID service

3

Navigate to the directory you want users to sign into

4

Click 'Properties' in the left sidebar

5

Copy the value under Tenant ID

6

Set environment variable for Mage

Once you have found your tenant ID, you will need to set the following environment variable in your Mage setup.

Name	ACTIVE_DIRECTORY_DIRECTORY_ID
Value	<tenant_id>

You should now see the “Sign in with Microsoft” button when you start Mage and attempt to sign in. You may need to restart your Mage server for the changes to take effect.

​

Map AD role to Mage role

You can map Active Directory roles to Mage roles by setting the ACTIVE_DIRECTORY_ROLES_MAPPING environment variable. The value should be a JSON object with the AD role as the key and the name of the Mage role as the value. For example:

export ACTIVE_DIRECTORY_ROLES_MAPPING='{"Mage.Edit": "Editor", "Mage.Admin": "Admin"}'

You can find the AD role value in the App roles section of your application in the Azure Portal.

When a user signs in for the first time with their Microsoft account, Mage will use this mapping to automatically add the appropriate roles to the user.