Skip to content
[ $ ] > P Y R O

Auth Methods, Entities and Groups

Auth Methods

Section titled “Auth Methods”
  • These are vault components that perform authentication and manages identities.
  • Responsible for assigning identity and policies to a user.
  • Multiple auth methods can be enables based on use case.
  • Tokens are the core method of authentication within vault
  • Most operations in vault require an existing token
  • Token auth method is responsible for creating and storing tokens

Auth Methods Workflow

Section titled “Auth Methods Workflow”
  1. User authenticates with credentials
  2. Validate credentials against provider (auth provider, could be OIDC, LDAP …)
  3. Generate vault token and attach policy or policies and a TTL
  4. Supply token to user
  5. User then uses that token for doing operations in vault

There are a lot of auth methods, see them at docs at 🌐

Configuring Auth Methods

Section titled “Configuring Auth Methods”
COMMANDEFFECT
vault auth enable -path=AUTH_METHOD_PATH -description="DESCRIPTION" AUTH_METHODEnable auth method at path, default path picked if path not supplied
vault auth disable AUTH_METHOD_PATHDisable auth method
vault auth listList auth methods
vault write auth/AUTH_METHOD_PATH/OPTIONS PARAMETERSConfigure auth method
vault auth tune AUTH_METHOD_PATH PARAMETERSModify vault auth method

Vault Entities

Section titled “Vault Entities”

  • Vault creates an entity every time a user logs in and attaches an alias to it if a corresponding entiry doesn’t already exist. The alias is combination of auth method and username or user ID

  • An entity is a representation of a single person or system used to log into the vault. Each has unique value, each entity is made of zero or more aliases.

  • Alias is a combination of auth method plus some identification. It is a mapping between an entity and auth method(s).

  • This is done using the Identity secrets engine, which manages internal identities that are recognized by vault. Identity secrets engine is default enabled and can’t be disabled, another instance of identity secrets engine also can’t be created.

  • Operators explicitly create and manage entities; Vault does not automatically sync identity information from external sources.

  • An entity can be created manually to map multiple entities for a single user to provide more efficient authorization management.

  • Any tokens created for the entity inherit the capabilities that are granted by alias(es).

  • This manually created entity has aliases to other entities that are required for inherited properties.

  • Policies get combined or we can say united from the particular alias and the current manual entity.

Managing Entities

Section titled “Managing Entities”

List Entities (Only IDs):

Terminal window
vault list identity/entity/id

Read Entity Details:

Terminal window
vault read identity/entity/id/ENTITY_ID

Read Entity ID using Name:

Terminal window
vault read -field=id identity/entity/name/ENTITY_NAME

Create Entity:

Terminal window
vault write identity/entity name="ENTITY_NAME" policies="POLICIES" metadata=METADATA

Update Entity(Name, Metadata, Policies):

Terminal window
vault write identity/entity/id/ENTITY_ID name="NEW_NAME" metadata=METADATA policies="POLICIES"

Delete Entity:

Terminal window
vault delete identity/entity/id/ENTITY_ID

Create Alias in Entity:

Terminal window
ENTITY_ID=$(vault read -field=id identity/entity/name/ENTITY_NAME)
USERPASS_ACCESSOR=$(vault auth list -format=json | jq -r '.[\"AUTH_METHOD_MOUNT_PATH/\"].accessor')
vault write identity/entity-alias name="ALIAS_NAME" canonical_id="$ENTITY_ID" mount_accessor="$USERPASS_ACCESSOR"

Delete Alias in Entity:

Terminal window
vault delete identity/entity-alias/id/ALIAS_ID

Vault Groups

Section titled “Vault Groups”
  • A group contains multiple entities as its members
  • A group can also have subgroups
  • Policies can be set to group and the permissions will be granted to all members of the group

Internal Groups

  • Used to easily manage permissions for entities
  • Frequently used when using vault namespaces to propagate permissions down to child namespaces
    • Helpful when the admin do not want to configure an identical auth method on every single namespace External Groups
  • Used to set permissions based on group members from an external identity provider. Such as Okta, OIDC, …
  • Allows admin to set up once and continue manage permissions and users in the identity provider instead of vault.

Managing Groups

Section titled “Managing Groups”

Create Group:

Terminal window
vault write identity/group name="NAME" type="internal" policies="POLICIES" member_entity_ids="ENTITY_IDS" metadata=METADATA

List Groups:

Terminal window
vault list identity/group/id

Read Group Details:

Terminal window
vault read identity/group/id/GROUP_ID

Update Group:

Terminal window
vault write identity/group/id/GROUP_ID policies="POLICIES" member_entity_ids="ENTITY_IDS" metadata=METADATA

Delete a Group:

Terminal window
vault delete identity/group/id/GROUP_ID

Add Members to Group:

Terminal window
CURRENT_MEMBERS=$(vault read -field=member_entity_ids identity/group/id/GROUP_ID)
NEW_MEMBERS="NEW_ENTITY_IDS"
UPDATED_MEMBERS="$CURRENT_MEMBERS,$NEW_MEMBERS"
vault write identity/group/id/GROUP_ID member_entity_ids="$UPDATED_MEMBERS"

Remove Members from Group:

Terminal window
CURRENT_MEMBERS=$(vault read -field=member_entity_ids identity/group/id/GROUP_ID)
# Remove members from the list in CURRENT_MEMBERS using shell/text tools, then update:
UPDATED_MEMBERS="LIST_OF_REMAINING_MEMBERS_AFTER_REMOVAL"
vault write identity/group/id/GROUP_ID member_entity_ids="$UPDATED_MEMBERS"

Add Member Groups to Group:

Terminal window
CURRENT_MEMBERS=$(vault read -field=member_group_ids identity/group/id/GROUP_ID)
UPDATED_MEMBERS="$CURRENT_MEMBERS,NEW_SUBGROUP_ID"
vault write identity/group/id/GROUP_ID member_group_ids="$UPDATED_MEMBERS"

Remove Member Groups from Group:

Terminal window
CURRENT_MEMBERS=$(vault read -field=member_group_ids identity/group/id/GROUP_ID)
# Remove subgroups in CURRENT_MEMBERS, then update:
UPDATED_MEMBERS="LIST_OF_REMAINING_SUBGROUPS_AFTER_REMOVAL"
vault write identity/group/id/GROUP_ID member_group_ids="$UPDATED_MEMBERS"