Quickstart¶

For authenticating on a Vault server, each node needs credentials. Currently supported authentication methods are AppRoles and tokens.

To ease the management overhead, this extension allows the Salt master to distribute configuration and credentials to minions on demand. Thus, you only need to configure the master for the general case.

Issued credentials can either be tokens or AppRoles again.

Note

It’s generally recommended to authenticate with and distribute AppRoles because this is more secure and allows for advanced behavior. For simplicity, this extension currently defaults to token authentication/issuance though.

For background information, see the auth FAQ, specifically the sections on static auth methods and credential issuance.

Hint

You can explicitly choose to configure each minion manually instead of relying on the master (config_location). From here on, this guide assumes you are setting up a Salt master for credential orchestration.

Security¶

It is highly recommended that you have a general understanding of the Vault authentication and authorization mechanisms that you intend to use with this extension and how this usage fits into your security model.

The following is a non-exhaustive list of points to consider:

Using templating with grains might allow minions to access Vault policies they are not supposed to since they control the content themselves. Consider using pillars or hard coding policies instead.
In general, minions should never be allowed to mutate their own pillar, otherwise the pillar’s trustworthiness degrades to the level of grains. Specifically, if you employ the Vault pillar module, a minion must not have write access to its pillar’s source path.
Using AppRole authentication allows the Salt Master to create roles with arbitrary policies. A compromised Salt Master can thus escalate its privileges within the Vault namespace. In the present, this cannot be worked around with parameter constraints in a sensible way. This may not be a problem if the Salt Master manages the Vault server already or if it is dedicated to Salt.

Prerequisites¶

Important

This list shows basic examples of how to create the necessary resources to get you rolling quickly. It does not necessarily represent recommended practices, specifically regarding token/SecretID validity.

Token

A Vault server (cluster).
A Token Role. This is not strictly required, but if omitted, issued minion tokens are bound to the Salt master’s token validity and able to inherit all its policies.
```
vault write auth/token/roles/salt-master \
  orphan=true \
  allowed_policies=salt_minion \
  allowed_policies_glob='salt_minion_*,salt_role_*'
```

A policy allowing the Salt master access to token issuance endpoints:

# This is the required Salt master policy for issuing Tokens.

# Issue tokens
path "auth/token/create" {
  capabilities = ["create", "read", "update"]
}

# Issue tokens with Token Roles
# Substitute `salt-master` with the role name the master is configured with
path "auth/token/create/salt-master" {
  capabilities = ["create", "read", "update"]
}

You can write it to a file (e.g. salt-master.hcl) and create the policy like this:

vault policy write salt-master salt-master.hcl

Authentication credentials for the Salt master:

vault auth enable -path=approle approle
vault write auth/approle/role/salt-master \
  token_policies=salt-master \
  secret_id_num_uses=0 \
  secret_id_ttl=720h \
  token_ttl=30m \
  token_max_ttl=0
# Show RoleID
vault read auth/approle/role/salt-master/role-id
# Generate new SecretID
vault write -f auth/approle/role/salt-master/secret-id

Policies for minions as needed.

AppRole

A Vault server (cluster).

A separate (unused) mount of the AppRole auth backend, called salt-minions by default:

vault auth enable -path=salt-minions approle
# You will need the mount accessor to replace the placeholder
# in the policy below, so look it up now:
vault read -format json sys/auth/salt-minions | jq '.data.accessor'

A policy allowing the Salt master access to AppRole issuance endpoints:

# This is the required Salt master policy for issuing AppRoles.
# Note that credentials should be issued from a distinct mount,
# not the one the Salt master AppRole is configured at.
# This separate mount is called `salt-minions` by default.

# List existing AppRoles
path "auth/salt-minions/role" {
  capabilities = ["list"]
}

# Manage AppRoles
# This enables the Salt Master to create roles with arbitrary policies.
# If you need to restrict the assignable policies, issue tokens instead.
path "auth/salt-minions/role/*" {
  capabilities = ["read", "create", "update", "delete"]
}

# Lookup mount accessor
path "sys/auth/salt-minions" {
  capabilities = ["read", "sudo"]
}

# Lookup entities by alias name (role-id) and alias mount accessor
path "identity/lookup/entity" {
  capabilities = ["create", "update"]
  allowed_parameters = {
    "alias_name" = []
    # Replace `auth_approle_0a1b2c3d` with the output of the previous step
    "alias_mount_accessor" = ["auth_approle_0a1b2c3d"]
  }
}

# Manage entities with name prefix salt_minion_
path "identity/entity/name/salt_minion_*" {
  capabilities = ["read", "create", "update", "delete"]
}

