Using entities without aliases?

I wonder if someone could help clarify something for me.

In the description of entities, it says:

each entity is made up of zero or more aliases

I can also see from vault lookup token <T> that a token contains a (possibly-empty) entity_id. The token also contains a display_name, but not an entity alias.

However, I can’t see how to issue a token for an entity that has no alias.

The API call to create token lets you specify an entity alias, but not an entity. AFAICS, it doesn’t let you specify the mountpoint that qualifies the entity alias either.

If I test it:

# creating a token with entity alias *must* use a role
$ vault write auth/token/roles/foo allowed_entity_aliases='*'
Success! Data written to: auth/token/roles/foo

$ vault token create -ttl=12h -orphan -entity-alias=blah -role=foo
Key                  Value
---                  -----
token                s.bOKeoaeTG8WPKb2Wx2CvstdC
token_accessor       ejdDHJB3lUPs0NzPociY9Ayc
token_duration       12h
token_renewable      true
token_policies       ["root"]
identity_policies    []
policies             ["root"]

$ vault token lookup s.bOKeoaeTG8WPKb2Wx2CvstdC
Key                 Value
---                 -----
accessor            ejdDHJB3lUPs0NzPociY9Ayc
creation_time       1643112516
creation_ttl        12h
display_name        token
entity_id           47227f19-08dc-cbd4-a603-3fe88cd196c6
expire_time         2022-01-26T00:08:36.5314Z
explicit_max_ttl    0s
id                  s.bOKeoaeTG8WPKb2Wx2CvstdC
issue_time          2022-01-25T12:08:36.531404Z
meta                <nil>
num_uses            0
orphan              false
path                auth/token/create/foo
policies            [root]
renewable           true
role                foo
ttl                 11h59m21s
type                service

It has created a new entity, and also an entity alias “blah” connected to that entity, under the “token” mountpoint accessor:

$ vault read identity/entity/id/47227f19-08dc-cbd4-a603-3fe88cd196c6
Key                    Value
---                    -----
aliases                [map[canonical_id:47227f19-08dc-cbd4-a603-3fe88cd196c6 creation_time:2022-01-25T12:08:36.530852Z custom_metadata:<nil> id:8d21fa4c-e16d-0c5d-9762-986467b8930a last_update_time:2022-01-25T12:08:36.530852Z local:false merged_from_canonical_ids:<nil> metadata:<nil> mount_accessor:auth_token_eaeec7a1 mount_path:auth/token/ mount_type:token name:blah]]
creation_time          2022-01-25T12:08:36.530847Z
direct_group_ids       []
disabled               false
group_ids              []
id                     47227f19-08dc-cbd4-a603-3fe88cd196c6
inherited_group_ids    []
last_update_time       2022-01-25T12:08:36.530847Z
merged_entity_ids      <nil>
metadata               <nil>
name                   entity_0e0f38fd
namespace_id           root
policies               []

$ vault read identity/entity-alias/id/8d21fa4c-e16d-0c5d-9762-986467b8930a
Key                          Value
---                          -----
canonical_id                 47227f19-08dc-cbd4-a603-3fe88cd196c6
creation_time                2022-01-25T12:08:36.530852Z
custom_metadata              <nil>
id                           8d21fa4c-e16d-0c5d-9762-986467b8930a
last_update_time             2022-01-25T12:08:36.530852Z
local                        false
merged_from_canonical_ids    <nil>
metadata                     <nil>
mount_accessor               auth_token_eaeec7a1
mount_path                   auth/token/
mount_type                   token
name                         blah
namespace_id                 root

$ vault auth list
Path         Type        Accessor                  Description
----         ----        --------                  -----------
token/       token       auth_token_eaeec7a1       token based credentials
userpass/    userpass    auth_userpass_36422767    n/a

(I’m aware that this token has the root role - I’ve ignored that for simplicity)

So my questions are:

  1. Is it true that it’s not possible to issue a token for an entity without adding an alias to it?
  2. If so, why is that - given that the token itself doesn’t appear to remember which associated alias was used to authenticate? Or does it?
  3. In order to issue a token for a previously-created entity, is it up to me to create a named alias under the ‘token’ auth mountpoint explicitly? (Otherwise, it appears Vault will create a brand new entity)
  4. Could adding this alias have any unexpected side effects? e.g. does it open up a new way for someone to authenticate as this entity, apart from possessing the token I just generated?

What I’m actually trying to do is to issue a token for an entity, before any aliases have been attached to it, as part of an account setup/registration process. The token would be used as a temporary login until the alias has been attached. Maybe I’m going about this the wrong way, but I’d still like to understand a bit more about the relationship between entities, entity aliases, and tokens.

