Skip to content

docs: document Azure AD federated identity flow #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mehighlow wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: document Azure AD federated identity flow #393

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/backends/azuread.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,48 @@ To enable OAuth2 support:

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, 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::
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.

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.

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
Comment on lines +43 to +76
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
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.
Comment on lines +43 to +76
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.

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.
Comment on lines +39 to +79
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 +78 to +79
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.
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.

Tenant Support
--------------
Expand Down Expand Up @@ -132,3 +174,6 @@ The policy should start with `b2c_`. For more information see `Azure AD B2C User
.. _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.
.. _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