coder · ericpaulsen · Jan 28, 2024 · Jan 26, 2024 · Jan 26, 2024 · Jan 28, 2024
diff --git a/docs/guides/azure-federation.md b/docs/guides/azure-federation.md
@@ -0,0 +1,131 @@
+# Federating Coder's control plane to Azure
+
+<div>
+  <a href="https://github.com/ericpaulsen" style="text-decoration: none; color: inherit;">
+    <span style="vertical-align:middle;">Eric Paulsen</span>
+    <img src="https://github.com/ericpaulsen.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
+  </a>
+</div>
+January 26, 2024
+
+---
+
+This guide will walkthrough how to authenticate a Coder Provisioner to Microsoft
+Azure, using a Service Principal with a client certificate. You can use this
+guide for authenticating Coder to Azure, regardless of where Coder is run,
+either on-premise or in a non-Azure cloud. This method is one of several
+[recommended by Terraform](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).
+
+## Step 1: Generate Client Certificate & PKCS bundle
+
+We'll need to create the certificate Coder will use for authentication. Run the
+below command to generate a private key and self-signed certificate:
+
+```console
+openssl req -subj '/CN=myclientcertificate/O=MyCompany, Inc./ST=CA/C=US' \
+  -new -newkey rsa:4096 -sha256 -days 730 -nodes -x509 -keyout client.key -out client.crt
+```
+
+Next, generate a `.pfx` file to be used by Coder's Provisioner to authenticate
+the AzureRM provider:
+
+```console
+openssl pkcs12 -export -password pass:"Pa55w0rd123" -out client.pfx -inkey client.key -in client.crt
+```
+
+## Step 2: Create Azure Application & Service Principal
+
+Navigate to the Azure portal, and into the Microsoft Entra ID section. Select
+the App Registration blade, and register a new application. Fill in the
+following fields:
+
+- **Name**: this is a friendly identifier and can be anything (e.g. "Coder")
+- **Supported Account Types**: - set to "Accounts in this organizational
+  directory only (single-tenant)"
+
+The **Redirect URI** field does not need to be set in this case. Take note of
+the `Application (client) ID` and `Directory (tenant) ID` values, which will be
+used by Coder.
+
+## Step 3: Assign Client Certificate to the Azure Application
+
+To upload the certificate we created in Step 1, select **Certificates &
+secrets** on the left-hand side, and select **Upload Certificate**. Upload the
+public key file, which is `service-principal.crt` from the example above.
+
+## Step 4: Set Permissions on the Service Principal
+
+Now that the Application is created in Microsoft Entra ID, we need to assign
+permissions to the Service Principal so it can provision Azure resources for
+Coder users. Navigate to the Subscriptions blade in the Azure Portal, select the
+**Subscription > Access Control (IAM) > Add > Add role assignment**.
+
+Set the **Role** that grants the appropriate permissions to create the Azure
+resources you need for your Coder workspaces. `Contributor` will provide
+Read/Write on all Subscription resources. For more information on the available
+roles, see the
+[Microsoft documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles).
+
+## Step 5: Configure Coder to use the Client Certificate
+
+Now that the client certificate is uploaded to Azure, we need to mount the
+certificate files into the Coder deployment. If running Coder on Kubernetes, you
+will need to create the `.pfx` file as a Kubernetes secret, and mount it into
+the Helm chart.
+
+Run the below command to create the secret:
+
+```console
+kubectl create secret generic -n coder azure-client-cert-secret --from-file=client.pfx=/path/to/your/client.pfx
+```
+
+In addition, create secrets for each of the following values from your Azure
+Application:
+
+- Client ID
+- Tenant ID
+- Subscription ID
+- Certificate password
+
+Next, set the following values in Coder's Helm chart:
+
+```yaml
+coder:
+  env:
+    - name: ARM_CLIENT_ID
+      valueFrom:
+        secretKeyRef:
+          key: id
+          name: arm-client-id
+    - name: ARM_CLIENT_CERTIFICATE_PATH
+      value: /home/coder/az/
+    - name: ARM_CLIENT_CERTIFICATE_PASSWORD
+      valueFrom:
+        secretKeyRef:
+          key: password
+          name: arm-client-cert-password
+    - name: ARM_TENANT_ID
+      valueFrom:
+        secretKeyRef:
+          key: id
+          name: arm-tenant-id
+    - name: ARM_SUBSCRIPTION_ID
+      valueFrom:
+        secretKeyRef:
+          key: id
+          name: arm-subscription-id
+  volumes:
+    - name: "azure-client-cert"
+      secret:
+        secretName: "azure-client-cert-secret"
+  volumeMounts:
+    - name: "azure-client-cert"
+      mountPath: "/home/coder/az/"
+      readOnly: true
+```
+
+Upgrade the Coder deployment using the following `helm` command:
+
+```console
+helm upgrade coder coder-v2/coder -n coder -f values.yaml
+```
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1045,6 +1045,11 @@
           "title": "Template ImagePullSecrets",
           "description": "Creating ImagePullSecrets for private registries",
           "path": "./guides/image-pull-secret.md"
+        },
+        {
+          "title": "Azure Federation",
+          "description": "Federating Coder to Azure",
+          "path": "./guides/azure-federation.md"
         }
       ]
     }