ACL HTTP API

The /acl endpoints are used to manage ACL tokens and policies in Consul, bootstrap the ACL system and check ACL replication status. There are additional pages for managing tokens and policies with the /acl endpoints.

For more information on how to setup ACLs, refer to the following resources:

• Access control list (ACL) overview
• ACL tutorial

Bootstrap ACLs

This endpoint does a special one-time bootstrap of the ACL system, making the first management token if the acl.tokens.initial_management configuration entry is not specified in the Consul server configuration and if the cluster has not been bootstrapped previously. An operator created token can be provided in the body of the request to bootstrap the cluster if required. The provided token should be presented in a UUID format.

This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's configuration files.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul acl bootstrap.

Sample Request

$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/acl/bootstrap

Sample Response

{
  "AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3",
  "SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
  "Description": "Bootstrap Token (Global Management)",
  "Policies": [
    {
      "ID": "00000000-0000-0000-0000-000000000001",
      "Name": "global-management"
    }
  ],
  "Local": false,
  "CreateTime": "2018-10-24T10:34:20.843397-04:00",
  "Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
  "CreateIndex": 12,
  "ModifyIndex": 12
}

Sample Request with provided token

{
  "BootstrapSecret": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a"
}

$ curl \
    --request PUT \
    --data @root-token.json \
    http://127.0.0.1:8500/v1/acl/bootstrap

You can detect if something has interfered with the ACL bootstrapping process by checking the response code. A 200 response means that the bootstrap was a success, and a 403 means that the cluster has already been bootstrapped, at which point you should consider the cluster in a potentially compromised state.

The returned token will have unrestricted privileges to manage all details of the system. It can then be used to further configure the ACL system. Please check the ACL tutorial for more details.

Check ACL Replication

This endpoint returns the status of the ACL replication processes in the datacenter. This is intended to be used by operators or by automation checking to discover the health of ACL replication.

Please check the ACL Replication tutorial for more details.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Query Parameters

• dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

Sample Request

$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/acl/replication

Sample Response

{
  "Enabled": true,
  "Running": true,
  "SourceDatacenter": "dc1",
  "ReplicationType": "tokens",
  "ReplicatedIndex": 1976,
  "ReplicatedTokenIndex": 2018,
  "LastSuccess": "2018-11-03T06:28:58Z",
  "LastError": "2016-11-03T06:28:28Z",
  "LastErrorMessage": "failed to retrieve ACL policy updates: RPC rate limit exceeded"
}

• Enabled - Reports whether ACL replication is enabled for the datacenter.

• Running - Reports whether the ACL replication process is running. The process may take approximately 60 seconds to begin running after a leader election occurs.

• SourceDatacenter - The authoritative ACL datacenter that ACLs are being replicated from and will match the primary_datacenter configuration.

• ReplicationType - The type of replication that is currently in use.

  • policies - ACL replication is only replicating policies as token replication is disabled.

  • tokens - ACL replication is replicating both policies and tokens.

• ReplicatedIndex - The last index that was successfully replicated. Which data the replicated index refers to depends on the replication type. When in either tokens or policies mode, this index can be compared with the value of the X-Consul-Index header returned by the /v1/acl/policies endpoint to determine if the policy replication process has gotten all available ACL policies. Note that ACL replication is rate limited so the indexes may lag behind the primary datacenter.

• ReplicatedTokenIndex - The last token index that was successfully replicated. This index can be compared with the value of the X-Consul-Index header returned by the /v1/acl/tokens endpoint to determine if the replication process has gotten all available ACL tokens. Note that ACL replication is rate limited so the indexes may lag behind the primary datacenter.

• LastSuccess - The UTC time of the last successful sync operation. Since ACL replication is done with a blocking query, this may not update for up to 5 minutes if there have been no ACL changes to replicate. A zero value of "0001-01-01T00:00:00Z" will be present if no sync has been successful.

• LastError - The UTC time of the last error encountered during a sync operation. If this time is later than LastSuccess, you can assume the replication process is not in a good state. A zero value of "0001-01-01T00:00:00Z" will be present if no sync has resulted in an error.

• LastErrorMessage - The last error message produced at the time of LastError. An empty string indicates that no sync has resulted in an error.

Login to Auth Method

This endpoint was added in Consul 1.5.0 and is used to exchange an auth method bearer token for a newly-created Consul ACL token.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul login.

Query Parameters

• ns (string: "")
  Enterprise
  - Specifies the namespace of the auth method you use to login. You can also specify the namespace through other methods.

JSON Request Body Schema

• AuthMethod (string: <required>) - The name of the auth method to use for login.

• BearerToken (string: <required>) - The bearer token to present to the auth method during login for authentication purposes. For the Kubernetes auth method this is a Service Account Token (JWT).

