From a98310487c5000c957a9f4103a21f788a0689e93 Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Tue, 3 Feb 2026 11:13:22 -0800 Subject: [PATCH 1/8] docs: document Azure AD federated identity flow --- docs/backends/azuread.rst | 45 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index ddf2f0d1..61949762 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -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:: + + 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. Tenant Support -------------- @@ -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 +.. _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 From ab81d91a29770e5bf994243caa0fee7a2605447f Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Wed, 4 Feb 2026 15:00:20 -0800 Subject: [PATCH 2/8] Update docs/backends/azuread.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/backends/azuread.rst | 82 +++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 61949762..564162dc 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -36,47 +36,47 @@ 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:: - - 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. Tenant Support -------------- From 31a678a7f0fef183e66cfab76437fd1588f560d1 Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Wed, 4 Feb 2026 15:06:25 -0800 Subject: [PATCH 3/8] Update docs/backends/azuread.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/backends/azuread.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 564162dc..297ac832 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -174,6 +174,5 @@ 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 .. _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 From 785de4db24a004c74b330018694042c225ab94c0 Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Wed, 4 Feb 2026 17:42:15 -0800 Subject: [PATCH 4/8] docs: updates "Federated identity credentials" --- docs/backends/azuread.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 297ac832..b448c70b 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -40,10 +40,12 @@ To enable OAuth2 support: (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 + 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 + 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:: @@ -62,6 +64,9 @@ To enable OAuth2 support: 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 @@ -75,8 +80,7 @@ To enable OAuth2 support: 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. + 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 -------------- From 8f78ec5065d958823d68246c9d08f979b71fb040 Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Fri, 6 Feb 2026 10:08:47 -0800 Subject: [PATCH 5/8] Update docs/backends/azuread.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/backends/azuread.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index b448c70b..5f8208c2 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -37,10 +37,11 @@ To enable OAuth2 support: - 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:: + (for example, Kubernetes service account tokens issued via Azure Workload Identity, or other OIDC tokens where you manage + writing the token to a file). 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:: + Default path used by Azure Workload Identity on Kubernetes:: AZURE_FEDERATED_TOKEN_FILE=/var/run/secrets/azure/tokens/azure-identity-token From 396aa996c1b7495251d7034e85a93789c93c1b9b Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Fri, 6 Feb 2026 10:21:48 -0800 Subject: [PATCH 6/8] docs: clarify azuread FIC precedence --- docs/backends/azuread.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 5f8208c2..75ddbcf1 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -38,8 +38,11 @@ To enable OAuth2 support: - 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). The backend will automatically use a client assertion instead of ``CLIENT_SECRET`` when the - secret is omitted:: + 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:: From a74ef4436afaeafe35b45f7e81bdb0187d04317d Mon Sep 17 00:00:00 2001 From: Mykhailo Zahlada Date: Fri, 6 Feb 2026 10:31:35 -0800 Subject: [PATCH 7/8] docs: clarify Azure AD federated credential flow and precedence --- docs/backends/azuread.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 75ddbcf1..560bbac3 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -52,11 +52,22 @@ To enable OAuth2 support: SOCIAL_AUTH_AZUREAD_OAUTH2_FEDERATED_TOKEN_FILE = '/path/to/oidc/token' - You can also provide a pre-built client assertion JWT:: + 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 From 5cd31ed85033f0c0a7791639e2e6a30bd1aab502 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Mon, 9 Feb 2026 15:04:39 +0100 Subject: [PATCH 8/8] Apply suggestion from @nijel --- docs/backends/azuread.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backends/azuread.rst b/docs/backends/azuread.rst index 560bbac3..1d69d8cb 100644 --- a/docs/backends/azuread.rst +++ b/docs/backends/azuread.rst @@ -42,7 +42,7 @@ To enable OAuth2 support: 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:: + ``CLIENT_SECRET`` when the secret is omitted. Default path used by Azure Workload Identity on Kubernetes::