Microsoft Azure Active Directory
================================

Backend classes
---------------

For Django, choose from these class paths for ``AUTHENTICATION_BACKENDS``.
For other integrations, use the same class paths in the
framework-specific backend setting.

.. list-table::
   :header-rows: 1

   * - Backend name
     - Class path
   * - ``azuread-oauth2``
     - ``social_core.backends.azuread.AzureADOAuth2``
   * - ``azuread-oauth2-v2``
     - ``social_core.backends.azuread.AzureADOAuth2V2``
   * - ``azuread-tenant-oauth2``
     - ``social_core.backends.azuread_tenant.AzureADTenantOAuth2``
   * - ``azuread-v2-tenant-oauth2``
     - ``social_core.backends.azuread_tenant.AzureADV2TenantOAuth2``
   * - ``azuread-b2c-oauth2``
     - ``social_core.backends.azuread_b2c.AzureADB2COAuth2``

User identifiers
----------------

The Azure backends use these claims as their default user identifiers:

.. list-table::
   :header-rows: 1

   * - Backend name
     - Default ID key
   * - ``azuread-oauth2``
     - ``upn``
   * - ``azuread-oauth2-v2``
     - ``upn``
   * - ``azuread-tenant-oauth2``
     - ``sub``
   * - ``azuread-v2-tenant-oauth2``
     - ``preferred_username``
   * - ``azuread-b2c-oauth2``
     - ``sub``

Microsoft documents ``preferred_username`` and ``upn`` as mutable
human-readable identifiers. The ``sub`` claim is immutable and unique to an
application ID, while ``oid`` is immutable and remains the same across
applications within a tenant. Choose the claim that matches the application's
identity model.

For example, configure the v2 tenant backend to use ``sub``::

    SOCIAL_AUTH_AZUREAD_V2_TENANT_OAUTH2_ID_KEY = 'sub'

Changing this setting for a deployed application changes the value stored in
``UserSocialAuth.uid``. Migrate existing associations before enabling the
new key. See :doc:`../configuration/settings` and the
`Microsoft ID token claims reference`_.

IdP Setup
---------

To configure Azure AD:

1. Log into the Azure Portal
2. Navigate to **Azure Active Directory** > **App registrations** > **New registration**
3. Configure:

   * **Name**: Your application name
   * **Redirect URI**: Select **Web** and enter ``https://your-domain.com/complete/azuread-oauth2/``

