Skip to content

Conversation

@mehighlow
Copy link

Azure AD/Entra ID federated identity credentials documentation

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This pull request adds comprehensive documentation for Azure AD/Entra ID federated identity credentials support. The documentation explains how to configure workload identity authentication using client assertions as an alternative to client secrets.

Changes:

  • Added documentation for federated identity credentials (client assertions) configuration
  • Included examples for environment variables, Django settings, and pre-built JWT assertions
  • Provided a complete Kubernetes service account token volume configuration example
  • Added three reference links to Microsoft and Azure documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +39 to +79
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, GitHub Actions OIDC tokens, or Azure Workload Identity). The backend
will automatically use a client assertion instead of ``CLIENT_SECRET`` when the secret is omitted::

# Default path exported by Azure Workload Identity and GitHub Actions
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::

SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Kubernetes projected service account token volume example::

apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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 all Azure AD/Entra ID variants in this doc (common, tenant-specific, v2, and B2C). For more
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_ docs.
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The continuation text of this bullet point should be indented with 2 spaces to align with the start of the text after the bullet marker, not 6 spaces. This is consistent with the pattern used in other bullet points in this file (see lines 6-7, 16-18, 32-34).

Suggested change
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, GitHub Actions OIDC tokens, or Azure Workload Identity). The backend
will automatically use a client assertion instead of ``CLIENT_SECRET`` when the secret is omitted::
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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 all Azure AD/Entra ID variants in this doc (common, tenant-specific, v2, and B2C). For more
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_ docs.
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, GitHub Actions OIDC tokens, or Azure Workload Identity). The backend
will automatically use a client assertion instead of ``CLIENT_SECRET`` when the secret is omitted::
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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 all Azure AD/Entra ID variants in this doc (common, tenant-specific, v2, and B2C). For more
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_ docs.

Copilot uses AI. Check for mistakes.
Comment on lines +43 to +76
# Default path exported by Azure Workload Identity and GitHub Actions
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::

SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Kubernetes projected service account token volume example::

apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block indentation is incorrect. Code blocks within bullet points should be indented with 6 spaces from the left margin, not 12 spaces. This is consistent with the pattern used throughout this file (see lines 9-10, 14, 22, 26-30, 36). Additionally, line 44 uses shell environment variable syntax (AZURE_FEDERATED_TOKEN_FILE=/path) which is inconsistent with the Python configuration style used elsewhere in the documentation. It should follow the same format as other settings with quotes around the value.

Suggested change
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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

Copilot uses AI. Check for mistakes.
Comment on lines +43 to +76
# Default path exported by Azure Workload Identity and GitHub Actions
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::

SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Kubernetes projected service account token volume example::

apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block indentation is incorrect. Code blocks within bullet points should be indented with 6 spaces from the left margin, not 12 spaces. This is consistent with the pattern used throughout this file (see lines 9-10, 14, 22, 26-30, 36).

Suggested change
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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

Copilot uses AI. Check for mistakes.
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Kubernetes projected service account token volume example::
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The continuation text should be indented with 2 spaces to match the bullet point pattern, not 6 spaces. This is consistent with other continuation text in bullet points (see lines 16-18, 32-34).

Copilot uses AI. Check for mistakes.
Comment on lines +78 to +79
These settings apply to all Azure AD/Entra ID variants in this doc (common, tenant-specific, v2, and B2C). For more
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_ docs.
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The continuation text should be indented with 2 spaces to match the bullet point pattern, not 6 spaces. This is consistent with other continuation text in bullet points (see lines 16-18, 32-34).

Copilot uses AI. Check for mistakes.
.. _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
.. _Federated identity credentials: https://learn.microsoft.com/en-us/graph/api/resources/federatedidentitycredentials-overview
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference "Federated identity credentials" is defined but never used in the documentation. Either this reference should be used somewhere in the text (perhaps on line 79), or it should be removed if it's not needed.

Suggested change
.. _Federated identity credentials: https://learn.microsoft.com/en-us/graph/api/resources/federatedidentitycredentials-overview

Copilot uses AI. Check for mistakes.
# 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::
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The continuation text should be indented with 2 spaces to match the bullet point pattern, not 6 spaces. This is consistent with other continuation text in bullet points (see lines 16-18, 32-34).

Copilot uses AI. Check for mistakes.
Comment on lines +43 to +76
# Default path exported by Azure Workload Identity and GitHub Actions
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::

SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Kubernetes projected service account token volume example::

apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block indentation is incorrect. Code blocks within bullet points should be indented with 6 spaces from the left margin, not 12 spaces. This is consistent with the pattern used throughout this file (see lines 9-10, 14, 22, 26-30, 36).

Suggested change
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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
# Default path exported by Azure Workload Identity and GitHub Actions
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::
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
SOCIAL_AUTH_AZUREAD_OAUTH2_CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
Kubernetes projected service account token volume example::
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
serviceAccountName: myserviceaccount
containers:
- name: mycontainer
image: myimage
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

Copilot uses AI. Check for mistakes.
expirationSeconds: 3600

These settings apply to all Azure AD/Entra ID variants in this doc (common, tenant-specific, v2, and B2C). For more
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_ docs.
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrasing "see Workload Identity Federation_ and Federated identity credentials (Workload Identity)_ docs" is grammatically awkward. Consider rephrasing to "see the Workload Identity Federation_ and Federated identity credentials (Workload Identity)_ documentation" or simply "see Workload Identity Federation_ and Federated identity credentials (Workload Identity)_" without the word "docs".

Suggested change
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_ docs.
information on workload identity, see `Workload Identity Federation`_ and `Federated identity credentials (Workload Identity)`_.

Copilot uses AI. Check for mistakes.
@nijel
Copy link
Member

nijel commented Feb 4, 2026

Copilot is right here, the documentation indentation is messed up, see rendering: https://python-social-auth--393.org.readthedocs.build/en/393/backends/azuread.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants