mirror of https://github.com/hashicorp/consul
521 lines
18 KiB
Markdown
521 lines
18 KiB
Markdown
---
|
|
layout: api
|
|
page_title: ACLs - HTTP API
|
|
description: The /acl endpoints manage the Consul's ACL system.
|
|
---
|
|
|
|
# ACL HTTP API
|
|
|
|
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls) and [check ACL replication status](#check-acl-replication). There are additional pages for managing [tokens](/consul/api-docs/acl/tokens) and [policies](/consul/api-docs/acl/policies) with the `/acl` endpoints.
|
|
|
|
For more information on how to setup ACLs, refer to the following resources:
|
|
|
|
- [Access control list (ACL) overview](/consul/docs/security/acl)
|
|
- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
|
|
|
|
## 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`](/consul/docs/agent/config/config-files#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.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------- | ------------------ |
|
|
| `PUT` | `/acl/bootstrap` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `none` |
|
|
|
|
The corresponding CLI command is [`consul acl bootstrap`](/consul/commands/acl/bootstrap).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request PUT \
|
|
http://127.0.0.1:8500/v1/acl/bootstrap
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
|
|
```json
|
|
{
|
|
"BootstrapSecret": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a"
|
|
}
|
|
```
|
|
|
|
```shell-session
|
|
$ 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](/consul/tutorials/security/access-control-setup-production) 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](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters)
|
|
for more details.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------ | ------------------ |
|
|
| `GET` | `/acl/replication` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `consistent` | `none` | `none` |
|
|
|
|
### Query Parameters
|
|
|
|
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
the datacenter of the agent being queried.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request GET \
|
|
http://127.0.0.1:8500/v1/acl/replication
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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`](/consul/docs/agent/config/config-files#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`](/consul/api-docs/acl/policies#list-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`](/consul/api-docs/acl/tokens#list-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](/consul/docs/security/acl/auth-methods) bearer token for a newly-created
|
|
Consul ACL token.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------ | ------------------ |
|
|
| `POST` | `/acl/login` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `none` |
|
|
|
|
-> **Note** - To use the login process to create tokens in any connected
|
|
secondary datacenter, [ACL
|
|
replication](/consul/docs/agent/config/config-files#acl_enable_token_replication) must be
|
|
enabled. Login requires the ability to create local tokens which is restricted
|
|
to the primary datacenter and any secondary datacenters with ACL token
|
|
replication enabled.
|
|
|
|
The corresponding CLI command is [`consul login`](/consul/commands/login).
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### 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)](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens).
|
|
|
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
|
|
linked to the token. Can be useful to track origins.
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"AuthMethod": "minikube",
|
|
"BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/login
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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](#login-to-auth-method). The token deleted is specified
|
|
with the `X-Consul-Token` header or the `token` query parameter.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------- | ------------------ |
|
|
| `POST` | `/acl/logout` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `none` |
|
|
|
|
-> **Note** - This endpoint requires no specific privileges as it is just
|
|
deleting a token for which you already must possess its secret.
|
|
|
|
The corresponding CLI command is [`consul logout`](/consul/commands/logout).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ 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
|
|
|
|
<EnterpriseAlert>
|
|
{' '}
|
|
This is an enterprise only endpoint.
|
|
</EnterpriseAlert>
|
|
|
|
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](/consul/docs/security/acl/auth-methods/oidc).
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------- | ------------------ |
|
|
| `POST` | `/acl/oidc/auth-url` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `none` |
|
|
|
|
-> **Note** - To use the login process to create tokens in any connected
|
|
secondary datacenter, [ACL
|
|
replication](/consul/docs/agent/config/config-files#acl_enable_token_replication) must be
|
|
enabled. Login requires the ability to create local tokens which is restricted
|
|
to the primary datacenter and any secondary datacenters with ACL token
|
|
replication enabled.
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for
|
|
login. This must be of type [`oidc`](/consul/docs/security/acl/auth-methods/oidc).
|
|
|
|
- `RedirectURI` `(string: <required>)` - See [Redirect
|
|
URIs](/consul/docs/security/acl/auth-methods/oidc#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: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).
|
|
|
|
This must match the namespace provided on the [OIDC Callback](#oidc-callback).
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"AuthMethod": "auth0",
|
|
"RedirectURI": "http://localhost:8550/oidc/callback"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/oidc/auth-url
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AuthURL": "https://myprovider.com/authorize?client_id=..."
|
|
}
|
|
```
|
|
|
|
## OIDC Callback
|
|
|
|
<EnterpriseAlert>
|
|
{' '}
|
|
This is an enterprise only endpoint.
|
|
</EnterpriseAlert>
|
|
|
|
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.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------- | ------------------ |
|
|
| `POST` | `/acl/oidc/callback` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/consul/api-docs/features/blocking),
|
|
[consistency modes](/consul/api-docs/features/consistency),
|
|
[agent caching](/consul/api-docs/features/caching), and
|
|
[required ACLs](/consul/api-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `none` |
|
|
|
|
-> **Note** - To use the login process to create tokens in any connected
|
|
secondary datacenter, [ACL
|
|
replication](/consul/docs/agent/config/config-files#acl_enable_token_replication) must be
|
|
enabled. Login requires the ability to create local tokens which is restricted
|
|
to the primary datacenter and any secondary datacenters with ACL token
|
|
replication enabled.
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for
|
|
login. This must be of type [`oidc`](/consul/docs/security/acl/auth-methods/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: "")` <EnterpriseAlert inline /> - 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](#methods-to-specify-namespace).
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"AuthMethod": "auth0",
|
|
"State": "aa3f1903c2f5eac666e6f92e804cf7fc0ff1d15b",
|
|
"Code": "dn0u9oM9WegYBEnp"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/oidc/callback
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"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",
|
|
"Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
|
|
"CreateIndex": 36,
|
|
"ModifyIndex": 36
|
|
}
|
|
```
|
|
|
|
## Methods to specify namespace <EnterpriseAlert inline />
|
|
|
|
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
|
|
1. ns` query parameter
|
|
1. X-Consul-Namespace` request header
|
|
1. Namespace is inherited from the namespace of the request's ACL token (if any)
|
|
1. The `default` namespace
|