From 9d900c0f0411fde88a789b98381a136e5a5393f9 Mon Sep 17 00:00:00 2001
From: Anthony Shaw <anthony.p.shaw@gmail.com>
Date: Wed, 27 Mar 2024 06:42:35 +1100
Subject: [PATCH] [docs/azure] Explain how to use Managed Identity
 (password-less auth) (#1370)

---
 docs/backends/azure.rst | 53 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/docs/backends/azure.rst b/docs/backends/azure.rst
index 00d6fa99..20c94399 100644
--- a/docs/backends/azure.rst
+++ b/docs/backends/azure.rst
@@ -46,11 +46,55 @@ Authentication Settings
 
 Several different methods of authentication are provided. In order of precedence they are:
 
-#. ``connection_string`` or ``AZURE_CONNECTION_STRING`` (see `Connection string docs <http://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/>`_)
+#. ``connection_string`` or ``AZURE_CONNECTION_STRING`` (see `Connection string docs <https://azure.microsoft.com/documentation/articles/storage-configure-connection-string/>`_)
 #. (``account_key`` or ``AZURE_ACCOUNT_KEY``) and (``account_name`` or ``AZURE_ACCOUNT_NAME``)
-#. ``token_credential`` or ``AZURE_TOKEN_CREDENTIAL``
+#. ``token_credential`` or ``AZURE_TOKEN_CREDENTIAL`` with ``account_name`` or ``AZURE_ACCOUNT_NAME``
 #. ``sas_token`` or ``AZURE_SAS_TOKEN``
 
+Using Managed Identity
+++++++++++++++++++++++
+
+`Azure Managed Identity <https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview>`_ is an authentication method that allows you to authenticate to Azure services without storing credentials in your code.
+Managed Identity is the recommended mechanism for password-less authentication to Azure Storage Accounts from other Azure services like App Services, Functions, Container Apps, and VMs.
+
+To use Managed Identity you will need to configure a System Assigned Managed Identity or a User Assigned Managed Identity for your app service. Then you can use the `DefaultAzureCredential <https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential>`_ class from the Azure SDK to authenticate. 
+This class will automatically try all the available authentication methods in the order of precedence. ``DefaultAzureCredential`` will also use environment variables for local development, or VS Code Azure Login if available.
+
+This `guide <https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-python?tabs=managed-identity%2Croles-azure-portal%2Csign-in-azure-cli&pivots=blob-storage-quickstart-scratch#authenticate-to-azure-and-authorize-access-to-blob-data>`_ contains more information on assigning roles to Storage Accounts.
+
+Before using Managed Identity, you will need to install the Azure Identity package::
+
+  pip install azure-identity
+
+After creating the containers in the Azure Storage Account, you can configure Managed Identity in Django settings. 
+Import ``DefaultAzureCredential`` from ``azure.identity`` to use it for the ``token_credential`` property::
+
+
+  from azure.identity import DefaultAzureCredential
+
+  ...
+
+  STORAGES = {
+      "default": {
+          "BACKEND": "storages.backends.azure_storage.AzureStorage",
+          "OPTIONS": {
+              "token_credential": DefaultAzureCredential(),
+              "account_name": "mystorageaccountname",
+              "azure_container": "media",
+          },
+      },
+      "staticfiles": {
+          "BACKEND": "storages.backends.azure_storage.AzureStorage",
+          "OPTIONS": {
+              "token_credential": DefaultAzureCredential(),
+              "account_name": "mystorageaccountname",
+              "azure_container": "static",
+          },
+      },
+  }
+
+For `User assigned Managed Identity <https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#specify-a-user-assigned-managed-identity-for-defaultazurecredential>`_, pass the client ID parameter to the DefaultAzureCredential call.
+
 Settings
 ~~~~~~~~
 
@@ -145,7 +189,8 @@ Settings
 
   Default: ``None``
 
-  The api version to use.
+  The Azure Storage API version to use. Default value is the most recent service version that is compatible with the current SDK.
+  Setting to an older version may result in reduced feature compatibility.
 
 Using with Azurite (previously Azure Storage Emulator)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -194,7 +239,7 @@ The difference between public and private URLs is that private includes the SAS
 With private URLs you can override certain properties stored for the blob by specifying
 query parameters as part of the shared access signature. These properties include the
 cache-control, content-type, content-encoding, content-language, and content-disposition.
-See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-properties#remarks
+See https://docs.microsoft.com/rest/api/storageservices/set-blob-properties#remarks
 
 You can specify these parameters by::