Thanks in advance,


Supplementary question. The documentation for token lookup shows it returning both policies and identity_policies:

  "data": {
    "identity_policies": ["dev-group-policy"],
    "policies": ["default", "testgroup2-policy"],

However when I do vault token lookup I don’t see identity_policies.

Is the API documentation correct, but the vault CLI is hiding these fields? Are the policies shown by vault token lookup the union of the entity policies and the token policies?

  1. I think if you’re creating an auth token directly (via auth/token/create) then an Identity/Alias would not be auto-created. However, using any other auth method to log in should result in a new Identity and associated Alias to be created
  2. As long as you’re authenticating in the same way a new token should be associated with an existing Alias
  3. It’s not required but may help in your administrative efforts
  4. Not to my knowledge. Basically it allows you to be able to manage policy assignment in a more dynamic way, such as using Templated Policies

I don’t understand why you’d need to issue a token before any Aliases are created. I would just create the Entities/Groups and associated Aliases up front, assuming you know the required details.

re: policies/identity_policies - When running via API or CLI I get identity_policies and policies returned with the same data. Note that policies are those assigned via the token directly or via the auth role. If you do not assign any policies to the Entity/Group or the Alias isn’t associating properly you will not see any identity_policies.

The scenario is that I’m logged in with one token (say an entity in an administrator group, or for simplicity say just a root token) and I want to create a token for some other entity. I can’t see how to do this, without creating an alias for that entity under the ‘token’ auth mountpoint.

The problem is that when using OpenID identities, you don’t necessarily know the “sub” claim of the user in advance. The user probably doesn’t even know their own “sub” claim (e.g. in the case of Google accounts it’s just a very long number that they never see)

I’m looking to build a process where I can get the user to authenticate to the Vault UI, which creates a new entity with a new alias, and then merge this new temporary entity with their real entity.

Maybe I’ll end up doing this differently.

Thanks. I can confirm that if I set a policy on the entity, then identity_policies is now displayed:

$ vault write identity/entity/name/entity_0e0f38fd policies=ergh
Success! Data written to: identity/entity/name/entity_0e0f38fd

$ vault token lookup s.bOKeoaeTG8WPKb2Wx2CvstdC
Key                            Value
---                            -----
identity_policies              [ergh]
policies                       [root]

What confused me is that I normally see [] or <nil> or n/a for empty fields. But looking at tcpdump, I can see the raw JSON returned is completely missing the identity_policies field if it’s unset. (Vault v1.9.2, by the way)



You can customize the attribute used to create the Alias (user_claim). I typically use email address as that’s unique enough and predictable. However, I also normally assign policies by group or Templated Policies. I’m assuming you’ve gone over the additional OIDC setup guide for Google? If not, you should take a look.

FWIW, it took me a few iterations to get to a good place with my config. I think the more you experiment with the settings things will make more sense and you’ll figure out a good path for your environment.

You can customize the attribute used to create the Alias (user_claim). I typically use email address as that’s unique enough and predictable

I’m aware of that. I’d prefer not to rely on the email claim from the IDP, given that it has the potential to change, and may not even be unique. I could perhaps add the email claim as custom_metadata on the entity alias, but retain the sub as the alias key.

My long-term aim is to prevent Vault from creating entities automatically when unknown OpenID accounts are presented (which requires a change to Vault). When that happens, I’d like to send the user out-of-band some sort of token that grants them the right to add an alias to an entity I already created for them - or at least to create a new entity.

Are you looking to manage users within your organization within Vault or are you looking at more of a self-service registration for people outside of your organization?

If it’s the former, perhaps setting up some kind of connection to Google to read the ID would work? If you use Terraform I think the Google Workspace provider might be useful. (This is essentially what I do for pulling in Azure group data to pre-create Identity Groups and Aliases)

However, if you’re looking for users outside your organization then I’d have to think about that a bit more.

It’s actually a bit of both. There’s a G-Suite managed domain, but there are also external individuals we need to allow to access with a generic Google account, so there will be two OpenID providers that the user can choose between at login time.

For your external users you might have to put together a registration process, but I think you could leverage Google’s People API to get their unique ID (resourceName on the Person object) based on a provided email address. Once the ID is acquired you could use that to pre-create the Entity Alias in Vault (assuming it’s the same number you’re after).

I’ve never used this API so I’m not sure it’s what you’d need, but hopefully opens up some options/ideas to help address your need.