Project: external-secrets (Provisioning / Security & Compliance)
File: azure-key-vault.md

External Secrets Operator integrates with for secrets, certificates and Keys management. We support authentication with Microsoft Entra identities that can be used as Workload Identity or as well as with Service Principal credentials. Since the is deprecated, it is recommended to use the authentication. We support connecting to different cloud flavours azure supports: `PublicCloud`, `USGovernmentCloud`, `ChinaCloud` and `GermanCloud`. You have to specify the `environmentType` and point to the correct cloud flavour. This defaults to `PublicCloud`. ```yaml apiVersion: external-secrets.io/v1beta1 kind: SecretStore metadata: name: azure-backend spec: provider: azurekv: environmentType: PublicCloud # default ``` Minimum required permissions are `Get` over secret and certificate permissions. This can be done by adding a Key Vault access policy: ```sh KUBELETIDENTITYOBJECTID=$(az aks show --resource-group <AKSCLUSTERRGNAME> --name <AKSCLUSTERNAME> --query 'identityProfile.kubeletidentity.objectId' -o tsv) az keyvault set-policy --name kv-name-with-certs --object-id "$KUBELETIDENTITYOBJECT_ID" --certificate-permissions get --secret-permissions get ``` A service Principal client and Secret is created and the JSON keyfile is stored in a `Kind=Secret`. The `ClientID` and `ClientSecret` or `ClientCertificate` (in PEM format) should be configured for the secret. This service principal should have proper access rights to the keyvault to be managed by the operator. A Managed Identity should be created in Azure, and that Identity should have proper rights to the keyvault to be managed by the operator. Use to assign the identity to external-secrets operator. To add the selector to external-secrets operator, use `podLabels` in your values.yaml in case of Helm installation of external-secrets. If there are multiple Managed Identities for different keyvaults, the operator should have been assigned all identities via , then the SecretStore configuration should include the Id of the identity to be used via the `identityId` field. ```yaml {% include 'azkv-secret-store-mi.yaml' %} ``` In Microsoft Entra, Workload Identity can be Application, user-assigned Managed Identity and Service Principal. You can use to access Azure managed services like Key Vault without needing to manage secrets. You need to configure a trust relationship between your Kubernetes Cluster and Azure AD. This can be done in various ways, for instance using `terraform`, the Azure Portal or the `az` cli. We found the cli very helpful. The Azure is also good place to get

This is basically a two step process: Create a Kubernetes Service Account () ```sh azwi serviceaccount create phase sa \ --aad-application-name "${APPLICATION_NAME}" \ --service-account-namespace "${SERVICEACCOUNTNAMESPACE}" \ --service-account-name "${SERVICEACCOUNTNAME}" ``` Configure the trust relationship between Azure AD and Kubernetes () ```sh azwi serviceaccount create phase federated-identity \ --aad-application-name "${APPLICATION_NAME}" \ --service-account-namespace "${SERVICEACCOUNTNAMESPACE}" \ --service-account-name "${SERVICEACCOUNTNAME}" \ --service-account-issuer-url "${SERVICEACCOUNTISSUER}" ``` With these prerequisites met you can configure `ESO` to use that Service Account. You have two options: You run the controller and mount that particular service account into the pod by adding the label `azure.workload.identity/use: "true"`to the pod. That grants everyone who is able to create a secret store or reference a correctly configured one the ability to read secrets. This approach is usually not recommended. But may make sense when you want to share an identity with multiple namespaces. Also see our for design considerations. ```yaml {% include 'azkv-workload-identity-mounted.yaml' %} ``` You run the controller without service account (effectively without azure permissions). Now you have to configure the SecretStore and set the `serviceAccountRef` and point to the service account you have just created. This is usually the recommended approach. It makes sense for everyone who wants to run the controller without Azure permissions and delegate authentication via service accounts in particular namespaces. Also see our for design considerations. ```yaml {% include 'azkv-workload-identity.yaml' %} ``` In case you don't have the clientId when deploying the SecretStore, such as when deploying a Helm chart that includes instructions for creating a using next to the SecretStore definition, you may encounter an interpolation problem. Helm lacks dependency management, which means it can create an issue when the clientId is only known after everything is deployed. Although the Service Account can inject `clientId` and `tenantId` into a pod, it doesn't support secretKeyRef/configMapKeyRef. Therefore, you can deliver the clientId and tenantId directly, bypassing the Service Account. The following example demonstrates using the secretRef field to directly deliver the `clientId` and `tenantId` to the SecretStore while utilizing Workload Identity authentication. ```yaml {% include 'azkv-workload-identity-secretref.yaml' %} ``` Be sure the `azurekv` provider is listed in the `Kind=SecretStore` ```yaml {% include 'azkv-secret-store.yaml' %} ``` NOTE: In case of a `ClusterSecretStore`, Be sure to provide `namespace` in `clientId` and `clientSecret` with the namespaces where the secrets reside. Or in case of Managed Identity authentication: ```yaml {% include 'azkv-secret-store-mi.yaml' %} ``` Azure Key Vault manages different , we support `keys`, `secrets` and `certificates`. Simply prefix the key with `key`, `secret` or `cert` to retrieve the desired type (defaults to secret). | Object Type | Return Value | | - | | | `secret` | the raw secret value. | | `key` | A JWK which contains the public key. Azure Key Vault does not export the private

