Vault
HomeDocumentationTutorialsTry Cloud!
  • Vault
  • Documentation
    • What is Vault?
    • Use Cases
    • Setup
      • Install
      • Configuration
    • Get Started
      • Starting the server
      • Your first secret
      • Deploying Vault on VMs with Let's encrypt! TLS certs
    • Concepts
      • Operations
        • Seal/Unseal
        • "Dev" server mode
        • Namespace lock and unlock
        • Lease, renew, and revoke
        • Lease Explosions
        • Mount migration
        • Client count
        • Resource quotas
        • Response wrapping
      • Authentication
        • Identity
        • Tokens
        • OIDC provider
        • Username templating
        • Passwordless
      • Secrets
      • Storage
        • Integrated storage
        • High availability mode (HA)
        • Recovery mode
      • Policies
  • Tutorials
    • CLI
      • Operations
        • Deploy Vault
        • Using the HTTP API
        • Unseal/Seal
      • Authentication
        • Token
        • GitHub authentication
        • Username/Password
        • TLS Client Certificates
        • SSH Keys
        • AWS, Azure, GCP and external auth methods
          • Azure
          • AWS
          • GCP
          • Github
          • Terraform
      • Secrets
        • Secrets engines
        • Built-in help
      • Access Control
        • Policies
    • UI
      • Authentication
        • Username/Password
        • Passwordless
      • Operations
        • Unseal / Seal
        • API Explorer
      • Secrets
        • Secrets engines
      • Access Control
        • Policies
    • Use Cases
      • Namespaces
      • MongoDB admin password
      • VM Disk Encryption Keys
      • VM SSH Keys
      • Kubernetes Configuration
      • GitHub Actions
      • Dynamic credentials for cloud providers
        • AWS
        • Azure
        • GCP
  • CLI
    • agent
    • audit
    • auth
    • debug
    • delete
    • events
    • kv
    • lease
    • license
    • list
    • login
    • monitor
    • namespace
    • operator
    • patch
    • path-help
    • pki
    • plugin
    • policy
    • print
    • proxy
    • read
    • secrets
    • server
    • ssh
    • status
    • token
    • transit
    • unwrap
    • version
    • version-history
    • write
  • API
    • Secrets engines
      • AliCloud secrets engine (API)
      • AWS secrets engine (API)
      • Azure secrets engine (API)
      • Cubbyhole secrets engine (API)
      • Database
        • Cassandra database plugin HTTP API
        • Elasticsearch database plugin HTTP API
        • Influxdb database plugin HTTP API
        • MongoDB database plugin HTTP API
        • MSSQL database plugin HTTP API
        • MySQL/MariaDB database plugin HTTP API
        • Oracle database plugin HTTP API
        • PostgreSQL database plugin HTTP API
        • Redis database plugin HTTP API
        • Redis ElastiCache database plugin HTTP API
        • Redshift database plugin HTTP API
        • Snowflake database plugin HTTP API
      • Google Cloud secrets engine (API)
      • Google Cloud KMS secrets engine (API)
      • Identity
        • entity
        • entity-alias
        • group
        • group-alias
        • tokens
        • lookup
        • oidc-provider
        • MFA
          • duo
          • okta
          • pingid
          • totp
          • login-enforcement
      • KV secrets engine (API)
      • Buckypaper secrets engine
      • Kubernetes secrets engine (API)
      • Nomad secrets engine (API)
      • LDAP secrets engine (API)
      • PKI secrets engine (API)
      • RabbitMQ secrets engine (API)
      • SSH secrets engine (API)
      • TOTP secrets engine (API)
      • Transit secrets engine (API)
    • Auth engines
      • AliCloud auth method (API)
      • AppRole auth method (API)
      • AWS auth method (API)
      • Azure auth method (API)
      • Pivotal Cloud Foundry (CF) auth method (API)
      • GitHub auth method (API)
      • Google Cloud auth method (API)
      • JWT/OIDC auth method (API)
      • Kerberos auth method (API)
      • Kubernetes auth method (API)
      • LDAP auth method (API)
      • OCI auth method (API)
      • Okta auth method (API)
      • Passwordless auth method (API)
      • RADIUS auth method (API)
      • TLS certificate auth method (API)
      • Token auth method (API)
      • Userpass auth method (HTTP API)
    • Service engines
      • Licence Manager
    • System backend
      • /sys/audit
      • /sys/audit-hash
      • /sys/auth
      • /sys/capabilities
      • /sys/capabilities-accessor
      • /sys/capabilities-self
      • /sys/config/auditing/request-headers
      • /sys/config/control-group
      • /sys/config/cors
      • /sys/config/reload
      • /sys/config/state
      • /sys/config/ui
      • /sys/decode-token
      • /sys/experiments
      • /sys/generate-recovery-token
      • /sys/generate-root
      • /sys/health
      • /sys/host-info
      • /sys/in-flight-req
      • /sys/init
      • /sys/internal/counters
      • /sys/internal/inspect
        • /sys/internal/inspect/router
      • /sys/internal/specs/openapi
      • /sys/internal/ui/feature-flags
      • /sys/internal/ui/mounts
      • /sys/internal/ui/namespaces
      • /sys/internal/ui/resultant-acl
      • /sys/key-status
      • /sys/ha-status
      • /sys/leader
      • /sys/leases
      • /sys/license/status
      • /sys/locked-users
      • /sys/loggers
      • /sys/metrics
      • /sys/monitor
      • /sys/mounts
      • /sys/namespaces
      • /sys/plugins/reload/backend
      • /sys/plugins/catalog
      • /sys/plugins/runtimes/catalog
      • /sys/policy
      • /sys/policies/
      • /sys/policies/password/
      • /sys/pprof
      • /sys/quotas/config
      • /sys/quotas/rate-limit
      • /sys/quotas/lease-count
      • /sys/raw
      • /sys/rekey
      • /sys/rekey-recovery-key
      • /sys/remount
      • /sys/rotate
      • /sys/rotate/config
      • /sys/seal
      • /sys/seal-status
      • /sys/seal-backend-status
      • /sys/step-down
      • /sys/storage
        • /sys/storage/raft
        • /sys/storage/raft/autopilot
      • /sys/tools
      • /sys/unseal
      • /sys/version-history
      • /sys/wrapping/lookup
      • /sys/wrapping/rewrap
      • /sys/wrapping/unwrap
      • /sys/wrapping/wrap
  • Resources
    • Blog
    • GitHub
    • Youtube
    • CCx101