# Create entity aliases – you can restrict the mount_accessor.
# This might allow privilege escalation in case the Salt master
# is compromised and the attacker knows the entity ID of an
# entity with relevant policies attached - although you might
# have other problems at that point.
path "identity/entity-alias" {
  capabilities = ["create", "update"]
  allowed_parameters = {
    "id" = []
    "canonical_id" = []
    # Replace `auth_approle_0a1b2c3d` with the output of the previous step
    "mount_accessor" = ["auth_approle_0a1b2c3d"]
    "name" = []
  }
}

Authentication credentials for the Salt master.

vault auth enable -path=approle approle
vault write auth/approle/role/salt-master \
  token_policies=salt-master \
  secret_id_num_uses=0 \
  secret_id_ttl=720h \
  token_ttl=30m \
  token_max_ttl=0
# Show RoleID
vault read auth/approle/role/salt-master/role-id
# Generate new SecretID
vault write -f auth/approle/role/salt-master/secret-id

Policies for minions as needed.

Secrets setup¶

Decide how you want to map minions to authorizations. A common pattern is to create policies based on minion IDs and minion roles, as shown in the example config above. This example setup is continued here.

Mount the KV backend¶

Mount the Key/Value v2 backend to a path, e.g. salt:

vault secrets enable -path=salt -version=2 kv

Create secrets¶

Write a secret that is accessible to all minions:

vault kv put -mount=salt general/accessible_for_all_minions all_foo=bar

Write a secret that is accessible to any minion that has the db role:

vault kv put -mount=salt roles/db db_foo=baz

Write a secret that is accessible to a specific minion named elliott:

vault kv put -mount=salt minions/elliott minion_foo=quux

Create policies¶

Create the policies that map necessary authorizations. The optimal setup depends on the issued credential type

Warning

If a secret path is used as a minion pillar, the minion must not have write access, otherwise a core security assumption in Salt is violated.

Important

Even if you only intend to use the secrets for minion pillars, you need to create minion policies. The master uses these policies to decide whether a minion should receive a specific pillar. The master should not have access to secret paths itself. For details, see Pillar impersonation.

Token

When issuing tokens, you cannot take advantage of minion metadata for templated Vault policies. You need to create all policies explicitly (consider automating this):

vault policy write salt_minion - <<'EOF'
path "salt/data/general/*" {
  capabilities = ["read"]
}
EOF

vault policy write salt_role_db - <<'EOF'
path "salt/data/roles/db" {
  capabilities = ["read"]
}
EOF
# + other roles as needed

vault policy write salt_minion_elliott - <<'EOF'
path "salt/data/minions/elliott" {
  capabilities = ["read"]
}
EOF
# + other minions as needed

AppRole

When issuing AppRoles, you can take advantage of minion metadata for templated Vault policies. This means a single policy should cover most minions and roles:

vault policy write salt_minion - <<'EOF'
path "salt/data/general" {
    capabilities = ["read"]
}

path "salt/data/minions/{{identity.entity.metadata.minion-id}}" {
    capabilities = ["read"]
}

path "salt/data/roles/{{identity.entity.metadata.roles__0}}" {
    capabilities = ["read"]
}

path "salt/data/roles/{{identity.entity.metadata.roles__1}}" {
    capabilities = ["read"]
}

path "salt/data/roles/{{identity.entity.metadata.roles__2}}" {
    capabilities = ["read"]
}

path "salt/data/roles/{{identity.entity.metadata.roles__3}}" {
    capabilities = ["read"]
}
EOF

Hint

See entity metadata templating for details, especially to understand why the roles mapping is repeated multiple times.

Test access¶

Now you can test that the minion is able to read all secrets:

[root@master ~]# salt elliott vault.read_secret salt/general/accessible_for_all_minions
elliott:
    ----------
    all_foo: bar
[root@master ~]# salt elliott vault.read_secret salt/roles/db
elliott:
    ----------
    db_foo: baz
[root@master ~]# salt elliott vault.read_secret salt/minions/elliott
elliott:
    ----------
    minion_foo: quux

If this fails, re-issue the minion’s token and try again:

salt elliott vault.clear_cache

If it still fails and you are issuing AppRoles, manually sync AppRoles and Entities and try again:

salt-run vault.sync_approles
salt-run vault.sync_entities
salt elliott vault.clear_cache

Quickstart¶

Security¶

Prerequisites¶

Salt master configuration¶

Credential orchestration¶

Required parameters¶

Master authentication¶

Credential issuance¶

Common customizations¶

Cache¶

Credential validity¶

Policies¶

Entity metadata¶

Complete examples¶

Secrets setup¶

Mount the KV backend¶

Create secrets¶

Create policies¶

Test access¶