Configure and manage keys

To use Azure with HYOK, you need to configure the following:

• A Key Vault and encryption key.
• An Entra ID Application which trusts the OIDC credentials issued by HCP Terraform.
• A service principal in the application with permission to use your key.

Create a Key Vault and an encryption key

Create a Key Vault and key to secure your sensitive HCP Terraform artifacts:

• If you do not already have one, create a Key Vault using the Azure portal.
• Then, add a key to the Key Vault to use to secure your sensitive Terraform artifacts.

Take note of the key URI, which is in the format: https://<KEY_VAULT_NAME>.vault.azure.net/keys/<KEY_NAME>. You will use this URI later to configure your key in HCP Terraform.

Create an Entra ID Application

Next, follow the steps to create the Application and Service Principal. Do not proceed to the Configure Microsoft Entra ID Application to Trust a GitHub Repository step, and set your Application Redirect URI type to Web. Also, take note of the client_id and tenant_id for your application. You use these values to configure your key in HCP Terraform.

Configure Entra ID to trust HCP Terraform

Next, create federated identity credentials in your application, which validate the contents of the token sent to Azure from HCP Terraform.

Follow the steps in the AzureRM provider docs: Configure Azure Microsoft Entra ID Application to Trust a Generic Issuer, and use the values below when you add the credential.

Specify the following information in the Add a credential step:

• Federated credential scenario: Set to Other issuer.
• Issuer: The address of HCP Terraform, https://app.terraform.io.
• Subject identifier: The subject identifier from HCP Terraform that this credential will match. This is in the form organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>. The HYOK configuration name can contain letters, numbers, hyphens, and underscores.
• Audience: Leave this as the default value, api://AzureADTokenExchange.

Make a note of the HYOK config name you choose here, you will use it later when you configure HCP Terraform.

To use AWS with HYOK, you need to configure the following:

• An OIDC Identity Provider for HCP Terraform.
• An IAM role with a trust policy that lets the HCP Terraform agent assume it.
• An AWS KMS key that your IAM role can use.

Create an OIDC Identity Provider

Follow the steps for Creating OpenID Connect (OIDC) identity providers - AWS Identity and Access Management through the AWS console or API.

Set your provider URL to the address of HCP Terraform (https://app.terraform.io) and the audience to aws.workload.identity.

Create an IAM Role and Trust Policy

Next, configure a role and corresponding trust policy by following: Creating a role for web identity or OpenID Connect Federation (console) - AWS Identity and Access Management.

Use the following trust policy as a template:

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Principal": {
              "Federated": "<the ARN of your new Identity Provider>"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
              "StringEquals": {
                  "app.terraform.io:aud": "aws.workload.identity"
              },
              "StringLike": {
                  "app.terraform.io:sub": "organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>"

              }
          }
      }
  ]
}

The Condition field matches against the subject claim of HCP Terraform's JWT. For HYOK, the subject claim is: organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>.

Wildcards are allowed when matching claims. For example, if you want to use the same role for all keys within your HCP Terraform organization, you can configure your subject claim to match all HYOK configurations in your organization: organization:<ORG_NAME>:hyok_config:*.

For additional security we recommend that you choose a configuration name now, so that only the specified HYOK configuration may assume this role: organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>. The HYOK configuration name can contain letters, numbers, hyphens, and underscores. Take note of the HYOK configuration name you specify here, you will use it when you create your HYOK configuration in HCP Terraform.

Create an AWS KMS Key

You must choose or create a symmetric AWS KMS key to use to encrypt and decrypt your data encryption keys. Use the AWS console or API and the steps in Create a symmetric encryption KMS key.

Add the IAM role you created in the previous step as a key user, so that the HCP Terraform agent can use it to perform cryptographic operations.

To use GCP with HYOK, you will configure the following:

• A key ring and a key to encrypt your sensitive HCP Terraform artifacts.
• A Workload Identity Pool and Provider configured to trust OIDC tokens issued by HCP Terraform.
• A service account that can be assumed with the workload identity provider and has permission to use the key.

