Skip to content

Commit 30b12d3

Browse files
gracegrimwoodrobobarioPaulRMellor
authored
Implement kroxylicious#2765: Document Azure Key Vault KMS usage for record encryption (kroxylicious#2894)
* kroxylicious#2765: First draft Azure Key Vault KMS docs Signed-off-by: Grace Grimwood <[email protected]> * setup tweaks Signed-off-by: Grace Grimwood <[email protected]> * fix con-azure-key-vault-plugin-configuration.adoc Signed-off-by: Grace Grimwood <[email protected]> * Update kroxylicious-docs/docs/_modules/record-encryption/azure-key-vault/con-azure-key-vault-setup.adoc Co-authored-by: Robert Young <[email protected]> Signed-off-by: Grace Grimwood <[email protected]> * docs tweaks from @robobario's feedback Signed-off-by: Grace Grimwood <[email protected]> * some more fixes Signed-off-by: Grace Grimwood <[email protected]> * add note about azure asymmetric keys to record encryption overview Signed-off-by: Grace Grimwood <[email protected]> * Update kroxylicious-docs/docs/_modules/record-encryption/azure-key-vault/con-azure-key-vault-key-creation.adoc Co-authored-by: Robert Young <[email protected]> Signed-off-by: Grace Grimwood <[email protected]> * fixes to oauth scripts Signed-off-by: Grace Grimwood <[email protected]> * adjust scripts in key creation Signed-off-by: Grace Grimwood <[email protected]> * Apply suggestions from code review Co-authored-by: PaulRMellor <[email protected]> Signed-off-by: Grace Grimwood <[email protected]> * rename azure-key-vault-setup a procedure - restructuring to follow Signed-off-by: Grace Grimwood <[email protected]> * add gating for managed identity content Signed-off-by: Grace Grimwood <[email protected]> * kill mentions of legacy permissions Signed-off-by: Grace Grimwood <[email protected]> * further fixes and tweaks Signed-off-by: Grace Grimwood <[email protected]> * rework granular permissions notes Signed-off-by: Grace Grimwood <[email protected]> * reformat proc-azure-key-vault-setup.adoc as a procedure Signed-off-by: Grace Grimwood <[email protected]> * refactor KEK_ prefix to KEK- across all the docs Signed-off-by: Grace Grimwood <[email protected]> * Apply suggestions from code review Co-authored-by: PaulRMellor <[email protected]> Signed-off-by: Grace Grimwood <[email protected]> --------- Signed-off-by: Grace Grimwood <[email protected]> Signed-off-by: Grace Grimwood <[email protected]> Co-authored-by: Robert Young <[email protected]> Co-authored-by: PaulRMellor <[email protected]>
1 parent 9e71faa commit 30b12d3

24 files changed

+430
-26
lines changed

‎kroxylicious-docs/docs/_assemblies/assembly-azure-key-vault.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
// file included in the following:
4+
//
5+
// assembly-record-encryption-filter.adoc
6+
7+
[id='assembly-azure-key-vault-{context}']
8+
= Preparing Azure Key Vault
9+
10+
[role="_abstract"]
11+
To prepare Azure Key Vault for use with the Record Encryption filter, use the following setup:
12+
13+
* Setup Azure resources
14+
* Establish a naming convention for keys
15+
* Create Azure Key Vault keys
16+
17+
You'll need a privileged Azure user that is capable of creating users and resources to perform the set-up.
18+
19+
include::../_modules/record-encryption/azure-key-vault/proc-azure-key-vault-setup.adoc[leveloffset=+1]
20+
include::../_modules/record-encryption/azure-key-vault/con-azure-key-vault-key-creation.adoc[leveloffset=+1]
21+
22+
[role="_additional-resources"]
23+
.Additional resources
24+
25+
* https://learn.microsoft.com/en-us/azure/key-vault/general/overview
26+
* https://learn.microsoft.com/en-us/azure/key-vault/keys/about-keys
27+
* https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-access-policy
28+
* https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices
29+
* https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview
30+
* https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/privileged
31+
* https://learn.microsoft.com/en-us/azure/role-based-access-control/scope-overview