You may want to use to transform this JWK into PEM encoded PKIX ASN.1 DER format. | | `certificate` | The raw CER contents of the x509 certificate. You may want to use to transform this into your desired encoding | To create a Kubernetes secret from the Azure Key vault secret a `Kind=ExternalSecret` is needed. You can manage keys/secrets/certificates saved inside the keyvault , by setting a "/" prefixed type in the secret name, the default type is a `secret`. Other supported values are `cert` and `key`. ```yaml {% include 'azkv-external-secret.yaml' %} ``` The operator will fetch the Azure Key vault secret and inject it as a `Kind=Secret`. Then the Kubernetes secret can be fetched by issuing: ```sh kubectl get secret secret-to-be-created -n <namespace> -o jsonpath='{.data.dev-secret-test}' | base64 -d ``` To select all secrets inside the key vault or all tags inside a secret, you can use the `dataFrom` directive: ```yaml {% include 'azkv-datafrom-external-secret.yaml' %} ``` To get a PKCS#12 certificate from Azure Key Vault and inject it as a `Kind=Secret` of type `kubernetes.io/tls`: ```yaml {% include 'azkv-pkcs12-cert-external-secret.yaml' %} ``` You can push secrets to Azure Key Vault into the different `secret`, `key` and `certificate` APIs. Pushing to a Secret requires no previous setup. with the secret available in Kubernetes, you can simply refer it to a PushSecret object to have it created on Azure Key Vault: ```yaml {% include 'azkv-pushsecret-secret.yaml' %} ``` !!! note In order to create a PushSecret targeting keys, `CreateSecret` and `DeleteSecret` actions must be granted to the Service Principal/Identity configured on the SecretStore. The first step is to generate a valid Private Key. Supported Formats include `PRIVATE KEY`, `RSA PRIVATE KEY` AND `EC PRIVATE KEY` (EC/PKCS1/PKCS8 types). After uploading your key to a Kubernetes Secret, the next step is to create a PushSecret manifest with the following configuration: ```yaml {% include 'azkv-pushsecret-key.yaml' %} ``` !!! note In order to create a PushSecret targeting keys, `ImportKey` and `DeleteKey` actions must be granted to the Service Principal/Identity configured on the SecretStore. The first step is to generate a valid P12 certificate. Currently, only PKCS1/PKCS8 types are supported. Currently only password-less P12 certificates are supported. After uploading your P12 certificate to a Kubernetes Secret, the next step is to create a PushSecret manifest with the following configuration ```yaml {% include 'azkv-pushsecret-certificate.yaml' %} ``` !!! note In order to create a PushSecret targeting keys, `ImportCertificate` and `DeleteCertificate` actions must be granted to the Service Principal/Identity configured on the SecretStore.