Create a Key Ring and Key

To begin, Create a key ring and a Create a symmetric encryption key in Google Cloud KMS.

Make a note of the key name and the key ring name. You use these values later when you create your HYOK configuration in HCP Terraform.

Create a Service Account

Next, create a service account with permissions to encrypt and decrypt data with the key you created. The HCP Terraform Agent will assume the role of this service account in order to use this key to encrypt and decrypt your data encryption keys.

Ensure that you grant the service account the necessary IAM permissions to encrypt and decrypt data using your key. For example, you could use the Cloud KMS CryptoKey Encrypter/Decrypter role, though you may want further scope access to only your key.

Create a Workload Identity Pool and Provider

Create a workload identity pool and provider by following the steps in Configure Workload Identity Federation.

Make a note of the name you choose for the Workload Identity Pool, you will use it when you create your HYOK configuration in HCP Terraform.

When creating the Identity Provider, specify the following details:

• Provider type: Must be "OpenID Connect (OIDC)".
• Issuer (URL): The address of HCP Terraform, https://app.terraform.io.
• Audience: Leave the default value.
• Provider attributes mapping: Set the google.subject value to assertion.sub.
• Attribute Conditions: Restrict which identity tokens this provider authenticates by matching on the subject claim of the JWT minted by HCP Terraform. For HYOK, this would be: organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>.

If you want to use the same provider to access all keys within your organization, you may use wildcard matching in the condition: assertion.sub.startsWith("organization:<ORG_NAME>:hyok_config:") For additional security, we recommend choosing a configuration name now so that only workloads requiring a particular key may assume this role: assertion.sub.startsWith("organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>"). The HYOK configuration name can contain letters, numbers, hyphens, and underscores.

Note the HYOK_CONFIG_NAME value you choose here, as well as the pool name and provider name. You use these values when you create your HYOK configuration in HCP Terraform.

Grant Service Account Access to the Identity Pool

Finally, you need to grant the workload identity pool access to the service account by following the steps in Allow the external workload to impersonate the service account.

To use Vault with HYOK, you need to configure the following:

• Mount and configure a JWT Authentication backend.
• Mount a transit secrets engine and add a key.
• Add a role for the tfc-agent to assume and policies that let it use the key.

Mount and Configure a JWT Authentication backend

If you already have a JWT Authentication backend set up, use that existing backend. If not, enable it as shown below.

$ vault auth enable -path=jwt-prod jwt
Success! Enabled jwt auth method at: jwt-prod/

Configure Vault to trust HCP Terraform's identity tokens and verify them using HCP Terraform's public key. The following command configures the JWT authentication backend in Vault to trust HCP Terraform as an OIDC identity provider:

$ vault write auth/jwt-prod/config \
   oidc_discovery_url="https://app.terraform.io" \
   bound_issuer="https://app.terraform.io"
Success! Data written to: auth/jwt-prod/config

Do not include any trailing slashes from the HCP Terraform URL.

Create a key

Set up the resource you want to access, which is the key encryption key you will create in the next step. To do this, enable Vault's transit secrets engine if it is not already enabled, as shown below:

$ vault secrets enable transit
Success! Enabled the transit secrets engine at: transit/

Next, create the key which Vault will use to encrypt and decrypt your data encryption keys. To do this, give your key a unique name, as shown below. In the example below, the key name is unique-prod:

$ vault write -f transit/keys/unique-prod


Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        0s
deletion_allowed          false
derived                   false
exportable                false
imported_key              false
keys                      map[1:1738617996]
latest_version            1
min_available_version     0
min_decryption_version    1
min_encryption_version    0
name                      unique-prod
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      aes256-gcm96

Take note of the key name you chose, as you will need to refer to the value later.

Configure roles and policies

To add roles and policies, grant entities authenticating with the JWT the ability to encrypt and decrypt with your newly created key encryption key. This requires a role and an access policy that grants access to the key. Create a new encrypt-decrypt-policy.hcl file with the following contents:

