Introduction to roles

You can use roles in Vault to simplify adding many configuration settings to an auth method or secrets engine. This tutorial provides context for how and why roles are used in Vault. In later tutorials, you will create roles in the Vault.

Scenario

HashiCorp is working with Alice on the design for the HashiCups proof-of-concept and production implementation. Alice has worked with the other teams at HashiCups to design authentication for different teams, and workloads which must give access to specific secrets engines.

Alice must decide how to configure the various plugins to support HashiCups.

What are roles

A role is collection of parameters that you group together to simplify plugin configuration.

In the Introduction to tokens tutorial, you saw how you can manually create a token, attach a policy, and configure the TTL for the token.

Example:

$ vault token create -policy="default" -period=1m -explicit-max-ttl=2m
Key                  Value
---                  -----
token                hvs.CAESINxleXnwDWoVm...example...MDU4bGFGcUNjMVZnTzhZMDA
token_accessor       oesNHFzPatMS2t9gxDQIK6Iq
token_duration       1m
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

The policy, period (also known as the TTL), and the explicit-max-ttl are provided as command-line arguments. Specifying these settings for all authentication requests would be cumbersome and error prone.

Roles allow you to create a collection of parameters to simplify plugin configuration. Authentication requests only need to pass the role name to Vault. Vault will read the role configuration and issue a token based on the settings configured for that role.

Where roles are used

You can use roles with most authentication and secrets management plugins.

Many user authentication plugins can either map groups from an external provider such as an LDAP group, or OIDC group directly to Vault policies or use roles.

Most plugins that support workload authentication support the use of roles. You will decide which method works for your use case during the design stage by comparing business and technical requirements with the use of different plugins to meet those requirements.

You will explore these decisions in a later tutorial.

The user authentication plugin selected for the POC is the userpass auth method. This auth method does not support the use of roles.

Workloads in the POC will authenticate with Vault using the kubernetes auth method. This auth method works with most types of Kubernetes deployments, including developer environments using tools like minikube.

HashiCorp will review the configuration of the kubernetes auth method with Alice so HashiCups understands how they will use roles with their Vault deployment.

Roles are also supported by secrets engines that support dynamic credentials. Similar to roles for auth methods, you can use roles to specify required information for the system you are creating credentials for. You will learn more about dynamic secrets engines in a later tutorial.

True or false - roles are supported for all auth methods and secrets engines?

Create a role

Danielle starts a Vault dev mode server, and minikube for HashiCorp to show how a role is configured. This role will be created for the kubernetes auth method. You must first enable the auth method.

Example:

$ vault auth enable kubernetes
Success! Enabled kubernetes auth method at: kubernetes/

You enabled the auth method at the default path of kubernetes because the -path parameter did not set a custom path.

Once you enable an auth method, you can supply the required configuration to integrate it with the desired system. In this scenario you would point to the minikube cluster.

Example:

$ vault write auth/kubernetes/config \
    token_reviewer_jwt="$K8S_SERVICE_ACCOUNT_TOKEN" \
    kubernetes_host=https://192.168.99.100:443 \
    kubernetes_ca_cert=@ca.crt

Now that Vault can connect to the Kubernetes API using the configuration supplied in the earlier example, you can create a role that includes all desired parameters.

Example:

$ vault write auth/kubernetes/role/hashicupsApp \
     bound_service_account_names=k8sHashicupsAppSA \
     bound_service_account_namespaces=k8sDevNamespace \
     policies=default,dev-secrets \
     ttl=1h \
     explicit-max-ttl=2h

The hashicupsApp role, in addition to any auth method required configuration, includes the policies required for a tokens issued by this auth method, a ttl, and explicit-max-ttl.

A pod with the k8sHashicupsAppSA service account can then authenticate with Vault. Danielle issues a curl command to connect to the Vault API passing the role name to the login API.

Example:

$ POD_TOKEN=$(kubectl exec exampleapp-auth -- curl --silent \
   --request POST \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --data '{"jwt": "'$k8sHashicupsAppSA_TOKEN'", "role": "hashicupsApp"}' \
   $VAULT_ADDR/v1/auth/kubernetes/login | jq -r '.auth | .client_token')

Without having to pass extra parameters, Vault returns a token with a ttl set to 1h, with the default and dev-secrets policies attached, and renewable for up to 2h. These settings are part of the hashicupsApp Vault role.

Summary

Roles allow you to group configuration settings together to simplify plugin management. You can use roles for both auth methods and secrets engines. When used with an auth methods, roles include all configuration parameters necessary to work with external systems such as Kubernetes. When used with secrets engines, a role can also include custom statements to control how you want to create or revoke dynamic credentials.