Skip to content

Commit

Permalink
docs: Recommend use of Workload Identity for Azure Key Vault (externa…
Browse files Browse the repository at this point in the history 
…l-secrets#2906)

* docs: Recommend use of Workload Identity for Azure Key Vault

Mentions AAD Pod Identity is deprecated and updates overview
of supported authentication modes for Azure Key Vault.

This removes "should use aad-pod-identity" wording, see
external-secrets#2901

Signed-off-by: Mateusz Łoskot <[email protected]>

* docs: Fix missing link to Multi-Tenancy Guide

Signed-off-by: Mateusz Łoskot <[email protected]>

* docs: Fix typos

Capitalise own names.

Signed-off-by: Mateusz Łoskot <[email protected]>

---------

Signed-off-by: Mateusz Łoskot <[email protected]>
  • Loading branch information
@mloskot
mloskot authored Nov 27, 2023
1 parent c5fa8d8 commit 4acf82f
Showing 1 changed file with 13 additions and 9 deletions.
22 changes: 13 additions & 9 deletions docs/provider/azure-key-vault.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ External Secrets Operator integrates with [Azure Key vault](https://azure.micros

### Authentication

We support Service Principals, Managed Identity and Workload Identity authentication.
We support authentication with Microsoft Entra identities that can be used as Workload Identity or [AAD Pod Identity](https://azure.github.io/aad-pod-identity/docs/) as well as with Service Principal credentials.

To use Managed Identity authentication, you should use [aad-pod-identity](https://azure.github.io/aad-pod-identity/docs/) 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.
Since the [AAD Pod Identity](https://azure.github.io/aad-pod-identity/docs/) is deprecated, it is recommended to use the [Workload Identity](https://azure.github.io/azure-workload-identity) 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`.

Expand Down Expand Up @@ -40,6 +40,8 @@ A service Principal client and Secret is created and the JSON keyfile is stored

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 [aad-pod-identity](https://azure.github.io/aad-pod-identity/docs/) 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 [aad-pod-identity](https://azure.github.io/aad-pod-identity/docs/), then the SecretStore configuration should include the Id of the identity to be used via the `identityId` field.

```yaml
Expand All @@ -48,6 +50,8 @@ If there are multiple Managed Identities for different keyvaults, the operator s

#### Workload Identity

In Microsoft Entra, Workload Identity can be Application, user-assigned Managed Identity and Service Principal.

You can use [Azure AD Workload Identity Federation](https://docs.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation) 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 [azwi](https://azure.github.io/azure-workload-identity/docs/installation/azwi.html) cli very helpful. The Azure [Workload Identity Quick Start Guide](https://azure.github.io/azure-workload-identity/docs/quick-start.html) is also good place to get started.

This is basically a two step process:
Expand Down Expand Up @@ -80,7 +84,7 @@ You run the controller and mount that particular service account into the pod by
```

##### Referenced Service Account
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 withour Azure permissions and delegate authentication via service accounts in particular namespaces. Also see our [Multi-Tenancy Guide] for design considerations.
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 [Multi-Tenancy Guide](../guides/multi-tenancy.md) for design considerations.

```yaml
{% include 'azkv-workload-identity.yaml' %}
Expand All @@ -102,17 +106,17 @@ Or in case of Managed Identity authentication:

### Object Types

Azure KeyVault manages different [object types](https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#object-types), we support `keys`, `secrets` and `certificates`. Simply prefix the key with `key`, `secret` or `cert` to retrieve the desired type (defaults to secret).
Azure Key Vault manages different [object types](https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#object-types), 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 KeyVault does **not** export the private key. You may want to use [template functions](../guides/templating.md) to transform this JWK into PEM encoded PKIX ASN.1 DER format. |
| `key` | A JWK which contains the public key. Azure Key Vault does **not** export the private key. You may want to use [template functions](../guides/templating.md) 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 [template functions](../guides/templating.md) to transform this into your desired encoding |

### Creating external secret

To create a kubernetes secret from the Azure Key vault secret a `Kind=ExternalSecret` is needed.
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`.

Expand All @@ -139,10 +143,10 @@ To get a PKCS#12 certificate from Azure Key Vault and inject it as a `Kind=Secre
```

### Creating a PushSecret
You can push secrets to Keyvault into the different `secret`, `key` and `certificate` APIs.
You can push secrets to Azure Key Vault into the different `secret`, `key` and `certificate` APIs.

#### Pushing to a Secret
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 Keyvault:
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' %}
```
Expand All @@ -159,7 +163,7 @@ The first step is to generate a valid Private Key. Supported Formats include `PR
!!! 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.
#### Pushing to a Certificate
The first step is to generate a valid P12 certificate. Currently, only PKCS1/PKCS8 types are supported. Currently only passwordless P12 certificates are supported.
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
Expand Down

0 comments on commit 4acf82f

Please sign in to comment.