Skip to main content

Role delegation

Overview​

Role delegation allows a role to act on behalf of another authenticated role. You use this feature for allowing end-users to authorize your backend services to perform actions on their behalf, without giving the backend services direct access to the end-users' stored data.

For example, your Vault stores secrets on behalf of your clients, but you don't want to give your backend services direct access to the client's secrets. Using role delegation, your client generates a token that allows access to their secrets and gives this token to your backend service. Your backend service can then use this token to access the client's secrets and perform an action that requires accessing the secrets on their behalf.

How it works​

To use delegation, you add a role that includes the roles it can delegate to in the trusted_roles field, like this:

[roles]

[roles.SecretsReadAccessRole]                      
    capabilities = ["CapObjectsReader", "CapObjectsLister"]
    policies = ["PolicyAllowSearchByID", "PolicyGetSecret"]
    trusted_roles = ["BackendRole"]  # <-- The trusted roles the SecretsReadAccessRole role can delegate to.

[roles.BackendRole]
     capabilities = []
     policies = []

[users]

[users.BackendUser]
	role = "BackendRole"
note

You cannot authenticate using the Authorization header with a role with trusted_roles using API keys or tokens (IDP).

Then, you set the X-Pvault-Delegation header to use the role, the "SecretsReadAccessRole" in the example. The X-Pvault-Delegation expects a token that can be authenticated by IDP, for example, a JWT token. See Direct JWT authentication for more information about how to generate a token. The X-Pvault-Delegation cannot be an API key.

Also, you use the Authorization header to authenticate the user or role, the "BackendRole" in the example, performing the request on behalf of the delegated role. The role performing the request must be listed in the trusted_entities field of the delegating role.

It's done like this in an API call:

curl --request GET \
	--url 'http://<server>/api/pvlt/1.0/data/collections/secrets/objects/<id>?reason=AppFunctionality&props=secret' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <backend-api-key>' \
    --header 'X-Pvault-Delegation: <role-jwt-token>'

It's done like this in a CLI call:

pvault object get --id <id> --props secret --collection secrets --authtoken <backend-api-key> --delegation <role-jwt-token>

The Authorization header is used to authenticate the user or role performing the request on behalf of the delegated role. The role performing the request must be listed in the trusted_entities field of the delegating role.

tip

Both users and roles can use delegated roles. The examples above show how to use a delegated role using a user, but you can also use role delegation with a role by setting both the Authorization and X-Pvault-Delegation headers as JWT tokens.

On this page