‎kroxylicious-docs/docs/_assemblies/assembly-configuring-record-encryption-filter.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ endif::OpenShiftOnly[]
2828
+
2929
* <<con-vault-plugin-configuration-{context},HashiCorp Vault plugin configuration>>
3030
* <<con-aws-kms-plugin-configuration-{context},AWS KMS plugin configuration>>
31+
* <<con-azure-key-vault-plugin-configuration-{context},Azure Key Vault KMS plugin configuration>>
3132
ifdef::include-fortanix-dsm-kms[]
3233
* <<con-fortanix-dsm-plugin-configuration-{context},Fortanix DSM plugin configuration>>
3334
endif::[]
@@ -49,6 +50,8 @@ include::../_modules/record-encryption/hashicorp-vault/con-vault-plugin-configur
4950

5051
include::../_modules/record-encryption/aws-kms/con-aws-kms-plugin-configuration.adoc[leveloffset=+1]
5152

53+
include::../_modules/record-encryption/azure-key-vault/con-azure-key-vault-plugin-configuration.adoc[leveloffset=+1]
54+
5255
ifdef::include-fortanix-dsm-kms[]
5356
include::../_modules/record-encryption/fortanix-dsm/con-fortanix-dsm-plugin-configuration.adoc[leveloffset=+1]
5457
endif::[]

‎kroxylicious-docs/docs/_assemblies/assembly-preparing-kms.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ It describes how to prepare the KMS for use with the filter.
1313
include::assembly-hashicorp-vault.adoc[leveloffset=+1]
1414
//setting up AWS KMS
1515
include::assembly-aws-kms.adoc[leveloffset=+1]
16+
//setting up Azure Key Vault KMS
17+
include::assembly-azure-key-vault.adoc[leveloffset=+1]
1618
ifdef::include-fortanix-dsm-kms[]
1719
include::assembly-fortanix-dsm.adoc[leveloffset=+1]
1820
endif::[]

‎kroxylicious-docs/docs/_assets/attributes.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@
104104
// (note: we control optional inclusion with ifdefs/ifndefs directives, so the value of the attribute is irrelevant)
105105
:include-fortanix-dsm-kms: 1
106106
:include-aws-kms-service-config-identity-ec2-metadata: 1
107+
:include-azure-key-vault-service-config-microsoft-entra-managed-identity: 1
107108
:include-platform-bare-metal: 1
108109
:include-platform-kubernetes: 1
109110
// We're not ready to enable OLM yet

‎kroxylicious-docs/docs/_assets/trademarks.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
* Strimzi is a trademark of The Linux Foundation.
1010
* Hashicorp Vault is a registered trademark of HashiCorp, Inc.
1111
* AWS Key Management Service is a trademark of Amazon.com, Inc. or its affiliates.
12+
* Microsoft, Azure, and Microsoft Entra are trademarks of the Microsoft group of companies.
1213
ifdef::include-fortanix-dsm-kms[]
1314
* Fortanix and Data Security Manager are trademarks of Fortanix, Inc.
1415
endif::[]

‎kroxylicious-docs/docs/_modules/record-encryption/aws-kms/con-aws-kms-key-creation.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ If using the CLI, this can be done with commands like this:
2121

2222
[source,shell]
2323
----
24-
KEY_ALIAS="KEK_<name>"
24+
KEY_ALIAS="KEK-<name>"
2525
KEY_ID=$(aws kms create-key | jq -r '.KeyMetadata.KeyId')
2626
# the create key command will produce JSON output including the KeyId
2727
aws kms create-alias --alias-name alias/${KEY_ALIAS} --target-key-id ${KEY_ID}

‎kroxylicious-docs/docs/_modules/record-encryption/aws-kms/con-aws-kms-setup.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
The filter references KEKs within AWS via an {aws}/kms/latest/developerguide/alias-about.html[AWS key alias].
1212

1313
Establish a naming convention for key aliases to keep the filter’s keys separate from those used by other systems.
14-
Here, we use a prefix of KEK_ for filter aliases.
14+
Here, we use a prefix of KEK- for filter aliases.
1515
Adjust the instructions if a different naming convention is used.
1616

1717
== Role of the administrator
@@ -67,7 +67,7 @@ cat > /tmp/policy << EOF
6767
],
6868
"Condition": {
6969
"ForAnyValue:StringLike": {
70-
"kms:ResourceAliases": "alias/KEK_*"
70+
"kms:ResourceAliases": "alias/KEK-*"
7171
}
7272
}
7373
}

