Authentication
Sign in with Microsoft Entra ID aka Active Directory
Enable signing in with a Microsoft account in Mage.
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
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.
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.
| Name | Value |
|---|---|
ACTIVE_DIRECTORY_DIRECTORY_ID | <tenant_id> |
ACTIVE_DIRECTORY_CLIENT_ID | <application_client_id> |
ACTIVE_DIRECTORY_CLIENT_SECRET | <application_client_secret> |
Use the default Mage application
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.
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.
| Name | ACTIVE_DIRECTORY_DIRECTORY_ID |
| Value | <tenant_id> |
Configurable environment variables
To configure the environment for Microsoft Azure Cloud and Microsoft Azure Gov Cloud sign-in, you need to set the following environment variables:- You can set the
AZURE_HOSTenvironment variable to one of the following based on your environment:
- You can set the
MICROSOFT_GRAPH_API_HOSTenvironment variable to one of the following basd on your environment:
Map AD role to Mage role
You will need to have created your own application and have app roles in order for this mapping to work.
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.
