docs: add ADFS identity provider system to custom environments (#1010)

* docs: add ADFS identity provider system to custom environments * Update website/content/en/configurations/custom-environments.md Co-authored-by: Anish Ramasekar <anish.ramasekar@gmail.com> * Update _index.md Co-authored-by: Anish Ramasekar <anish.ramasekar@gmail.com>
Azure · Nov 1, 2022 · ed68f18 · ed68f18
1 parent 174cf12
commit ed68f18
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 3 deletions.
diff --git a/website/content/en/configurations/custom-environments.md b/website/content/en/configurations/custom-environments.md
@@ -55,6 +55,16 @@ The `cloudEnvFileName` parameter should match the volumeMount that was configure
 
 Even if the target cloud is not an Azure Stack Hub cloud, cloud name must be set to `"AzureStackCloud"` to signal `azure-sdk-for-go` to load the custom cloud environment details from `cloudEnvFileName`.
 
+If the target cloud's identity provider system is [AD FS][adfs] (instead of Azure AD), then the `tenantId` property in `SecretProviderClass` should be set to `"adfs"`.
+
+
+```yaml
+parameters:
+  cloudName: "AzureStackCloud"
+  cloudEnvFileName: "/path/to/custom/environment.json"
+  tenantId: "adfs"
+```
+
 ## Environment files
 
 The custom cloud environment sample below shows the minimum set of properties required:
@@ -67,3 +77,29 @@ The custom cloud environment sample below shows the minimum set of properties re
   "keyVaultDNSSuffix": "vault.azure.net"
 }
 ```
+
+### Azure Stack Hub Environment Files
+
+The environment file for most ARM-based Azure clouds can be generated by using as input the target cloud metadata. The following script shows how to generate the environment file for Azure Stack Hub clouds (both Azure AD and AD FS deployments).
+
+> Learn more about Azure Stack Hub's fully qualified domain names (FQDN) [here][ash-dns].
+
+```bash
+curl -s https://management.${FQDN}/metadata/endpoints?api-version=1.0 -o cloudMeta.json
+
+AD_EP=$(jq -r .authentication.loginEndpoint cloudMeta.json | sed -e 's|adfs$||1')
+KV_EP=$(jq -r .authentication.audiences[0] cloudMeta.json | sed "s|management.|vault.|1")
+KV_DNS=vault.${FQDN}
+
+cat << EOF
+{
+  "name": "AzureStackCloud",
+  "activeDirectoryEndpoint": "${AD_EP}",
+  "keyVaultEndpoint": "${KV_EP}",
+  "keyVaultDNSSuffix": "${KV_DNS}"
+}
+EOF
+```
+
+[adfs]: https://learn.microsoft.com/windows-server/identity/active-directory-federation-services
+[ash-dns]: https://learn.microsoft.com/azure-stack/operator/azure-stack-integrate-dns?#azure-stack-hub-dns-namespace
diff --git a/website/content/en/getting-started/usage/_index.md b/website/content/en/getting-started/usage/_index.md
@@ -28,7 +28,7 @@ Create a `SecretProviderClass` custom resource to provide provider-specific para
 
 Update [this sample deployment](https://raw.githubusercontent.com/Azure/secrets-store-csi-driver-provider-azure/master/examples/service-principal/v1alpha1_secretproviderclass_service_principal.yaml) to create a `SecretProviderClass` resource to provide Azure-specific parameters for the Secrets Store CSI driver.
 
-To provide identity to access key vault, refer to the following [section](#provide-identity-to-access-key-vault).
+To provide identity to access Key Vault, refer to the following [section](#provide-identity-to-access-key-vault).
 
   ```yaml
   apiVersion: secrets-store.csi.x-k8s.io/v1
@@ -82,7 +82,7 @@ To provide identity to access key vault, refer to the following [section](#provi
   | objectFormat           | no       | [__*available for version > 0.0.7*__] the format of the Azure Key Vault object, supported types are pem and pfx. `objectFormat: pfx` is only supported with `objectType: secret` and PKCS12 or ECC certificates        | "pem"         |
   | objectEncoding         | no       | [__*available for version > 0.0.8*__] the encoding of the Azure Key Vault secret object, supported types are `utf-8`, `hex` and `base64`. This option is supported only with `objectType: secret`                      | "utf-8"       |
   | filePermission         | no       | [__*available for version > v1.1.0*__] permission for secret file being mounted into the pod                      | "0644"       |
-  | tenantId               | yes      | tenant ID containing key vault instance                                                                                                                                                                                | ""            |
+  | tenantId               | yes      | tenant ID containing the Key Vault instance. Should be set to `"adfs"` for [Azure Stack Hub clouds](../../configurations/custom-environments) using the AD FS identity provider system                                                                       | ""            |
 
 #### Provide Identity to Access Key Vault
 
@@ -139,4 +139,5 @@ The Azure Key Vault Provider allows syncing previous versions of a secret via th
 If you want to sync one of these versions with a kubernetes secret, the only difference is that you have to specify which version you want (i.e., to use the latest version, you specify `{objectAlias}/0` in `[secretObjects].[objectName]`)
 
 ##### Permissions
-If you use this functionality, the principal being used to access Key Vault will also need the list permission for secrets, keys, and certificates. 
+
+If you use this functionality, the principal being used to access Key Vault will also need the list permission for secrets, keys, and certificates.