Workload Identity and Azure documentation (#48755)

* Framework out Azure Workload Identity Federation documentation

* Add prereq/intro

* Add section on deciding a SPIFFE ID structure

* Add outline headings

* Add initial steps

* Add instructions for using CLI and SDK

* Finish up Azure workload id guide

* Minor fixup

docs/cspell.json

@@ -475,7 +475,9 @@
     "enzos",
     "errcode",
     "etcdctl",
+    "examplecontainer",
     "exampledb",
+    "examplestorageaccount",
     "exampletoken",
     "exampleuser",
     "exfiltrated",

docs/pages/enroll-resources/workload-identity/aws-oidc-federation.mdx

@@ -3,12 +3,7 @@ title: Configuring Workload Identity and AWS OIDC Federation
 description: Configuring AWS to accept Workload Identity JWTs as authentication using OIDC Federation
 ---
 
-<Admonition type="tip" title="Preview">
-Teleport Workload Identity is currently in Preview. This means that some
-features may be missing. We're actively looking for design partners to help us
-shape the future of Workload Identity and would love to
-[hear your feedback](mailto:product@goteleport.com).
-</Admonition>
+(!/docs/pages/includes/workload-id-preview.mdx!)
 
 Teleport Workload Identity issues flexible short-lived identities in JWT format.
 AWS OIDC Federation allows you to use these JWTs to authenticate to AWS

docs/pages/enroll-resources/workload-identity/azure-federated-credentials.mdx

@@ -0,0 +1,310 @@
+---
+title: Configuring Workload Identity and Azure Federated Credentials
+description: Configuring Azure to accept Workload Identity JWTs as authentication using Azure Federated Credentials
+---
+
+(!/docs/pages/includes/workload-id-preview.mdx!)
+
+Teleport Workload Identity issues flexible short-lived identities in JWT format.
+Azure Federated Credentials allows you to use these JWTs to authenticate to
+Azure services.
+
+This can be useful in cases where a machine needs to securely authenticate with
+Azure services without the use of a long-lived credential. This is because the
+machine can authenticate with Teleport without using any shared secrets by
+using one of our delegated join methods.
+
+In this guide, we'll configure Teleport Workload Identity and Azure to allow our
+workload to authenticate to the Azure Blob Storage and upload content to a
+container.
+
+## How it works
+
+This implementation differs from using the Teleport Application Service to
+protect Azure APIs in a few ways:
+
+- Requests to Azure are not proxied through the Teleport Proxy Service, meaning
+  reduced latency but also less visibility, as these requests will not be
+  recorded in Teleport's audit log.
+- Workload Identity works with any Azure client, including the command-line tool
+  but also their SDKs.
+- Using the Teleport Application Service to access Azure does not work with
+  Machine ID and therefore cannot be used when a machine needs to authenticate
+  with Azure.
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+- `tbot` must already be installed and configured on the host where the
+  workloads which need to access Teleport Workload Identity will run. For more
+  information, see the [deployment
+  guides](../machine-id/deployment/deployment.mdx).
+- An Azure resource group and subscription you wish to grant the workload access
+  to.
+
+<Notice type="warning">
+Issuing JWT SVIDs with Teleport Workload Identity requires at least Teleport
+version 16.4.3.
+</Notice>
+
+### Deciding on a SPIFFE ID structure
+
+Within Teleport Workload Identity, all identities are represented using a
+SPIFFE ID. This is a URI that uniquely identifies the entity that the identity
+represents. The scheme is always `spiffe://`, and the host will be the name of
+your Teleport cluster. The structure of the path of this URI is up to you.
+
+For the purposes of this guide, we will be granting access to Azure to the
+`spiffe://example.teleport.sh/svc/example-service` SPIFFE ID.
+
+If you have already deployed Teleport Workload Identity, then you will already
+have a SPIFFE ID structure in place. If you have not, then you will need to
+decide on a structure for your SPIFFE IDs.
+
+If you are only using Teleport Workload Identity with AWS OIDC Federation, you
+may structure your SPIFFE IDs so that they explicitly specify the Azure
+user-managed identity they are allowed to assume. However, it often makes more
+sense to name the workload or person that will use the SPIFFE ID. See the
+[best practices guide](./best-practices.mdx) for further advice.
+
+## Step 1/4. Configure Azure
+
+To configure Azure to accept Workload Identity JWT SVIDs as authentication,
+you'll need to create an identity to represent that workload within Azure, 
+configure that identity to accept JWT SVIDs issued by your Teleport Cluster as
+a federated credential, and then grant that identity the necessary permissions
+within Azure using a role assignment.
+
+### Create a user-managed identity
+
+First, you'll create a user-managed identity to represent the workload within
+Azure.
+
+1. Browse to the "Managed Identities" section of the Azure Portal.
+1. Select "Create" to open the "Create User Assigned Managed Identity" form.
+1. Select your resource group and subscription.
+1. Enter a unique name for your identity that describes the workload it will
+  represent. In our example, we will use "example-service".
+1. Select "Review + create".
+
+You now need to record some key information about the created user-managed
+identity to be used in future steps.
+
+Browse to the "Properties" section on the created user-managed identity and note
+down the "Client Id" and "Tenant Id", these values will both be UUIDs.
+
+### Create a federated credential
+
+Next, you need to configure a federated credential for the user-managed
+identity. This will configure Azure to accept JWT SVIDs issued by your Teleport
+cluster as a form of authentication for this user-managed identity.
+
+1. Browse to your user-managed identity in the Azure Portal and select the 
+  "Federated credentials" page from the "Settings" section.
+1. Select "Add Credential" to open the "Add Federated Credential" form.
+1. Select "Other" for the "Federated credential scenario".
+1. Enter the address of your Teleport Proxy service followed by
+  `/workload-identity` for the "Issuer URL", for example
+  `https://example.teleport.sh/workload-identity`.
+1. Enter the SPIFFE ID you have decided on for the workload in the
+  "Subject identifier" field. For example,
+  `spiffe://example.teleport.sh/svc/example-service`. This will control which
+  JWT SVIDs issued by Teleport Workload Identity will be accepted for this
+  user-managed identity.
+1. Enter a unique, identifiable name for the federated credential. For example,
+   `example-teleport-sh-svc-example-service`.
+1. Click "Add".
+
+### Create a storage account and container
+
+For the purposes of this guide, you'll create a storage account and container
+for your workload to authenticate to. You can skip this step if you already have
+resources you wish to grant the workload access to.
+
+First, create a storage account:
+
+1. Browse to the "Storage accounts" section of the Azure Portal and select the 
+  "Create" button to open the "Create a storage account" form.
+1. Select your resource group and subscription.
+1. Enter a unique, identifiable name for the storage account. Record this as 
+  you will need it later. In our examples we will use `examplestorageaccount`.
+1. Select a region and select "Azure Blob Storage" for the "Primary Service"
+  field.
+1. Click "Create".
+
+Now, you can create a storage container:
+
+1. Browse to the "Storage accounts" section of the Azure Portal and select the
+  storage account you created.
+1. Browse to the "Containers" section beneath the "Data storage" section.
+1. Select "Add container" to open the "New container" form.
+1. Enter a unique, identifiable name for the container. Record this as you will
+  need it later. In our examples we will use `examplecontainer`.
+
+### Create a role assignment
+
+Finally, you need to grant the user-managed identity the necessary permissions
+for your workload to perform the actions it needs to within Azure.
+
+When creating a role assignment in Azure, it can be scoped to different levels:
+
+- Subscription (to grant access to any resource within the subscription)
+- Resource Group (to grant access to any resource within the resource group)
+- Resource (to grant access to a specific resource)
+
+For the purposes of this guide, we will grant the user-managed identity the
+`Storage Blob Data Owner` role with the scope of the storage account you have
+created.
+
+1. Browse to the "Storage accounts" section of the Azure Portal and select the
+  storage account you created.
+1. Browse to "Access control (IAM)" in the sidebar, then select "Add" and "Add
+  role assignment".
+1. Under "Role" select "Storage Blob Data Owner".
+1. Under "Members", for "Assign access to" select "Managed identity" and then
+  press "Select members".
+1. For "Managed identity", select "User-assigned managed identity" and then 
+  search for and select the user-managed identity you created earlier.
+1. Click "Review + assign" and save your changes.
+
+## Step 2/4. Configure Teleport RBAC
+
+Now we need to configure Teleport to allow a JWT to be issued containing the
+SPIFFE ID we have chosen.
+
+Create `role.yaml` with the following content:
+
+```yaml
+kind: role
+version: v6
+metadata:
+  name: my-workload-azure
+spec:
+  allow:
+    spiffe:
+      - path: /svc/example-service
+```
+
+Replace:
+
+- `my-workload-azure` with a descriptive name for the role.
+- `/svc/example-service` with the path part of the SPIFFE ID you have chosen.
+
+Apply this role to your Teleport cluster using `tctl`:
+
+```code
+$ tctl create -f role.yaml
+```
+
+You now need to assign this role to the bot:
+
+```code
+$ tctl bots update my-bot --add-roles my-workload-azure
+```
+
+## Step 3/4. Issue Workload Identity JWTs
+
+You'll now configure `tbot` to issue and renew the short-lived JWT SVIDs for
+your workload. It'll write the JWT as a file on disk, where you can then
+configure Azure clients and SDKs to read it.
+
+Take your already deployed `tbot` service and configure it to issue SPIFFE SVIDs
+by adding the following to the `tbot` configuration file:
+
+```yaml
+outputs:
+  - type: spiffe-svid
+    destination:
+      type: directory
+      path: /opt/workload-identity
+    svid:
+      path: /svc/example-service
+    jwts:
+      - audience: api://AzureADTokenExchange
+        file_name: azure-jwt
+```
+
+Replace:
+
+- /opt/workload-identity with the directory where you want the JWT to be
+  written.
+- /svc/example-service with the SPIFFE ID you have chosen.
+
+Restart your `tbot` service to apply the new configuration. You should see a
+file created at `/opt/workload-identity/azure-jwt` containing the JWT.
+
+## Step 4/4. Configure the Azure CLIs and SDKs
+
+You can now use the issued JWT SVID to authenticate to Azure. How this is
+configured varies between the Azure CLI and Azure SDK.
+
+### Configuring Azure CLI
+
+To use the JWT SVID to authenticate with the Azure CLI, you perform
+log-in specifying the JWT and the client and tenant ID of the user-managed 
+identity you created. This performs an initial exchange of the JWT SVID for an
+Azure access token, which is then cached by the CLI until the access token 
+expires.
+
+Run the following, inserting the client and tenant id you recorded in the first
+step:
+
+```code
+$ az login \ 
+  --federated-token $(cat /opt/workload-identity/azure-jwt) \
+  --service-principal \
+  -u <user-managed-identity-client-id> \
+  -t <user-managed-identity-tenant-id>
+```
+
+You should see a message indicating that this has succeeded.
+
+You can now test this has succeeded by uploading a file to the Azure Blob
+Storage container:
+
+```sh
+$ echo "testing 1,2,3..." > test.txt
+# Upload a test file. Replace the name of the account and container with those
+# you selected earlier.
+$ az storage blob upload \
+  --auth login \
+  --account-name examplestorageaccount \
+  --container-name examplecontainer \
+  --name test.txt \
+  --file ./test.txt
+# Check that the file has been uploaded. Replace the name of teh account and
+# container with those you selected earlier.
+$ az storage blob list \
+  --auth login \
+  --output table \
+  --account-name examplestorageaccount \
+  --container-name examplecontainer
+```
+
+### Configuring Azure SDKs
+
+The Azure SDKs support a set of environment variables to configure them to use
+the federated credential for authentication with the issued JWT SVID:
+
+- `AZURE_CLIENT_ID`: The client ID of the user-managed identity.
+- `AZURE_TENANT_ID`: The tenant ID of the user-managed identity.
+- `AZURE_FEDERATED_TOKEN_FILE`: The path to the JWT SVID file, for example
+  `/opt/workload-identity/azure-jwt`.
+
+You can also explicitly configure the SDK to use the federated credential, this
+will vary language-to-language.
+
+## Next steps
+
+- [Azure Workload Identity Federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation):
+The official Azure documentation for Workload Identity Federation.
+- [Workload Identity Overview](./introduction.mdx): Overview of Teleport
+Workload Identity.
+- [JWT SVID Overview](./jwt-svids.mdx): Overview of the JWT SVIDs issued by
+Teleport Workload Identity.
+- [Best Practices](./best-practices.mdx): Best practices for using Workload
+Identity in Production.
+- Read the [configuration reference](../../reference/machine-id/configuration.mdx) to explore
+all the available configuration options.

docs/pages/enroll-resources/workload-identity/introduction.mdx

@@ -109,6 +109,7 @@ Learn how to configure Teleport Workload Identity for specific use-cases:
 - [AWS Roles Anywhere](./aws-roles-anywhere.mdx): Configuring AWS to accept Workload Identity certificates as authentication using AWS Roles Anywhere.
 - [AWS OIDC Federation](./aws-oidc-federation.mdx): Configuring AWS to accept Workload Identity JWTs as authentication using AWS OIDC Federation.
 - [GCP Workload Identity Federation](./gcp-workload-identity-federation-jwt.mdx): Configuring GCP to accept Workload Identity JWTs as authentication using GCP Workload Identity Federation.
+- [Azure Federated Credentials](./azure-federated-credentials.mdx): Configuring Azure to accept Workload Identity JWTs as authentication using Azure Federated Credentials.
 
 ### Other resources
 

docs/pages/enroll-resources/workload-identity/jwt-svids.mdx

@@ -58,7 +58,7 @@ platforms:
 
 - [AWS](./aws-oidc-federation.mdx)
 - [Google Cloud Platform](./gcp-workload-identity-federation-jwt.mdx)
-- Azure
+- [Azure](./azure-federated-credentials.mdx)
 
 ## Next steps