‎kroxylicious-docs/docs/_modules/record-encryption/azure-key-vault/con-azure-key-vault-key-creation.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
// file included in the following:
4+
//
5+
// assembly-azure-key-vault.adoc
6+
7+
[id='con-azure-key-vault-key-creation-{context}']
8+
= Creating Azure Key Vault keys
9+
10+
[role="_abstract"]
11+
As a user with the _Key Vault Crypto Officer_ role (or otherwise sufficient RBAC permissions to manage keys in Azure Key Vault), use either the Azure CLI or Azure PowerShell to create a `key` with `wrapKey` and `unwrapKey` operations enabled.
12+
13+
== Establish the naming convention for keys within key vault hierarchy
14+
15+
Establish a naming convention for keys to keep the filter’s keys separate from those used by other systems.
16+
17+
== Supported Key Types
18+
19+
NOTE: The key types available to you in Azure Key Vault will depend on your Azure Key Vault service tier. See the _About keys_ page in the Azure Key Vault docs for more details.
20+
21+
The filter accepts the following key types and their associated wrapping algorithms:
22+
23+
* *Symmetric Keys (`oct` or `oct-HSM`):* Uses the quantum-resistant `A256GCM` (256-bit AES GCM) wrapping algorithm, which requires a Managed HSM subscription.
24+
* *Asymmetric Keys (`RSA` or `RSA-HSM`):* Uses the `RSA-OAEP-256` (RSAES-OAEP with SHA-256 hash and MGF1/SHA-256 mask) wrapping algorithm, which is not quantum-resistant. This wrapping algorithm does not require a Managed HSM subscription to use (however, `RSA-HSM` is not available without a premium Azure Key Vault subscription).
25+
26+
If you use the Azure CLI, you can create a key with a command similar to the following:
27+
28+
[source,shell]
29+
----
30+
KEY_VAULT_NAME="kroxylicious-key-vault"
31+
KEY_NAME="KEK-<name>"
32+
KEY_TYPE="rsa"
33+
az keyvault key create --vault-name ${KEY_VAULT_NAME} --name ${KEY_NAME} --kty ${KEY_TYPE} --ops wrapKey unwrapKey
34+
----
35+
* Change `KEY_TYPE` if you want to use a key type other than RSA.
36+
* The `wrapKey` and `unwrapKey` operations must be enabled.
37+
38+
When the key is created, it is recommended to use a key rotation policy.
39+
40+
To configure a key rotation policy with the Azure CLI, save your policy to a JSON file. An example JSON file can be found in the Azure CLI docs.
41+
42+
When you've prepared your policy, apply it with a command like this:
43+
44+
[source,shell]
45+
----
46+
az keyvault key rotation-policy update --vault-name ${VAULT_NAME} --name ${KEY_NAME} --value path/to/my_policy.json
47+
----

‎kroxylicious-docs/docs/_modules/record-encryption/azure-key-vault/con-azure-key-vault-plugin-configuration.adoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
// file included in the following:
4+
//
5+
// assembly-configuring-record-encryption-filter
6+
7+
[id='con-azure-key-vault-plugin-configuration-{context}']
8+
= Azure Key Vault plugin configuration
9+
10+
[role="_abstract"]
11+
For Azure Key Vault the configuration for authenticating with Microsoft Identity Platform looks like this:
12+
13+
include::snip-azure-key-vault-service-config-microsoft-identity-platform-oauth2.adoc[leveloffset=+1]
14+
15+
ifdef::include-azure-key-vault-service-config-microsoft-entra-managed-identity[]
16+
17+
Alternatively, the configuration for authenticating with Managed Identities for Azure resources looks like this:
18+
19+
include::snip-azure-key-vault-service-config-microsoft-entra-managed-identity.adoc[leveloffset=+1]
20+
endif::[]
21+
22+
include::../../../_snippets/snip-tls-client-keystore.adoc[]
23+
24+
include::../../../_snippets/snip-tls-client-truststore.adoc[]

