Adding Microsoft Credentials¶
To make the SSO work, we need to set up, in your Django project, you need the credentials from your Microsoft Entra Registered Application.
Microsoft is a huge company that works for even larger ones. This means that the Microsoft Entra Platform is very complex and can be a bit confusing for newcomers. The following sections provide a brief overview of the Microsoft Entra Platform and the key concepts that are relevant to the authentication process. You do not need to understand all the details, but it is important to have a general idea of how the different components fit, especially when you need to configure and troubleshoot your application.
Understand Microsoft Tenants¶
Microsoft Entra, formerly known as Azure Active Directory (Azure AD), organizes user access and resources through a unique entity known as a Tenant. A tenant represents a dedicated instance of Microsoft Entra ID, essentially serving as a directory of users and groups that is owned and managed by an organization. Each tenant is distinct and separate from other tenants, ensuring data privacy and security across the Microsoft Cloud environment.
What the Tenant means to your Organization?
The tenant can be your entire company, a business unit or even a single department. It is a security boundary that defines the scope of administrative authority for an organization.
The most important thing to understand here is while you can restrict or permit data to be shared between entities inside a tenant, you are not allowed to share data between them.
Understand the Registered Enterprise Application¶
To your projects can interact with your Tenants, you will need to register an Enterprise Application:
Registered Application¶
Registering an application in Microsoft Entra informs the platform about the application's existence and defines the interaction parameters between the platform and the projects which will access it through the application. The registration encompasses details like the application's name, type (e.g., web, public, native), redirect URIs, client identifiers, client secrets, and other settings controlling the interaction with the identity service.
Enterprise Application¶
Once registered, the application can be utilized across one or more Microsoft Entra tenants. A registered application is referred to an "Enterprise Application" for the purpose of the configurations the application needs regard a tenant, covering aspects like who can use the application, the permissions it holds, monitoring, auditing, and more.
Single or Multi-tenant Applications¶
The distinction between single-tenant and multi-tenant configurations is important for understanding how applications interact with user identities and resources within the Microsoft Entra ecosystem. In a single-tenant configuration, the application is registered within a specific tenant, ensuring that only users from that particular tenant can authenticate. On the other hand, a multi-tenant configuration allows an application to be available to users across multiple tenants. This setup facilitates broader access and interoperability, catering to scenarios where an application needs to be accessible to users from different organizational domains.
What the Registered Enterprise Application means to your Organization?
This can be a single application to handle all users, from all tenants to all projects you want to authenticate. Or can be a complex multiple applications for multi-tenant and multiple projects/environments. The final organization depends on your company compliance needs.
The most important thing here is while you can start with just One-App-to-Rule-All, you will eventually finish with a configuration which embraces your company needs. Do not underestimate this task.
To learn more:
Creating your first Microsoft Entra Registered Application¶
To create your first Microsoft Entra Registered Application, you need to access the Microsoft Entra Administration Center and navigate to Applications -> App registrations.
For the purpose of this tutorial, we suggest creating a new registered application, clicking on the New registration button.
Do I use an existing application or create a new one?
The decision to use an existing Application or create a new one depends on your needs: you can create an application for each project you have, for each group of users, or for each environment (development, staging, production, etc...).
The safest route is to create a new single-tenant application for each project for each environment. This helps to mitigate the risk of exposing all your data in case of a security breach and the risk of service interruption due to misconfiguration. But in the other hand, this can be a bit cumbersome and fairly complex to manage.
In the end, any solution must be compatible with how your organization works.
Navigate to the App registrations page and click on the New registration button.
Add a new name for the app, and select the Supported account types to Accounts in this organizational directory only.
Go back to the Overview tab and retrieve the Application (client) ID. This will be the MICROSOFT_SSO_APPLICATION_ID in your Django project.
Now, navigate to the Certificates & secrets tab and click on the New client secret button. Add a description for the secret and select the expiration date. Click on the Add button.
In the next page, copy the Value of the secret. This will be the MICROSOFT_SSO_CLIENT_SECRET in your Django project.
Navigate to Enterprise applications, select your application and go to the Users and Groups tab and add a test user to your application.
Configuring your Django Project¶
After that, add the credentials in your settings.py file:
# settings.py
MICROSOFT_SSO_APPLICATION_ID = "your Application (client) Id here"
MICROSOFT_SSO_CLIENT_SECRET = "your client secret value here"
Don't commit this info in your repository. This permits you to have different credentials for each environment and mitigates security breaches. That's why we recommend you to use environment variables to store this info. To read this data, we recommend you to install and use a Twelve-factor compatible library in your project.
For example, you can use our project Stela to load the environment
variables from a .env.local file, like this:
# .env.local
MICROSOFT_SSO_APPLICATION_ID = "your Application (client) Id here"
MICROSOFT_SSO_CLIENT_SECRET = "your client secret value here"
# Django settings.py
from stela import env
MICROSOFT_SSO_APPLICATION_ID = env.MICROSOFT_SSO_APPLICATION_ID
MICROSOFT_SSO_CLIENT_SECRET = env.MICROSOFT_SSO_CLIENT_SECRET
But in fact, you can use any library you want, like django-environ, django-constance, python-dotenv, etc...
Customizing Token Authority¶
By default, Django Microsoft SSO uses the default Token Authority from the microsoft-authentication-library-for-python library (msal).
Currently, the default Token Authority is https://login.microsoftonline.com/common.
If you need to define another authority, please set the MICROSOFT_SSO_AUTHORITY option with your full tenant URL or AuthorityBuilder instance.
Using a custom authority URL¶
Please inform the full URL of your tenant, like https://login.microsoftonline.com/your_tenant.
Using a custom authority with AuthorityBuilder¶
Use the AuthorityBuilder class to create a custom authority. This class is available in the msal library.
# settings.py
from msal.authority import (
AuthorityBuilder,
AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC
)
MICROSOFT_SSO_AUTHORITY = AuthorityBuilder(AZURE_PUBLIC, "your-tenant.onmicrosoft.com")
To learn more:
In the next step, we need to configure the authorized callback URI for your Django project.