Include role name in Entity Alias metadata

[stefan-zh]

Overview

This PR is suggesting the addition of the role name in the Entity Alias metadata on successful login.

Adding the role name on the Entity Alias metadata makes it easier to manage access to endpoints via ACL templated policies. Using the plugin mount accessor, one can simply use the following rule to restrict access: identity.entity.aliases.<mount_accessor>.metadata.role. Another auth plugin, AppRole, recently implemented this change for the same reason: hashicorp/vault#9529

Also, it already seems like the authors of this plugin had in mind that role is an important metadata that should not be overriden. We can assume this from the following two things. First, the only way to set metadata attributes on the Entity is through the claim_mappings property when creating an OIDC role (claim_mappings is the only way where properties from the OIDC JWT token will be mapped directly into the Entity Alias metadata). Second, we can see from the code that there is special reserved metadata role, which cannot be included in the claim_mappings: https://github.com/hashicorp/vault-plugin-auth-jwt/blob/main/path_role.go#L508. I can think only of 2 reasons why that is the case - 1) role is important to be present on the metadata without being overridden; 2) role must never appear in the metadata and should be excluded.

My assumption is that the developers of this plugin had option 1 in mind. However, as of now, the role metadata is not present on the Entity Alias metadata and cannot be included. Therefore, I am suggesting this PR to add role in the Entity Alias metadata.

Design of Change

The role name is added directly on the Entity Alias metadata on a successful login in the 2 available flows:

• the OIDC flow with a browser redirect
• the JWT flow

Related Issues/Pull Requests

None

Contributor Checklist

[ ] Add relevant docs to upstream Vault repository, or sufficient reasoning why docs won’t be added yet
My Docs PR Link
Example
[ ] Add output for any tests not ran in CI to the PR description (eg, acceptance tests)
[X] Backwards compatible

[hashicorp-cla]

All committers have signed the CLA.

[stefan-zh]

Tagging @fairclothjm and @austingebauer to take a look at this improvement.

[austingebauer]

Hi, @stefan-zh. This seems like a reasonable request. It's been requested before in hashicorp/vault-plugin-auth-kubernetes#111 without objection. I'm double checking that there aren't any gotchas before approving this.

[stefan-zh]

Thanks @austingebauer ! Only thing I'm not sure is whether to call it role or role_name as is the case with approle: https://github.com/hashicorp/vault/blob/main/builtin/credential/approle/path_login.go#L366

[austingebauer]

@stefan-zh - My preference is role similar to how it's specified for token metadata. I'd just like it to be consistent for both token and alias metadata (like it is for approle, although using a different key name). How does that sound?

[jbayer]

@austingebauer when I was playing with https://github.com/jbayer/vault-clients-for-humans and trying to get client metadata I was wondering what other Auth Methods do for setting up Entity Alias metadata values. As pointed out in this issue, AppRole does call it role_name. What do other Auth Methods like Kubernetes Auth Method do if anything? It would be helpful if there was a consistent attribute name that could be expected to be populated in the Entity Alias metadata. If we use role in this JWT Auth Method, then should we add role in AppRole Auth Method?

[stefan-zh]

@stefan-zh - My preference is role similar to how it's specified for token metadata. I'd just like it to be consistent for both token and alias metadata (like it is for approle, although using a different key name). How does that sound?

I have no strong preference here, so I'm fine to whatever we agree to. Only counter-argument I can bring in is that role can be meaningfully attributed to the Role object, while role_name is just the string.

[austingebauer]

@jbayer - I did a survey of the auth methods, and approle is the only one that sets the role name as alias metadata. Adding the role name has been requested in the Kubernetes auth method but has yet to be added. I agree that we should be consistent across auth methods. I think we'll want to add role to approle instead of use role_name here (explanation below). The JWT auth method is more flexible than most auth methods when it comes to configuration of alias metadata via claim mappings.

@stefan-zh - I forgot to mention another reason that I prefer role here is that it's already a reserved key which cannot be used for claim mappings. If we chose to use role_name, there is a chance someone is already using that in their claim mappings. A collision could at worst change their ACL policies if using templating and at best be confusing. Let me know your thoughts on this.

[jbayer]

Thanks @austingebauer, your explanation makes sense and I appreciate your summary of the behavior of the other Auth Methods.

[stefan-zh]

@austingebauer I agree with you on that point for using role. Then, my PR can be reviewed as is.

[austingebauer]

Thanks, both! Reviewing this PR as is 👍

[austingebauer]

Thanks for this, @stefan-zh! Looks good to me. It will eventually be released with Vault 1.16.