AppRole (Machine Authentication)

While all individuals use SAML to authenticate to Vault with their own named permissions, there are various ways for machines/apps/services to authenticate to Vault. AppRole is a popular machine authentication method that can be used for certain use cases. See the integration examples for more options.

In essence, an AppRole is a static username (role_id) and dynamic/rotatable password (secret_id) for a machine to authenticate to Vault to retrieve other secrets. AppRoles differ from traditional usernames and passwords in that you can have multiple secret_id's associated with a single role_id.

Creating an AppRole

AppRoles can only be created via the Vault CLI or API. They are not available for creation/configuration from the GUI. See this example for how terraform can also be used to create AppRoles.

1. Log in to Vault with the CLI. See this article for more information

   Bash

   export VAULT_ADDR=https://hcp-vault-private-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/
   vault login --method=saml --namespace=admin
   export VAULT_NAMESPACE=admin/CESI
   

2. Create a policy to associate with the AppRole. This is what gives the machine connecting to Vault permissions to perform operations in Vault. This example policy gives the approle permissions to create, read, update, patch, and delete any secrets in the secret/example/* path. This policy and its name should be customized for your use case.

   Note

   Most policies require /data/ after the mount (i.e. secret/data/...) to read from a Vault KV v2 secrets engine. A few integrations require the data to be omitted from the policy so it is important to look at the specific integration or include both.

   Bash

   vault policy write approle_example_access_policy - <<EOF
   path "secret/data/example/*" {
       capabilities = ["create", "read", "update", "patch", "delete"]
   }
   
   path "secret/example/*" {
       capabilities = ["create", "read", "update", "patch", "delete"]
   }
   EOF
   

3. Create the AppRole itself. The maximum life of a secret_id or password is 365 days and will need to be change at least yearly (or more often).

   Bash

   vault write auth/approle/role/example \
   token_policies="default,approle_example_access_policy" \
   secret_id_ttl="365d"
   

Reading the AppRole role_id (username)

Bash

export VAULT_ADDR=https://hcp-vault-private-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/
vault login --method=saml --namespace=admin

vault read --namespace=admin/CESI auth/approle/role/example/role-id

Creating a new AppRole secret_id (password)

Note

The output will include both a secret_id and secret_id_accessor. The secret_id is the password itself, whereas the secret_id_accessor is a record of that password that can later be used to revoke it. It may be good to record the secret_id_accessor as that makes revoking the secret_id easier.

Bash

export VAULT_ADDR=https://hcp-vault-private-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/
vault login --method=saml --namespace=admin
export VAULT_NAMESPACE=admin/CESI

vault write --namespace=admin/CESI -f auth/approle/role/example/secret-id 

Revoking an AppRole secret_id

Bash

export VAULT_ADDR=https://hcp-vault-private-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200/
vault login --method=saml --namespace=admin

# List the secret_id_accessors of all current secret_ids for example role
vault list --namespace=admin/CESI auth/approle/role/example/secret-id

# Revoke secret-id's no longer needed
vault write --namespace=admin/CESI auth/approle/role/example/secret-id-accessor/destroy secret_id_accessor=<SECRET ID ACCESSOR TO BE REVOKED>

# Confirm only expected remaining secret-id's exist
vault list --namespace=admin/CESI auth/approle/role/example/secret-id

Rotating an AppRole secret_id

1. Create a new secret_id using the steps in Creating a new AppRole secret_id.

2. Update the application or service to use the new secret_id.

3. Revoke the old secret_id using the steps in Revoking an AppRole secret_id.

While you do not technically need to revoke the old secret_id (as it will likely expire if a secret_id_ttl has been set), it is good best practice for security purposes to revoke unused secret_id's. The secrets management team will also be sending out notifications for expiring secret_id's so you will want to revoke ones that have been rotated/replaced so you do not continue to get notified about them expiring.