Powered by GitBook
On this page
  • Create an entity alias
  • Read entity alias by ID
  • Update entity alias by ID
  • Delete entity alias by ID
  • List entity aliases by ID
  1. API
  2. Secrets engines
  3. Identity

entity-alias

NOTE: Be careful in granting permissions to non-readonly identity endpoints. If a user can modify an entity, they can grant it additional privileges through policies. If a user can modify an alias they can login with, they can bind it to an entity with higher privileges.

Create an entity alias

IMPORTANT NOTE: Prior to creating any alias it is important to consider the cardinality of the alias' name, since there are potential security issues to be aware of. The main one revolves around alias reuse. It is possible for multiple authenticated entities to be bound to the same alias, and therefore gain access to all of its privileges. It is recommended, whenever possible, to create a unique alias for each entity. This is especially true in the case of machine generated entities.

This endpoint creates a new alias for an entity.

Method
Path

POST

/identity/entity-alias

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.

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

Method
Path

GET

/identity/entity-alias/id/:id

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"
    },
    "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31",
    "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.

Method
Path

POST

/identity/entity-alias/id/:id

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.

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.

Method
Path

DELETE

/identity/entity-alias/id/:id

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.

Method
Path

LIST

/identity/entity-alias/id

GET

/identity/entity-alias/id?list=true

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"
        ]
    }
}
PreviousentityNextgroup

Last updated 1 year ago