• Meta (map<string|string>: nil) - Specifies arbitrary KV metadata linked to the token. Can be useful to track origins.

• Namespace (string: "")

  Enterprise
  - Specifies the namespace of the auth method you use to login. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

Sample Payload

{
  "AuthMethod": "minikube",
  "BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/login

Sample Response

{
  "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
  "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
  "Description": "token created via login",
  "Roles": [
    {
      "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
      "Name": "demo"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "example"
    }
  ],
  "Local": true,
  "AuthMethod": "minikube",
  "CreateTime": "2019-04-29T10:08:08.404370762-05:00",
  "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
  "CreateIndex": 36,
  "ModifyIndex": 36
}

Logout from Auth Method

This endpoint was added in Consul 1.5.0 and is used to destroy a token created via the login endpoint. The token deleted is specified with the X-Consul-Token header or the token query parameter.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

The corresponding CLI command is consul logout.

This endpoint only destroys the Consul token. The OIDC callback endpoint returns an IDPLogoutURL value. To also end the user's session at the OIDC identity provider, open that URL in the user's browser.

Sample Request

$ curl \
    --header "X-Consul-Token: b78d37c7-0ca7-5f4d-99ee-6d9975ce4586" \
    --request POST \
    http://127.0.0.1:8500/v1/acl/logout

OIDC Authorization URL Request

This endpoint was added in Consul 1.8.0 and is used to obtain an authorization URL from Consul to start an OIDC login flow.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Query Parameters

• ns (string: "")
  Enterprise
  - Specifies the namespace of the auth method you use to login. You can also specify the namespace through other methods.

JSON Request Body Schema

• AuthMethod (string: <required>) - The name of the auth method to use for login. This must be of type oidc.

• RedirectURI (string: <required>) - See Redirect URIs for more information.

• ClientNonce (string: "") - Optional client-provided nonce that must match during callback, if present.

• Meta (map<string|string>: nil) - Specifies arbitrary KV metadata linked to the token. Can be useful to track origins.

• Namespace (string: "")

  Enterprise
  - Specifies the namespace of the auth method you use to login. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

  This must match the namespace provided on the OIDC Callback.

Sample Payload

{
  "AuthMethod": "auth0",
  "RedirectURI": "http://localhost:8550/oidc/callback"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/oidc/auth-url

Sample Response

{
  "AuthURL": "https://myprovider.com/authorize?client_id=..."
}

OIDC Callback

This endpoint was added in Consul 1.8.0 and is used to exchange an OIDC authorization code for an OIDC ID Token. The ID token will in turn be exchanged for a newly-created Consul ACL token.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Query Parameters

• ns (string: "")
  Enterprise
  - Specifies the namespace of the auth method you use to login. You can also specify the namespace through other methods.

JSON Request Body Schema

• AuthMethod (string: <required>) - The name of the auth method to use for login. This must be of type oidc.

• State (string: <required>) - Opaque state ID that is part of the Authorization URL and will be included in the redirect following successful authentication on the provider.

• Code (string: <required>) - Provider-generated authorization code that Consul will exchange for an ID token.

• ClientNonce (string: "") - Optional client-provided nonce that must match the one provided in the auth url request, if present.

• Meta (map<string|string>: nil) - Specifies arbitrary KV metadata linked to the token. Can be useful to track origins.

• Namespace (string: "")

  Enterprise
  - Specifies the namespace of the auth method you use to login. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

Sample Payload

{
  "AuthMethod": "auth0",
  "State": "aa3f1903c2f5eac666e6f92e804cf7fc0ff1d15b",
  "Code": "dn0u9oM9WegYBEnp"
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/oidc/callback

Sample Response

If identity provider logout is available for the auth method, the response includes IDPLogoutURL, the identity provider logout URL to open in the user's browser when the user logs out. Refer to OIDC logout for details. Consul returns this field only in this response and does not store it.

{
  "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
  "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
  "Description": "token created via OIDC login",
  "Roles": [
    {
      "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
      "Name": "demo"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "example"
    }
  ],
  "Local": true,
  "AuthMethod": "auth0",
  "CreateTime": "2019-04-29T10:08:08.404370762-05:00",
  "IDPLogoutURL": "https://idp.example.com/oidc/logout?id_token_hint=ID_TOKEN&post_logout_redirect_uri=https%3A%2F%2Fconsul.example.com%2Fui%2F",
  "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
  "CreateIndex": 36,
  "ModifyIndex": 36
}

Methods to specify namespace

Enterprise

Some ACL endpoints support several methods for specifying the namespace of the resource with the following order of precedence:

1. Namespace` field of the JSON request body - only applies to endpoints that accept an JSON request body
2. ns` query parameter
3. X-Consul-Namespace` request header
4. Namespace is inherited from the namespace of the request's ACL token (if any)
5. The default namespace