path "transit/encrypt/<your key>" {
 capabilities = [ "create", "update" ]
}
path "transit/decrypt/<your key>" {
 capabilities = [ "create", "update" ]
}

Replace <your key> with the name of the key you created in the previous step.

$ vault policy write hyok-encrypt-prod encrypt-decrypt-policy.hcl
Success! Uploaded policy: hyok-encrypt-prod

Next, create a role that you will grant the policy above to, and that can also be assumed by the JWT authentication endpoint when given a valid HCP Terraform HYOK JWT.

Choose a unique name for the role, as outlined in the example below:

{
 "policies": ["hyok-encrypt-prod"],
 "bound_audiences": ["vault.workload.identity"],
 "bound_claims_type": "glob",
 "bound_claims": {
   "sub": "organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>"
 },
 "user_claim": "sub",
 "role_type": "jwt",
 "token_ttl": "20m"
}

Replace the following values in the above role configuration:

• The policies list needs to include the name of the policy you created.
• The bound_audiences list needs to be vault.workload.identity.
• The bound_claims.sub matches against the subject claim of the HCP Terraform-issued JWT, which for HYOK is organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>".

Wildcards are allowed when matching claims. For example, if you want to use the same role for all keys within your HCP Terraform organization, you can configure your subject claim to match all HYOK configurations in your organization: organization:<ORG_NAME>:hyok_config:*.

For additional security we recommend that you choose a configuration name now, so that only the specified HYOK configuration may assume this role: organization:<ORG_NAME>:hyok_config:<HYOK_CONFIG_NAME>. The HYOK configuration name can contain letters, numbers, hyphens, and underscores. Note the HYOK_CONFIG_NAME value you choose here. You use this value when you create your HYOK configuration in HCP Terraform.

Run the following command to create the role in Vault:

$ vault write auth/jwt-prod/role/unique-prod-role-prod @hyok-prod-role.json
Success! Data written to: auth/jwt-prod/role/unique-prod

To configure your OIDC connection in HCP Terraform, you need the following values from Azure:

• Application ID for your Entra ID Application. This is also called an Application (client) ID on the EntraID Application overview page.
• Tenant ID for your Entra ID Application. This is also called an Directory (tenant) ID on the EntraID Application overview page.
• Your Subscription ID from the Azure subscription overview page.

To configure your OIDC connection in HCP Terraform, you need the following values from AWS:

• Role ARN: The ARN of the IAM role you configured earlier.

To configure your OIDC connection in HCP Terraform, you need the following values from GCP:

• Service account email: The email of the service account you created in the previous step, with permission to encrypt and decrypt using your key.
• Your GCP Project Number for the project containing the Workload Identity Provider and service account.
• The fully qualified Workload Provider name, in the format: projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<WORKLOAD_IDENTITY_POOL_ID>/providers/<WORKLOAD_IDENTITY_POOL_PROVIDER_ID>

To configure your OIDC connection in HCP Terraform, you need the following values from Vault:

• The Address (URL) of your Vault instance, with https:// included.
• The Role name for the role you created on the JWT authentication endpoint in the previous step. In the Vault configuration example above, this was unique-prod-role-prod.
• The namespace to use when authenticating to Vault, such as admin.
• The JWT auth path where your JWT authentication backend is mounted. By default this is admin, but in the Vault configuration example above, it was jwt-prod.

If you are using Vault Enterprise with a custom CA, enter the TLS CA Certificate which authenticates it.

To configure your key in HCP Terraform, you need the full Key URI for the key you created in Azure, which uses the format: https://<KEY_VAULT_NAME>.vault.azure.net/keys/<KEY_NAME>

To configure your key in HCP Terraform, you need the following values from AWS:

• The full Key ARN for the KMS key.
• The Region that the key is located in.

To configure your key in HCP Terraform, you need the following values from GCP:

• The Key Ring Name for the key ring.
• The Key Name for the specific key in that ring.
• The Location that the key ring was created in, for example global or us-central1.

To configure your key in HCP Terraform, you need the Name of the key you created in the transit secrets engine. In the Vault configuration example above, this was unique-prod.