4. After registration, note the **Application (client) ID** and **Directory (tenant) ID**
5. Create a client secret:

   * Go to **Certificates & secrets** > **New client secret**
   * Copy the secret value immediately (you won't be able to see it again)

6. Configure API Permissions:

   * Go to **API permissions** > **Add a permission** > **Microsoft Graph**
   * Add delegated permissions: ``User.Read``, ``email``, ``openid``, ``profile``
   * Click **Grant admin consent** if required

Application Configuration
-------------------------

Fill in ``Client ID`` and ``Client Secret`` settings with values from Azure AD::

    SOCIAL_AUTH_AZUREAD_OAUTH2_KEY = ''
    SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET = ''

- Also it's possible to define extra permissions with::

      SOCIAL_AUTH_AZUREAD_OAUTH2_RESOURCE = ''

  This is the resource you would like to access after authentication succeeds.
  Some of the possible values are: ``https://graph.windows.net`` or
  ``https://<your Sharepoint site name>-my.sharepoint.com``.

  When using Microsoft Graph, the resource needed is::

      SOCIAL_AUTH_AZUREAD_OAUTH2_RESOURCE = 'https://graph.microsoft.com/'

- Add the backend to the authentication backends setting::

      AUTHENTICATION_BACKENDS = (
          ...
          'social_core.backends.azuread.AzureADOAuth2',
          ...
      )

- If you are using an authority host other than the default ``AZURE_PUBLIC_CLOUD`` (``'login.microsoftonline.com'``)
  then you can override the default with the  ``AUTHORITY_HOST`` setting. A list of Azure authority hosts can be found
  in the `Azure Authority Hosts`_ doc::

      SOCIAL_AUTH_AZUREAD_OAUTH2_AUTHORITY_HOST = ''

- Federated identity credentials (client assertions) are supported when you do not want to use a client secret. After
  adding a federated credential to your Entra ID app, point the backend at the OIDC token that your workload issues
  (for example, Kubernetes service account tokens issued via Azure Workload Identity, or other OIDC tokens where you manage
  writing the token to a file). Precedence: if ``SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET`` is set, the backend uses the client
  secret and does not send a client assertion; otherwise it prefers an explicit ``SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION``;
  if no assertion is provided, it reads a token file from ``AZURE_FEDERATED_TOKEN_FILE`` (or ``OAUTH2_FIC_TOKEN_FILE``) or
  ``SOCIAL_AUTH_AZUREAD_OAUTH2_FEDERATED_TOKEN_FILE``. The backend will automatically use a client assertion instead of
  ``CLIENT_SECRET`` when the secret is omitted.

  Default path used by Azure Workload Identity on Kubernetes::

      AZURE_FEDERATED_TOKEN_FILE=/var/run/secrets/azure/tokens/azure-identity-token

  Or configure explicitly via the backend setting::

      SOCIAL_AUTH_AZUREAD_OAUTH2_FEDERATED_TOKEN_FILE = '/path/to/oidc/token'

  You can also provide a pre-built client assertion JWT (preferred when you already create the assertion yourself)::

      SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
      # Optional: defaults to the standard JWT bearer URN shown here
      SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

  Minimal configs by approach:

  - Token file (workload-issued OIDC token): leave ``SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET`` unset; set either
    ``AZURE_FEDERATED_TOKEN_FILE`` (or ``OAUTH2_FIC_TOKEN_FILE``) or ``SOCIAL_AUTH_AZUREAD_OAUTH2_FEDERATED_TOKEN_FILE``
    to the token path. ``CLIENT_ASSERTION_TYPE`` is not needed for this mode.

  - Pre-built client assertion: leave ``SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET`` unset; set
    ``SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION`` (and optionally ``SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE``
    if you use a non-standard type). ``FEDERATED_TOKEN_FILE`` is not read in this mode because the explicit assertion wins.

  Kubernetes projected service account token volume example::

      apiVersion: v1
      kind: Pod
      metadata:
        name: mypod
      spec:
        serviceAccountName: myserviceaccount
        containers:
        - name: mycontainer
          image: myimage
          env:
          - name: AZURE_FEDERATED_TOKEN_FILE
            value: /var/run/secrets/azure/tokens/azure-identity-token
          volumeMounts:
          - name: azure-identity-token
            mountPath: /var/run/secrets/azure/tokens
            readOnly: true
        volumes:
        - name: azure-identity-token
          projected:
            sources:
            - serviceAccountToken:
              path: azure-identity-token
              audience: api://AzureADTokenExchange
              expirationSeconds: 3600

  These settings apply to Azure AD/Entra ID scenarios. For more information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_.

Tenant Support
--------------

If the app is linked to a specific tenant (vs the common tenant) it's
possible to use a version of the backend with tenant support.

*Note: The backends are split because of the needed cryptography dependencies which must be installed manually.*

IdP Setup for Tenant
^^^^^^^^^^^^^^^^^^^^^

Follow the same IdP setup steps from the 'IdP Setup' section above, but use redirect URI::

    https://your-domain.com/complete/azuread-tenant-oauth2/

Application Configuration for Tenant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Fill in ``Client ID``, ``Client Secret``, and ``Tenant ID`` settings::

    SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY = ''
    SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET = ''
    SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID = ''

- Also it's possible to define extra permissions with::

      SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_RESOURCE = ''

  This is the resource you would like to access after authentication succeeds.
  Some of the possible values are: ``https://graph.windows.net`` or
  ``https://<your Sharepoint site name>-my.sharepoint.com``.

  When using Microsoft Graph, the resource needed is::

      SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_RESOURCE = 'https://graph.microsoft.com/'

- Add the backend to the authentication backends setting::

      AUTHENTICATION_BACKENDS = (
          ...
          'social_core.backends.azuread_tenant.AzureADTenantOAuth2',
          ...
      )

- If you are using an authority host other than the default ``AZURE_PUBLIC_CLOUD`` ('login.microsoftonline.com')
  then you can override the default with the  ``AUTHORITY_HOST`` setting. The Azure authority hosts are listed
  in the `Azure Authority Hosts`_ doc::

      SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_AUTHORITY_HOST = ''

B2C Tenant
----------
If the app needs custom business logic for authentication then use the Azure AD B2C tenant.

To enable OAuth2 B2C Tenant support:

- Fill in ``Client ID`` and ``Client Secret`` settings. These values can be
  obtained easily as described in `Azure AD Application Registration`_ doc::

      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_KEY = ''
      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_SECRET = ''

- Fill in the tenant id::

      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_TENANT_NAME = ''

- Fill in the B2C policy::

      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_POLICY = ''

The policy should start with `b2c_`. For more information see `Azure AD B2C User flows and custom policies overview`_ doc.

- Also it's possible to define extra permissions with::

      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_RESOURCE = ''

  This is the resource you would like to access after authentication succeeds.
  Some of the possible values are: ``https://graph.windows.net`` or
  ``https://<your Sharepoint site name>-my.sharepoint.com``.

  When using Microsoft Graph, the resource needed is::

      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_RESOURCE = 'https://graph.microsoft.com/'

- Add the backend to the authentication backends setting::

      AUTHENTICATION_BACKENDS = (
          ...
          'social_core.backends.azuread_b2c.AzureADB2COAuth2',
          ...
      )

- If you are using an authority host other than the default ``AZURE_PUBLIC_CLOUD`` ('b2clogin.com')
  then you can override the default with the  ``AUTHORITY_HOST`` setting.

      SOCIAL_AUTH_AZUREAD_B2C_OAUTH2_AUTHORITY_HOST = ''

.. _Azure AD Application Registration: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
.. _Azure AD B2C User flows and custom policies overview: https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview
.. _Azure Authority Hosts: https://docs.microsoft.com/en-us/python/api/azure-identity/azure.identity.azureauthorityhosts?view=azure-python
.. _Workload Identity Federation: https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation
.. _Federated identity credentials (Workload Identity): https://azure.github.io/azure-workload-identity/docs/topics/federated-identity-credential.html
.. _Microsoft ID token claims reference: https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference