Configure groups and policies

After you've completed the steps in Integrate HashiCorp Vault with Okta, you can create groups and policies.

Configure groups in Okta

Create a group for each type of user (admins and developers, for example) who requires access to HCP Vault.

1. For each Okta-sourced group that you want to create, complete the steps in Create a group. Ensure that each group name uses the okta-group-vault prefix. For example, okta-group-vault-admins for admin users and okta-group-vault-developer for developer users.
2. Manually assign people to a group (or Bulk assign people to a group to grant granular access levels to users.

Configure policies in HCP Vault

Create a policy for each of the user groups that you created in the previous section. Policies ensure that different user personas and capabilities can access secrets that are stored in HCP Vault. See Introduction to policies for more information. There are two ways to configure policies: Use a CLI command or Use the API.

Use a CLI command

1. Run this command to create a policy file named vault-policy-developer-read.hcl:#!/bin/bash tee vault-policy-developer-read.hcl <<EOF # Read permission on the k/v secrets path "/secret/*" { capabilities = ["read", "list"] } EOF
2. Run this command to create a policy named vault-policy-developer-read. The policy uses the file that you created in the previous step:#!/bin/bash vault policy write vault-policy-developer-read vault-policy-developer-read.hcl
3. Run this command to create a policy file named vault-policy-admin.hcl:#!/bin/bash tee vault-policy-admin.hcl <<EOF # Admin policy path "*" { capabilities = ["sudo","read","create","update","delete","list","patch"] } EOF
4. Run this command to create a policy named vault-policy-admin. The policy uses the file that you created in the previous step:#!/bin/bash vault policy write vault-policy-admin vault-policy-admin.hcl
5. Run this command to view the policies you just created, as well as the default HCP Vault policies:#!/bin/bash vault policy list

Use the API

Complete these steps in either HCP Vault Dedicated or HCP Vault.

HCP Vault Dedicated

1. Send an API request that contains a JSON-formatted vault-policy-developer-read policy:#!/bin/bash tee vault-policy-developer-read.json <<EOF { "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\"]\n}\n" } EOF
2. Create a policy named vault-policy-developer-read that uses the policy that's defined in vault-policy-developer-read.json:curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request PUT \ --data @vault-policy-developer-read.json \ $VAULT_ADDR/v1/sys/policies/acl/vault-policy-developer-read
3. Create an API request that contains a JSON-formatted vault-policy-admin policy:#!/bin/bash tee vault-policy-admin.json <<EOF { "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\", \"sudo\", \"create\", \"update\", \"delete\", \"patch\"]\n}\n" } EOF
4. Create a policy named vault-policy-admin that uses the policy that's defined in vault-policy-admin.json: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request PUT \ --data @vault-policy-admin.json \ $VAULT_ADDR/v1/sys/policies/acl/vault-policy-admin
5. Run this command to view the policies you just created, as well as the default HCP Vault Dedicated policies: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ $VAULT_ADDR/v1/sys/policy | jq '.data | .policies'

HCP Vault

1. Send an API request that contains a JSON-formatted vault-policy-developer-read policy: #!/bin/bash tee vault-policy-developer-read.json <<EOF { "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\"]\n}\n" } EOF
2. Create a policy named vault-policy-developer-read that uses the policy that's defined in vault-policy-developer-read.json: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request PUT \ --data @vault-policy-developer-read.json \ $VAULT_ADDR/v1/sys/policies/acl/vault-policy-developer-read
3. Create an API request that contains a JSON-formatted vault-policy-admin policy: #!/bin/bash tee vault-policy-admin.json <<EOF { "policy": "path \"/secret/*\" {\n\tcapabilities = [\"read\", \"list\", \"sudo\", \"create\", \"update\", \"delete\", \"patch\"]\n}\n" } EOF
4. Create a policy named vault-policy-admin that uses the policy that's defined in vault-policy-admin.json: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request PUT \ --data @vault-policy-admin.json \ $VAULT_ADDR/v1/sys/policies/acl/vault-policy-admin
5. Run this command to view the policies you just created, as well as the default HCP Vault policies: curl --header "X-Vault-Token: $VAULT_TOKEN" \ $VAULT_ADDR/v1/sys/policy | jq '.data | .policies'

Configure groups in HCP Vault

Create groups in HCP Vault that match the groups that you've created in Okta. There are two ways to configure policies: Use a CLI command or Use the API.

Use a CLI command

1. Run this command to create a role called vault-role-okta-group-vault-developer. This action assigns the default policy to the role:#!/bin/bash vault write auth/oidc/role/vault-role-okta-group-vault-developer \ bound_audiences="$OKTA_CLIENT_ID" \ allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \ allowed_redirect_uris="http://localhost:8250/oidc/callback" \ user_claim="sub" \ token_policies="default" \ oidc_scopes="groups" \ groups_claim="groups"
2. Run this command to create a group called okta-group-vault-developer and assign it the vault-policy-developer-read policy:#!/bin/bash vault write identity/group name="okta-group-vault-developer" type="external" \ policies="vault-policy-developer-read" \ metadata=responsibility="okta-group-vault-developer"
3. Run this command to create a variable called GROUP_ID. The variable contains the ID for the group that you created earlier.#!/bin/bash GROUP_ID=$(vault read -field=id identity/group/name/okta-group-vault-developer)
4. Run this command to create an OIDC_AUTH_ACCESSOR variable for the OIDC authentication method:#!/bin/bash OIDC_AUTH_ACCESSOR=$(vault auth list -format=json | jq -r '."oidc/".accessor')
5. Run this command to create a group alias called okta-group-vault-developer. The alias connects the OIDC authentication method and the group that you created earlier to the vault-policy-developer-read policy.#!/bin/bash vault write identity/group-alias name="okta-group-vault-developer" \ mount_accessor="$OIDC_AUTH_ACCESSOR" \ canonical_id="$GROUP_ID"
6. Run this command, and then sign in as a developer with the okta-group-vault-developer role:#!/bin/bash vault login -method=oidc role="vault-role-okta-group-vault-developer"

   A success message and a list of key-value pairs appear. The token that's returned uses vault-policy-developer-read because okta-group-vault-developer matches the assigned Okta group.

7. Sign out of Okta.
8. Run this command to create a role called vault-role-okta-group-vault-admins:#!/bin/bash vault write auth/oidc/role/vault-role-okta-group-vault-admins \ bound_audiences="$OKTA_CLIENT_ID" \ allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \ allowed_redirect_uris="http://localhost:8250/oidc/callback" \ user_claim="sub" \ token_policies="default" \ oidc_scopes="groups" \ groups_claim="groups"
9. Run this command to create a okta-group-vault-admins group that uses the vault-policy-admin policy: #!/bin/bash vault write identity/group name="okta-group-vault-admins" type="external" \ policies="vault-policy-admin" \ metadata=responsibility="okta-group-vault-admins"
10. Run this command to create a GROUP_ID variable that stores the okta-group-vault-admins group ID: #!/bin/bash GROUP_ID=$(vault read -field=id identity/group/name/okta-group-vault-admins)
11. Run this command to create an OIDC_AUTH_ACCESSOR variable for the OIDC authentication method: #!/bin/bash OIDC_AUTH_ACCESSOR=$(vault auth list -format=json | jq -r '."oidc/".accessor')
12. Run this command to create a group alias called okta-group-vault-admins. The alias connects the OIDC authentication method and the group that you created earlier to the vault-policy-admin policy. #!/bin/bash vault write identity/group-alias name="okta-group-vault-admins" \ mount_accessor="$OIDC_AUTH_ACCESSOR" \ canonical_id="$GROUP_ID"
13. Run this command, and then sign in with the okta-group-vault-admins role:#!/bin/bash vault login -method=oidc role="vault-role-okta-group-vault-admins"

    A success message and a list of key-value pairs appear. The token that's returned uses vault-policy-admin because okta-group-vault-admins matches the assigned Okta group.

Use the API

Complete these steps in either HCP Vault Dedicated or HCP Vault.

HCP Vault Dedicated

1. Send a request for the okta-group-vault-developer role:#!/bin/bash tee vault-role-okta-group-vault-developer.json <<EOF { "bound_audiences": "$OKTA_CLIENT_ID", "allowed_redirect_uris": [ "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback", "http://localhost:8250/oidc/callback" ], "user_claim": "sub", "token_policies": ["default"], "oidc_scopes": "groups", "groups_claim": "groups" } EOF
2. Send a request to create a role called vault-role-okta-group-vault-developer:curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST \ --data @vault-role-okta-group-vault-developer.json \ $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-developer
3. Send a request that assigns the vault-policy-developer-read policy to the okta-group-vault-developer group: #!/bin/bash tee okta-group-vault-developer.json <<EOF { "name": "okta-group-vault-developer", "policies": ["vault-policy-developer-read"], "type": "external", "metadata": { "responsibility": "okta-group-vault-developer" } } EOF
4. Send a request to create a group that contains the okta-group-vault-developer.json group definition: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST --data @okta-group-vault-developer.json \ $VAULT_ADDR/v1/identity/group | jq
5. Send a request to create a GROUP_ID variable for the okta-group-vault-developer group:#!/bin/bash GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request GET \ $VAULT_ADDR/v1/identity/group/name/okta-group-vault-developer | jq '.data | .id' -r)
6. Send a request to create an OIDC_AUTH_ACCESSOR variable for the OIDC authentication method: #!/bin/bash OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
7. Use this command to create a group alias called okta-group-vault-developer:#!/bin/bash tee alias-okta-group-vault-developer.json <<EOF { "canonical_id": "$GROUP_ID", "mount_accessor": "$OIDC_AUTH_ACCESSOR", "name": "okta-group-vault-developer" } EOF
8. Send a request that shares the okta-group-vault-developer alias with HCP Vault:#!/bin/bash curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST -s \ --data @alias-okta-group-vault-developer.json \ $VAULT_ADDR/v1/identity/group-alias | jq
9. Send this request, and then sign in as a developer with the okta-group-vault-developer role:#!/bin/bash vault login -method=oidc role="vault-role-okta-group-vault-developer"

   A success message and a list of key-value pairs appear. The token that's returned uses vault-policy-developer-read because okta-group-vault-developer matches the assigned Okta group.

10. Sign out of Okta.
11. Send a request for the okta-group-vault-admins role:#!/bin/bash tee vault-role-okta-group-vault-admins.json << EOF { "bound_audiences": "$OKTA_CLIENT_ID", "allowed_redirect_uris": [ "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback", "http://localhost:8250/oidc/callback" ], "user_claim": "sub", "token_policies": ["default"], "oidc_scopes": "groups", "groups_claim": "groups" } EOF
12. Send a request to create a role called vault-role-okta-group-vault-admins:curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST \ --data @vault-role-okta-group-vault-admins.json \ $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-admins
13. Send a request that defines the okta-group-vault-admins group that's assigned to the vault-policy-admin policy:#!/bin/bash tee okta-group-vault-admins.json <<EOF { "name": "okta-group-vault-admins", "policies": ["vault-policy-admin"], "type": "external", "metadata": { "responsibility": "okta-group-vault-admins" } } EOF
14. Send a request that creates a group with the group definition in okta-group-vault-admins.json:curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST \ --data @okta-group-vault-admins.json $VAULT_ADDR/v1/identity/group | jq
15. Send a request to create a GROUP_ID variable that contains the okta-group-vault-admins group ID: #!/bin/bash GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request GET \ $VAULT_ADDR/v1/identity/group/name/okta-group-vault-admins | jq '.data | .id' -r)
16. Send a request to create OIDC_AUTH_ACCESSOR variable for the OIDC authentication method:#!/bin/bash OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
17. Send a request to create an okta-group-vault-admins alias: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST -s \ --data @alias-okta-group-vault-admins.json \ $VAULT_ADDR/v1/identity/group-alias | jq
18. Send this request, and then sign in with the vault-role-okta-group-vault-admin role: #!/bin/bash vault login -method=oidc role="vault-role-okta-group-vault-admins"

    A success message and a list of key-value pairs appear. The token that's returned uses vault-policy-admin because okta-group-vault-admins matches the assigned Okta group.

HCP Vault

1. Send an API request for the okta-group-vault-developer role: #!/bin/bash tee vault-role-okta-group-vault-developer.json << EOF { "bound_audiences": "$OKTA_CLIENT_ID", "allowed_redirect_uris": [ "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback", "http://localhost:8250/oidc/callback" ], "user_claim": "sub", "token_policies": ["default"], "oidc_scopes": "groups", "groups_claim": "groups" } EOF
2. Send a request to create a role called vault-role-okta-group-vault-developer: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request POST \ --data @vault-role-okta-group-vault-developer.json \ $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-developer
3. Send a request to create a group that contains the okta-group-vault-developer.json group definition: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request POST \ --data @okta-group-vault-developer.json \ $VAULT_ADDR/v1/identity/group | jq
4. Send a request to create a GROUP_ID variable that contains the okta-group-vault-developer ID: #!/bin/bash GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request GET \ $VAULT_ADDR/v1/identity/group/name/okta-group-vault-developer | jq '.data | .id' -r)
5. Send a request that creates an OIDC_AUTH_ACCESSOR variable for the OIDC authentication method: #!/bin/bash OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
6. Use this command to create an alias for okta-group-vault-developer: #!/bin/bash tee alias-okta-group-vault-developer.json <<EOF { "canonical_id": "$GROUP_ID", "mount_accessor": "$OIDC_AUTH_ACCESSOR", "name": "okta-group-vault-developer" } EOF
7. Send a request to share the okta-group-vault-developer alias with HCP Vault: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request POST -s \ --data @alias-okta-group-vault-developer.json \ $VAULT_ADDR/v1/identity/group-alias | jq
8. Send this request, and then sign in with the vault-role-okta-group-vault-developer role: #!/bin/bash vault login -method=oidc role="vault-role-okta-group-vault-developer"

   A success message and a list of key-value pairs appear. The token that's returned uses vault-policy-developer-read because okta-group-vault-developer matches the assigned Okta group.

9. Sign out of Okta.
10. Send a request for the okta-group-vault-admins role: #!/bin/bash tee vault-role-okta-group-vault-admins.json << EOF { "bound_audiences": "$OKTA_CLIENT_ID", "allowed_redirect_uris": [ "$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback", "http://localhost:8250/oidc/callback" ], "user_claim": "sub", "token_policies": ["default"], "oidc_scopes": "groups", "groups_claim": "groups" } EOF
11. Send a request to create a role called vault-role-okta-group-vault-admins: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request POST \ --data @vault-role-okta-group-vault-admins.json \ $VAULT_ADDR/v1/auth/oidc/role/vault-role-okta-group-vault-admins
12. Send a request that assigns the vault-policy-admin policy to the okta-group-vault-admins group: #!/bin/bash tee okta-group-vault-admins.json <<EOF { "name": "okta-group-vault-admins", "policies": ["vault-policy-admin"], "type": "external", "metadata": { "responsibility": "okta-group-vault-admins" } } EOF
13. Send a request to create a group that contains the okta-group-vault-admins.json group definition: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request POST \ --data @okta-group-vault-admins.json \ $VAULT_ADDR/v1/identity/group | jq
14. Send a request to create a GROUP_ID variable that contains the okta-group-vault-admins group: #!/bin/bash GROUP_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request GET \ $VAULT_ADDR/v1/identity/group/name/okta-group-vault-admins | jq '.data | .id' -r)
15. Send a request to create an OIDC_AUTH_ACCESSOR variable for the OIDC authentication method: #!/bin/bash OIDC_AUTH_ACCESSOR=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \ $VAULT_ADDR/v1/sys/auth | jq '.data | ."oidc/".accessor' -r)
16. Use this command to create an okta-group-vault-admins alias: #!/bin/bash tee alias-okta-group-vault-admins.json <<EOF { "canonical_id": "$GROUP_ID", "mount_accessor": "$OIDC_AUTH_ACCESSOR", "name": "okta-group-vault-admins" } EOF
17. Send a request to share the okta-group-vault-admins alias with HCP Vault: curl --header "X-Vault-Token: $VAULT_TOKEN" \ --request POST -s \ --data @alias-okta-group-vault-admins.json \ $VAULT_ADDR/v1/identity/group-alias | jq
18. Send this request, and then sign in with the vault-role-okta-group-vault-admins role: #!/bin/bash vault login -method=oidc role="vault-role-okta-group-vault-admins"

    A success message and a list of key-value pairs appears. The token that's returned uses vault-policy-admin because okta-group-vault-admins matches the assigned Okta group.

Next step

Test the integration