Merge pull request #3603 from ItalyPaleAle/azure-ad-auth-update

Update docs for using Azure AD.

daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/_index.md

@@ -3,5 +3,5 @@ type: docs
 title: "Authenticate to Azure"
 linkTitle: "Authenticate to Azure"
 weight: 1600
-description: "Learn about authenticating Azure components using Azure Active Directory or Managed Service Identities"
+description: "Learn about authenticating Azure components using Azure Active Directory or Managed Identities"
 ---

daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/authenticating-azure.md

@@ -9,59 +9,74 @@ aliases:
 weight: 10000
 ---
 
-Certain Azure components for Dapr offer support for the *common Azure authentication layer*, which enables applications to access data stored in Azure resources by authenticating with Azure Active Directory (Azure AD). Thanks to this:
-- Administrators can leverage all the benefits of fine-tuned permissions with Role-Based Access Control (RBAC).
-- Applications running on Azure services such as Azure Container Apps, Azure Kubernetes Service, Azure VMs, or any other Azure platform services can leverage [Managed Service Identities (MSI)](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview).
+Most Azure components for Dapr support authenticating with Azure AD (Azure Active Directory). Thanks to this:
 
+- Administrators can leverage all the benefits of fine-tuned permissions with Azure Role-Based Access Control (RBAC).
+- Applications running on Azure services such as Azure Container Apps, Azure Kubernetes Service, Azure VMs, or any other Azure platform services can leverage [Managed Identities (MI)](https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) and [Workload Identity](https://learn.microsoft.com/azure/aks/workload-identity-overview). These offer the ability to authenticate your applications without having to manage sensitive credentials.
 
 ## About authentication with Azure AD
 
 Azure AD is Azure's identity and access management (IAM) solution, which is used to authenticate and authorize users and services.
 
-Azure AD is built on top of open standards such OAuth 2.0, which allows services (applications) to obtain access tokens to make requests to Azure services, including Azure Storage, Azure Key Vault, Cosmos DB, etc. 
+Azure AD is built on top of open standards such OAuth 2.0, which allows services (applications) to obtain access tokens to make requests to Azure services, including Azure Storage, Azure Service Bus, Azure Key Vault, Azure Cosmos DB, Azure Database for Postgres, Azure SQL, etc. 
 
 > In Azure terminology, an application is also called a "Service Principal".
 
-Some Azure components offer alternative authentication methods, such as systems based on "master keys" or "shared keys". Although both master keys and shared keys are valid and supported by Dapr, you should authenticate your Dapr components using Azure AD. Using Azure AD offers benefits like the following.
+Some Azure components offer alternative authentication methods, such as systems based on "shared keys" or "access tokens". Although these are valid and supported by Dapr, you should authenticate your Dapr components using Azure AD whenever possible to take advantage of many benefits, including:
 
-### Managed Service Identities
+- [Managed Identities and Workload Identity](#managed-identities-and-workload-identity)
+- [Role-Based Access Control](#role-based-access-control)
+- [Auditing](#auditing)
+- [(Optional) Authentication using certificates](#optional-authentication-using-certificates)
 
-With Managed Service Identities (MSI), your application can authenticate with Azure AD and obtain an access token to make requests to Azure services. When your application is running on a supported Azure service, an identity for your application can be assigned at the infrastructure level.  
+### Managed Identities and Workload Identity
+
+With Managed Identities (MI), your application can authenticate with Azure AD and obtain an access token to make requests to Azure services. When your application is running on a supported Azure service (such as Azure VMs, Azure Container Apps, Azure Web Apps, etc), an identity for your application can be assigned at the infrastructure level.
+
+Once using MI, your code doesn't have to deal with credentials, which:
 
-Once using MSI, your code doesn't have to deal with credentials, which:
 - Removes the challenge of managing credentials safely
 - Allows greater separation of concerns between development and operations teams
 - Reduces the number of people with access to credentials
 - Simplifies operational aspects–especially when multiple environments are used
 
-### Role-based Access Control
+Applications running on Azure Kubernetes Service can similarly leverage [Workload Identity](https://learn.microsoft.com/azure/aks/workload-identity-overview) to automatically provide an identity to individual pods.
+
+### Role-Based Access Control
 
-When using Role-Based Access Control (RBAC) with supported services, permissions given to an application can be fine-tuned. For example, you can restrict access to a subset of data or make it read-only.
+When using Azure Role-Based Access Control (RBAC) with supported services, permissions given to an application can be fine-tuned. For example, you can restrict access to a subset of data or make the access read-only.
 
 ### Auditing
 
-Using Azure AD provides an improved auditing experience for access.
+Using Azure AD provides an improved auditing experience for access. Tenant administrators can consult audit logs to track authentication requests.
 
-### (Optional) Authenticate using certificates
+### (Optional) Authentication using certificates
 
-While Azure AD allows you to use MSI or RBAC, you still have the option to authenticate using certificates.
+While Azure AD allows you to use MI, you still have the option to authenticate using certificates.
 
 ## Support for other Azure environments
 
-By default, Dapr components are configured to interact with Azure resources in the "public cloud". If your application is deployed to another cloud, such as Azure China, Azure Government, or Azure Germany, you can enable that for supported components by setting the `azureEnvironment` metadata property to one of the supported values:
+By default, Dapr components are configured to interact with Azure resources in the "public cloud". If your application is deployed to another cloud, such as Azure China or Azure Government ("sovereign clouds"), you can enable that for supported components by setting the `azureEnvironment` metadata property to one of the supported values:
 
-- Azure public cloud (default): `"AZUREPUBLICCLOUD"`
-- Azure China: `"AZURECHINACLOUD"`
-- Azure Government: `"AZUREUSGOVERNMENTCLOUD"`
-- Azure Germany: `"AZUREGERMANCLOUD"`
+- Azure public cloud (default): `"AzurePublicCloud"`
+- Azure China: `"AzureChinaCloud"`
+- Azure Government: `"AzureUSGovernmentCloud"`
+
+> Support for sovereign clouds is experimental.
 
 ## Credentials metadata fields
 
-To authenticate with Azure AD, you will need to add the following credentials as values in the metadata for your [Dapr component]({{< ref "#example-usage-in-a-dapr-component" >}}). 
+To authenticate with Azure AD, you will need to add the following credentials as values in the metadata for your [Dapr component](#example-usage-in-a-dapr-component).
 
 ### Metadata options
 
-Depending on how you've passed credentials to your Dapr services, you have multiple metadata options. 
+Depending on how you've passed credentials to your Dapr services, you have multiple metadata options.
+
+- [Using client credentials](#authenticating-using-client-credentials)
+- [Using a certificate](#authenticating-using-a-certificate)
+- [Using Managed Identities (MI)](#authenticating-with-managed-identities-mi)
+- [Using Workload Identity on AKS](#authenticating-with-workload-identity-on-aks)
+- [Using Azure CLI credentials (development-only)](#authenticating-using-azure-cli-credentials-development-only)
 
 #### Authenticating using client credentials
 
@@ -73,7 +88,7 @@ Depending on how you've passed credentials to your Dapr services, you have multi
 
 When running on Kubernetes, you can also use references to Kubernetes secrets for any or all of the values above.
 
-#### Authenticating using a PFX certificate
+#### Authenticating using a certificate
 
 | Field | Required | Details | Example |
 |--------|--------|--------|--------|
@@ -85,27 +100,30 @@ When running on Kubernetes, you can also use references to Kubernetes secrets fo
 
 When running on Kubernetes, you can also use references to Kubernetes secrets for any or all of the values above.
 
-#### Authenticating with Managed Service Identities (MSI)
+#### Authenticating with Managed Identities (MI)
 
 | Field           | Required | Details                    | Example                                  |
 |-----------------|----------|----------------------------|------------------------------------------|
 | `azureClientId` | N        | Client ID (application ID) | `"c7dd251f-811f-4ba2-a905-acd4d3f8f08b"` |
 
-Using MSI, you're not required to specify any value, although you may pass `azureClientId` if needed.
+Using Managed Identities, the `azureClientId` field is generally recommended. The field is optional when using a system-assigned identity, but may be required when using user-assigned identities.
+
+#### Authenticating with Workload Identity on AKS
+
+When running on Azure Kubernetes Service (AKS), you can authenticate components using Workload Identity. Refer to the Azure AKS documentation on [enabling Workload Identity](https://learn.microsoft.com/azure/aks/workload-identity-overview) for your Kubernetes resources.
+
+#### Authenticating using Azure CLI credentials (development-only)
+
+> **Important:** This authentication method is recommended for **development only**.
 
-### Aliases
+This authentication method can be useful while developing on a local machine. You will need:
 
-For backwards-compatibility reasons, the following values in the metadata are supported as aliases. Their use is discouraged.
+- The [Azure CLI installed](https://learn.microsoft.com/cli/azure/install-azure-cli)
+- Have successfully authenticated using the `az login` command
 
-| Metadata key               | Aliases (supported but deprecated) |
-|----------------------------|------------------------------------|
-| `azureTenantId`            | `spnTenantId`, `tenantId`          |
-| `azureClientId`            | `spnClientId`, `clientId`          |
-| `azureClientSecret`        | `spnClientSecret`, `clientSecret`  |
-| `azureCertificate`         | `spnCertificate`                   |
-| `azureCertificateFile`     | `spnCertificateFile`               |
-| `azureCertificatePassword` | `spnCertificatePassword`           |
+When Dapr is running on a host where there are credentials available for the Azure CLI, components can use those to authenticate automatically if no other authentication method is configuration.
 
+Using this authentication method does not require setting any metadata option.
 
 ### Example usage in a Dapr component
 

daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/howto-aad.md

@@ -62,6 +62,7 @@ Save the output values returned; you'll need them for Dapr to authenticate with
 ```
 
 When adding the returned values to your Dapr component's metadata:
+
 - `appId` is the value for `azureClientId`
 - `password` is the value for `azureClientSecret` (this was randomly-generated)
 - `tenant` is the value for `azureTenantId`
@@ -93,11 +94,12 @@ Save the output values returned; you'll need them for Dapr to authenticate with
 ```
 
 When adding the returned values to your Dapr component's metadata:
+
 - `appId` is the value for `azureClientId`
 - `tenant` is the value for `azureTenantId`
 - `fileWithCertAndPrivateKey` indicates the location of the self-signed PFX certificate and private key. Use the contents of that file as `azureCertificate` (or write it to a file on the server and use `azureCertificateFile`)
 
-> **Note:** While the generated file has the `.pem` extension, it contains a certificate and private key encoded as _PFX (PKCS#12)_.
+> **Note:** While the generated file has the `.pem` extension, it contains a certificate and private key encoded as PFX (PKCS#12).
 
 {{% /codetab %}}
 
@@ -122,26 +124,13 @@ Expected output:
 Service Principal ID: 1d0ccf05-5427-4b5e-8eb4-005ac5f9f163
 ```
 
-The returned value above is the **Service Principal ID**, which is different from the Azure AD application ID (client ID). 
-
-**The Service Principal ID** is:
-- Defined within an Azure tenant
-- Used to grant access to Azure resources to an application
-
+The returned value above is the **Service Principal ID**, which is different from the Azure AD application ID (client ID). The Service Principal ID is defined within an Azure tenant and used to grant access to Azure resources to an application  
 You'll use the Service Principal ID to grant permissions to an application to access Azure resources. 
 
 Meanwhile, **the client ID** is used by your application to authenticate. You'll use the client ID in Dapr manifests to configure authentication with Azure services.
 
 Keep in mind that the Service Principal that was just created does not have access to any Azure resource by default. Access will need to be granted to each resource as needed, as documented in the docs for the components.
 
-{{% alert title="Note" color="primary" %}}
-This step is different from the [official Azure documentation](https://docs.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli). The short-hand commands included in the official documentation creates a Service Principal that has broad `read-write` access to all Azure resources in your subscription, which:
-
-- Grants your Service Principal more access than you likely desire. 
-- Applies _only_ to the Azure management plane (Azure Resource Manager, or ARM), which is irrelevant for Dapr components, which are designed to interact with the data plane of various services.
-
-{{% /alert %}}
-
 ## Next steps
 
-{{< button text="Use MSI >>" page="howto-msi.md" >}}
+{{< button text="Use Managed Identities >>" page="howto-mi.md" >}}

daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/howto-msi.md → daprdocs/content/en/developing-applications/integrations/Azure/azure-authentication/howto-mi.md

@@ -1,14 +1,16 @@
 ---
 type: docs
-title: "How to: Use Managed Service Identities"
-linkTitle: "How to: Use MSI"
+title: "How to: Use Managed Identities"
+linkTitle: "How to: Use MI"
 weight: 40000
-description: "Learn how to use Managed Service Identities"
+aliases:
+  - "/developing-applications/integrations/azure/azure-authentication/howto-msi/"
+description: "Learn how to use Managed Identities"
 ---
 
-Using MSI, authentication happens automatically by virtue of your application running on top of an Azure service that has an assigned identity. 
+Using Managed Identities (MI), authentication happens automatically by virtue of your application running on top of an Azure service that has an assigned identity. 
 
-For example, let's say you enable a managed service identity for an Azure VM, Azure Container App, or an Azure Kubernetes Service cluster. When you do, an Azure AD application is created for you and automatically assigned to the service. Your Dapr services can then leverage that identity to authenticate with Azure AD, transparently and without you having to specify any credential.
+For example, let's say you enable a managed service identity for an Azure VM, Azure Container App, or an Azure Kubernetes Service cluster. When you do, an Azure AD application is created for you and automatically assigned to the service. Your Dapr services can then leverage that identity to authenticate with Azure AD, transparently and without you having to specify any credentials.
 
 To get started with managed identities, you need to assign an identity to a new or existing Azure resource. The instructions depend on the service use. Check the following official documentation for the most appropriate instructions:
 
@@ -19,8 +21,9 @@ To get started with managed identities, you need to assign an identity to a new
 - [Azure Virtual Machines Scale Sets (VMSS)](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-cli-windows-vmss)
 - [Azure Container Instance (ACI)](https://docs.microsoft.com/azure/container-instances/container-instances-managed-identity)
 
+Dapr supports both system-assigned and user-assigned identities.
 
-After assigning a managed identity to your Azure resource, you will have credentials such as:
+After assigning an identity to your Azure resource, you will have credentials such as:
 
 ```json
 {
@@ -31,7 +34,7 @@ After assigning a managed identity to your Azure resource, you will have credent
 }
 ```
 
-From the returned values, take note of **`principalId`**, which is the Service Principal ID that was created. You'll use that to grant access to Azure resources to your Service Principal.
+From the returned values, take note of **`principalId`**, which is the Service Principal ID that was created. You'll use that to grant access to Azure resources to your identity.
 
 ## Next steps
 

daprdocs/content/en/reference/components-reference/supported-cryptography/azure-key-vault.md

@@ -38,7 +38,7 @@ The Azure Key Vault cryptography component supports authentication with Azure AD
 
 1. Read the [Authenticating to Azure]({{< ref "authenticating-azure.md" >}}) document.
 1. Create an [Azure AD application]({{< ref "howto-aad.md" >}}) (also called a Service Principal).
-1. Alternatively, create a [managed identity]({{< ref "howto-msi.md" >}}) for your application platform.
+1. Alternatively, create a [managed identity]({{< ref "howto-mi.md" >}}) for your application platform.
 
 ## Spec metadata fields
 
@@ -48,5 +48,6 @@ The Azure Key Vault cryptography component supports authentication with Azure AD
 | Auth metadata | Y | See [Authenticating to Azure]({{< ref "authenticating-azure.md" >}}) for more information  |  |
 
 ## Related links
+
 - [Cryptography building block]({{< ref cryptography >}})
 - [Authenticating to Azure]({{< ref azure-authentication >}})