entity-alias

Create an entity alias

This endpoint creates a new alias for an entity.

Parameters

• name (string: <required>) - Name of the alias. Name should be the identifier of the client in the authentication source. For example, if the alias belongs to userpass backend, the name should be a valid username within userpass auth method. If the alias belongs to GitHub, it should be the GitHub username. If the alias belongs to an approle auth method, the name should be a valid RoleID.

• id (string: <optional>) - ID of the entity alias. If set, updates the corresponding entity alias.

• canonical_id (string: <required>) - Entity ID to which this alias belongs to.

• mount_accessor (string: <required>) - Accessor of the mount to which the alias should belong to. You can omit mount_accessor during creation when you set profile_name, config_id, or issuer. If you omit mount_accessor, Vault automatically generates a synthetic value for aliases bound to an OAuth resource-server configuration in the format oauth-resource-server_<namespace_id>_<config_id>, where <config_id> is the UUID of the matching configuration. You may also specify the mount accessor in the format oauth-resource-server_<namespace_id>_<config_id> or oauth-resource-server_<namespace_path>_<config_id>. When mount_accessor names an OAuth resource-server configuration and you also set issuer, the issuer must match the issuer of the named configuration. Vault 2.2.0 and later reject the request when the two differ.

• profile_name (string: "")

  Enterprise
  - Requires Vault 2.2.0 or later. Name of the OAuth resource server profile that backs the alias. Set profile_name together with external_id, and omit mount_accessor, to have Vault resolve the profile and derive the mount accessor and issuer from it. You can set profile_name only when you create an alias. Refer to Reference an OAuth resource server profile for the resolution rules.

• config_id (string: "")

  Enterprise
  - Requires Vault 2.2.0 or later. Config ID of the OAuth resource server profile that backs the alias. Behaves the same way as profile_name, but identifies the profile by the ID Vault assigned it instead of the name you chose. You can set config_id only when you create an alias.

• custom_metadata (map<string|string>: <optional>) - A map of arbitrary string to string valued user-provided metadata meant to describe the alias.

• issuer (string: "") - Issuer URL of the external identity provider bound to the alias. You cannot change issuer after creation. Setting mount_accessor is optional when you set issuer. When you set profile_name or config_id, Vault derives the issuer from the referenced profile, so you can omit issuer.

• external_id (string: "") - Subject identifier for the alias from the external identity provider. The ID must be unique with issuer within a namespace. You cannot change external_id after creation.

Reference an OAuth resource server profile

Enterprise

Aliases backed by an OAuth resource server profile use a synthetic mount accessor that encodes the namespace ID and the profile config_id. Rather than assemble that accessor, name the profile with profile_name or config_id and let Vault resolve it. Refer to the sample payload for an example.

Vault applies the following rules when you reference a profile:

• Vault resolves the profile in the request namespace. A profile in another namespace does not resolve. Vault returns an error that names the reference that failed.
• external_id is required. A profile reference tells Vault which profile backs the alias. The external ID identifies the principal within that profile.
• Vault derives the issuer from the profile. If you also set issuer, it must match the issuer_id of the referenced profile.
• Profile references are mutually exclusive. Set profile_name, config_id, or mount_accessor, but never more than one. Vault rejects the request even when the values identify the same profile.
• Profile references apply only at creation. Vault rejects profile_name and config_id when you update an existing alias, including through identity/entity-alias/id/:id, because an alias keeps the mount accessor it was created with.
• Vault copies the locality of the profile. Referencing a profile created with local=true produces a local alias.

Sample payload

{
  "name": "testuser",
  "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
  "mount_accessor": "auth_userpass_e50b1a44",
  "custom_metadata": {
    "contact_email": "james_updated@example.com"
  }
}

Sample payload (OAuth resource-server alias)

{
  "name": "svc-agent",
  "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
  "issuer": "https://idp.example.com",
  "external_id": "svc-agent@example.com"
}

Sample payload (OAuth resource-server profile reference)

{
  "name": "svc-agent",
  "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
  "profile_name": "agent-profile",
  "external_id": "svc-agent@example.com"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/entity-alias

Sample response

{
  "data": {
    "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
    "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31"
  }
}

Read entity alias by ID

This endpoint queries the entity alias by its identifier.

Parameters

• id (string: <required>) – Identifier of entity alias.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31

Sample response

{
  "data": {
    "creation_time": "2017-07-25T21:41:09.820717636Z",
    "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
    "custom_metadata": {
      "contact_email":"james@example.com"
    },
    "external_id": "",
    "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31",
    "issuer": "",
    "last_update_time": "2017-07-25T21:41:09.820717636Z",
    "local": false,
    "metadata": {
      "group": "san_francisco",
      "region": "west"
    },
    "mount_accessor": "auth_userpass_e50b1a44",
    "mount_path": "userpass/",
    "mount_type": "userpass",
    "name": "testuser"
  }
}

Update entity alias by ID

This endpoint is used to update an existing entity alias.

Parameters

• id (string: <required>) – Identifier of the entity alias.

• name (string: "") - Name of the alias. Name should be the identifier of the client in the authentication source. For example, if the alias belongs to userpass backend, the name should be a valid username within userpass backend. If alias belongs to GitHub, it should be the GitHub username.

• canonical_id (string: "") - Entity ID to which this alias belongs to.

• mount_accessor (string: "") - Accessor of the mount to which the alias should belong to.

• custom_metadata (map<string|string>: <optional>) - A map of arbitrary string to string valued user-provided metadata meant to describe the alias.

• issuer (string: "") - Issuer URL bound to the alias. The provided issuer must match the existing issuer value for the alias.

• external_id (string: "") - Subject identifier bound to the alias. The provided ID must match the existing external_id value for the alias.

Sample payload

{
  "name": "testuser",
  "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
  "mount_accessor": "auth_userpass_e50b1a44",
   "custom_metadata": {
    "contact_email": "james@example.com"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31

Sample response

{
  "data": {
    "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3",
    "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31"
  }
}

Delete entity alias by ID

This endpoint deletes an alias from its corresponding entity.

Parameters

• id (string: <required>) – Identifier of the entity alias.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31

List entity aliases by ID

The list by ID endpoint returns the available entity aliases and key data by their identifiers.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/entity-alias/id

Sample response

{
    "data": {
        "key_info": {
            "35405f3c-884a-a3ff-4176-bac57f220811": {
                "canonical_id": "0c34f097-6313-9597-3b22-91e34072ad28",
                "custom_metadata": null,
                "local": false,
                "mount_accessor": "auth_jwt_e47c5220",
                "mount_path": "auth/tfc_jwt/",
                "mount_type": "jwt",
                "name": "app-alias-1"
            },
            "4065d8c7-4fa6-db9d-e190-f9644c09638a": {
                "canonical_id": "21c6f2bf-b9b0-db44-242f-18bf76cb9ff0",
                "custom_metadata": null,
                "local": false,
                "mount_accessor": "auth_ns_token_79c4d932",
                "mount_path": "auth/token/",
                "mount_type": "ns_token",
                "name": "app-alias-2"
            }
        },
        "keys": [
            "35405f3c-884a-a3ff-4176-bac57f220811",
            "4065d8c7-4fa6-db9d-e190-f9644c09638a"
        ]
    }
}