/sys/locked-users

The /sys/locked-users endpoint is used to list and unlock locked users in Vault.

Please visit user lockout concepts page for more details about the feature.

List locked users

This endpoint lists the locked users information in Vault.

The response will include all child namespaces of the namespace in which the request was made. If some namespace has subsequently been deleted, its path will be listed as "deleted namespace :ID:." Deleted namespaces are reported only for queries in the root namespace because the information about the namespace path is unknown. The response will be returned in the decreasing order of locked user counts.

This endpoint was added in Vault 1.13.

Method	Path
`GET`	`/sys/locked-users`

Parameters

mount_accessor (string, optional) - Specifies the identifier of the auth mount entry to which the user belongs in the namespace in which the request was made. If no mount accessor is specified, the response will include locked users in all child namespaces of the namespace in which the request was made.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/locked-users

Sample response

{
   "request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
   "lease_id":"",
   "renewable":false,
   "lease_duration":0,
   "data":{
      "by_namespace":[
         {
            "namespace_id":"BzIex",
            "namespace_path":"ns1/",
            "counts": 3,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_79e2fe02",
                  "counts":3,
                  "alias_identifiers":[
                      {"user3"},
                      {"user4"},
                      {"user5"},
                  ]
               },
            ]
         },
         {
            "namespace_id":"root",
            "namespace_path":"",
            "counts":2,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_837f35fc",
                  "counts":2,
                  "alias_identifiers":[
                      {"user1"},
                      {"user2"}
                  ]
               },
            ]
         },
          {
            "namespace_id":"v1lb9",
            "namespace_path":"ns1/ns2/",
            "counts":1,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_af8d1d32",
                  "counts":1,
                  "alias_identifiers":[
                      {"user6"}
                  ]
               },
            ]
         }
      ],
      "total":6
   },
   "wrap_info":null,
   "warnings":null,
   "auth":null
}

For deleted namespaces, the response will look like:

{
   "request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
   "lease_id":"",
   "renewable":false,
   "lease_duration":0,
   "data":{
      "by_namespace":[
         {
            "namespace_id":"BzIex",
            "namespace_path":"ns1/",
            "counts": 3,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_79e2fe02",
                  "counts":3,
                  "alias_identifiers":[
                      {"user3"},
                      {"user4"},
                      {"user5"},
                  ]
               },
            ]
         },
         {
            "namespace_id":"root",
            "namespace_path":"",
            "counts":2,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_837f35fc",
                  "counts":2,
                  "alias_identifiers":[
                      {"user1"},
                      {"user2"}
                  ]
               },
            ]
         },
          {
            "namespace_id":"v1lb9",
            "namespace_path":"deleted namespace v1lb9",
            "counts":1,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_af8d1d32",
                  "counts":1,
                  "alias_identifiers":[
                      {"user6"}
                  ]
               },
            ]
         }
      ],
      "total":6
   },
   "wrap_info":null,
   "warnings":null,
   "auth":null
}

Sample request with mount accessor

Sample payload

{
  "mount_accessor": "auth_userpass_af8d1d32"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --data @payload.json \
    --request GET \
    http://127.0.0.1:8200/v1/sys/locked-users

Unlock user

This endpoint unlocks a locked user with provided mount_accessor and alias_identifier in namespace in which the request was made if locked. This command is idempotent, meaning it succeeds even if user with the given mount_accessor and alias_identifier is not locked.

This endpoint was added in Vault 1.13.

Method	Path
`POST`	`/sys/locked-users/:mount_accessor/unlock/:alias-identifier`

Parameters

mount_accessor (string, required) - Specifies the identifier of the auth mount entry to which the user belongs
alias_identifier (string, required) - It is the name of the alias (user). 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 an approle auth method, the name should be a valid RoleID. If the alias belongs to an ldap auth method, the name should be a valid username.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/locked-users/auth_userpass_af8d1d32/unlock/bsmith