docs: document Azure AD federated identity flow

docs/backends/azuread.rst

@@ -35,6 +35,67 @@ 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 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
 --------------
@@ -132,3 +193,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
+.. _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