‎kroxylicious-docs/docs/_modules/record-encryption/azure-key-vault/proc-azure-key-vault-setup-microsoft-entra-managed-identity.adoc‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
// file included in the following:
4+
//
5+
// proc-azure-key-vault-setup.adoc
6+
7+
[id='proc-azure-key-vault-setup-microsoft-entra-managed-identity-{context}']
8+
= Authenticating with Managed Identities for Azure resources
9+
10+
[role="_abstract"]
11+
This procedure describes how to use a System-assigned Managed Identity (on the Azure resource where Kroxylicious is deployed) to allow the Record Encryption filter to authenticate to Azure Key Vault. The process uses the Azure CLI to enable the identity on the hosting resource and grant it the required Azure Role-Based Access Control (RBAC) role.
12+
13+
NOTE: A Managed Identity is a type of Service Principal that Azure manages automatically and does not require credentials. Assigning RBAC roles to a Managed Identity follows the same process as for other Service Principals.
14+
15+
.Prerequisites
16+
17+
* Access to the Azure CLI
18+
* A user with sufficient permissions to manage the hosting resource and assign RBAC roles.
19+
* The Azure resource that hosts Kroxylicious must be provisioned in advance.
20+
21+
.Procedure
22+
23+
. Enable the system-assigned managed identity on the hosting resource:
24+
+
25+
[source,shell]
26+
----
27+
HOST_RESOURCE_NAME="kroxylicious-host"
28+
HOST_RESOURCE_GROUP="my-resource-group"
29+
az <RESOURCE_TYPE> identity assign \
30+
--name ${HOST_RESOURCE_NAME} \
31+
--resource-group ${HOST_RESOURCE_GROUP} \
32+
--query "systemAssignedIdentity" --output tsv
33+
----
34+
* Set `HOST_RESOURCE_NAME` to the name of the Azure resource that hosts Kroxylicious.
35+
* Replace **<RESOURCE_TYPE>** with the correct Azure CLI subcommand for your resource type (for example, `vm`).
36+
* The command outputs the identifier of the system-assigned managed identity. Use this identifier in the next step.
37+
38+
. Assign the built-in Azure Key Vault RBAC role to the managed identity:
39+
+
40+
[source,shell]
41+
----
42+
SYSTEM_ASSIGNED_ID="x.kroxylicious-host"
43+
KEY_VAULT_NAME="kroxylicious-key-vault"
44+
RESOURCE_GROUP="my-resource-group"
45+
SCOPE_ID=$(az keyvault show --name ${KEY_VAULT_NAME} --resource-group ${RESOURCE_GROUP} --query "id" --output tsv)
46+
az role assignment create --assignee ${SYSTEM_ASSIGNED_ID} --role "Key Vault Crypto Service Encryption User" --scope ${SCOPE_ID}
47+
----
48+
* Set `SYSTEM_ASSIGNED_ID` to the managed identity’s identifier from the previous step.
49+
* Set `RESOURCE_GROUP` to the name of the resource group that contains your key vault. This may differ from the resource group that hosts Kroxylicious.
50+
+
51+
These commands assign the built-in Key Vault Crypto Service Encryption User role to the Managed Identity, using the target Key Vault as the scope. Replace `HOST_RESOURCE_NAME`, `KEY_VAULT_NAME`, and `RESOURCE_GROUP` with your actual values.
52+
53+
. (Optional) If you do not use the built-in RBAC roles, assign the following permissions to the managed identity instead:
54+
* `Microsoft.KeyVault/vaults/keys/read`
55+
* `Microsoft.KeyVault/vaults/keys/wrap/action`
56+
* `Microsoft.KeyVault/vaults/keys/unwrap/action`
57+
+
58+
If you are using Managed HSM, also assign `Microsoft.KeyVault/managedhsms/rng/action`.
59+
60+
. Confirm the role has been successfully assigned:
61+
+
62+
[source,shell]
63+
----
64+
SYSTEM_ASSIGNED_ID="x.kroxylicious-host"
65+
az role assignment list --assignee ${SYSTEM_ASSIGNED_ID} --query '[].{Role:roleDefinitionName, Scope:scope}' --output tsv
66+
----
67+
+
68+
The output lists the Key Vault Crypto Service Encryption User role and the full resource ID of your key vault.

0 commit comments

Comments
 (0)