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:
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?
False - certain plugins such as the userpass
auth method do not support roles.
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:
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:
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:
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:
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.