»Connect - Agent HTTP API
The /agent/connect endpoints interact with Connect
with agent-local operations.
These endpoints may mirror the non-agent Connect endpoints
in some cases. Almost all agent-local Connect endpoints perform local caching
to optimize performance of Connect without having to make requests to the server.
»Authorize
Note: This endpoint will always treat intentions with Permissions
defined as deny intentions during evaluation, as this endpoint is only suited
for networking layer 4 (e.g. TCP) integration.
For performance and reliability reasons it is desirable to implement intention
enforcement by listing intentions that match the
destination and representing
them in the native configuration of the proxy itself (such as RBAC for Envoy).
This endpoint tests whether a connection attempt is authorized between
two services. This is the primary API that must be implemented by
proxies or
native integrations
that wish to integrate with Connect. Prior to calling this API, it is expected
that the client TLS certificate has been properly verified against the
current CA roots.
The implementation of this API uses locally cached data
and doesn't require any request forwarding to a server. Therefore, the
response typically occurs in microseconds to impose minimal overhead on the
connection attempt.
| Method |
Path |
Produces |
POST |
/agent/connect/authorize |
application/json |
The table below shows this endpoint's support for
blocking queries,
consistency modes,
agent caching, and
required ACLs.
| Blocking Queries |
Consistency Modes |
Agent Caching |
ACL Required |
NO |
none |
background refresh |
service:write |
»Parameters
-
Target (string: <required>) - The name of the service that is being
requested.
-
ClientCertURI (string: <required>) - The unique identifier for the
requesting client. This is currently the URI SAN from the TLS client
certificate.
-
ClientCertSerial (string: <required>) - The colon-hex-encoded serial
number for the requesting client cert.
-
Namespace (string: "")
Enterprise
- Specifies the namespace of
the target service. If not provided in the JSON body, the value of
the ns URL query parameter or in the X-Consul-Namespace header will be used.
If not provided, the namespace will be inherited from the request's ACL
token or will default to the default namespace. Added in Consul 1.7.0.
»Sample Payload
{
"Target": "db",
"ClientCertURI": "spiffe://dc1-7e567ac2-551d-463f-8497-f78972856fc1.consul/ns/default/dc/dc1/svc/web",
"ClientCertSerial": "04:00:00:00:00:01:15:4b:5a:c3:94"
}
{ "Target": "db", "ClientCertURI": "spiffe://dc1-7e567ac2-551d-463f-8497-f78972856fc1.consul/ns/default/dc/dc1/svc/web", "ClientCertSerial": "04:00:00:00:00:01:15:4b:5a:c3:94"}
»Sample Request
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/connect/authorize
$ curl \ --request POST \ --data @payload.json \ http://127.0.0.1:8500/v1/agent/connect/authorize
»Sample Response
{
"Authorized": true,
"Reason": "Matched intention: web => db (allow)"
}
{ "Authorized": true, "Reason": "Matched intention: web => db (allow)"}
»Certificate Authority (CA) Roots
This endpoint returns the trusted certificate authority (CA) root certificates.
This is used by proxies or
native integrations to verify served client
or server certificates are valid.
This is equivalent to the non-Agent Connect endpoint,
but the response of this request is cached locally at the agent. This allows
for very fast response times and for fail open behavior if the server is
unavailable. This endpoint should be used by proxies and native integrations.
| Method |
Path |
Produces |
GET |
/agent/connect/ca/roots |
application/json |
The table below shows this endpoint's support for
blocking queries,
consistency modes,
agent caching, and
required ACLs.
| Blocking Queries |
Consistency Modes |
Agent Caching |
ACL Required |
YES |
all |
background refresh |
none |
»Sample Request
$ curl \
http://127.0.0.1:8500/v1/agent/connect/ca/roots
$ curl \ http://127.0.0.1:8500/v1/agent/connect/ca/roots
»Sample Response
{
"ActiveRootID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7",
"Roots": [
{
"ID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7",
"Name": "Consul CA Root Cert",
"SerialNumber": 7,
"SigningKeyID": "1f:91:ca:41:8f:ac:67:bf:59:c2:fa:4e:75:5c:d8:f0:55:de:be:75:b8:33:31:d5:24:b0:04:b3:e8:97:5b:7e",
"ExternalTrustDomain": "a1499528-fbf6-df7b-05e5-ae81e1873fc4",
"NotBefore": "2018-05-21T16:33:28Z",
"NotAfter": "2028-05-18T16:33:28Z",
"RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjExNjMzMjhaFw0yODA1MTgxNjMzMjhaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAER0qlxjnRcMEr\niSGlH7G7dYU7lzBEmLUSMZkyBbClmyV8+e8WANemjn+PLnCr40If9cmpr7RnC9Qk\nGTaLnLiF16OCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8xZjo5MTpjYTo0MTo4ZjphYzo2NzpiZjo1OTpjMjpmYTo0ZTo3\nNTo1YzpkODpmMDo1NTpkZTpiZTo3NTpiODozMzozMTpkNToyNDpiMDowNDpiMzpl\nODo5Nzo1Yjo3ZTBqBgNVHSMEYzBhgF8xZjo5MTpjYTo0MTo4ZjphYzo2NzpiZjo1\nOTpjMjpmYTo0ZTo3NTo1YzpkODpmMDo1NTpkZTpiZTo3NTpiODozMzozMTpkNToy\nNDpiMDowNDpiMzplODo5Nzo1Yjo3ZTA/BgNVHREEODA2hjRzcGlmZmU6Ly8xMjRk\nZjVhMC05ODIwLTc2YzMtOWFhOS02ZjYyMTY0YmExYzIuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgisxMjRkZjVhMC05ODIwLTc2YzMtOWFhOS02ZjYyMTY0YmExYzIu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIQDzkkI7R+0U12a+zq2EQhP/n2mHmta+\nfs2hBxWIELGwTAIgLdO7RRw+z9nnxCIA6kNl//mIQb+PGItespiHZKAz74Q=\n-----END CERTIFICATE-----\n",
"IntermediateCerts": null,
"Active": true,
"PrivateKeyType": "ec",
"PrivateKeyBits": 256,
"CreateIndex": 8,
"ModifyIndex": 8
}
]
}
{ "ActiveRootID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7", "Roots": [ { "ID": "15:bf:3a:7d:ff:ea:c1:8c:46:67:6c:db:b8:81:18:36:ad:e5:d0:c7", "Name": "Consul CA Root Cert", "SerialNumber": 7, "SigningKeyID": "1f:91:ca:41:8f:ac:67:bf:59:c2:fa:4e:75:5c:d8:f0:55:de:be:75:b8:33:31:d5:24:b0:04:b3:e8:97:5b:7e", "ExternalTrustDomain": "a1499528-fbf6-df7b-05e5-ae81e1873fc4", "NotBefore": "2018-05-21T16:33:28Z", "NotAfter": "2028-05-18T16:33:28Z", "RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjExNjMzMjhaFw0yODA1MTgxNjMzMjhaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAER0qlxjnRcMEr\niSGlH7G7dYU7lzBEmLUSMZkyBbClmyV8+e8WANemjn+PLnCr40If9cmpr7RnC9Qk\nGTaLnLiF16OCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8xZjo5MTpjYTo0MTo4ZjphYzo2NzpiZjo1OTpjMjpmYTo0ZTo3\nNTo1YzpkODpmMDo1NTpkZTpiZTo3NTpiODozMzozMTpkNToyNDpiMDowNDpiMzpl\nODo5Nzo1Yjo3ZTBqBgNVHSMEYzBhgF8xZjo5MTpjYTo0MTo4ZjphYzo2NzpiZjo1\nOTpjMjpmYTo0ZTo3NTo1YzpkODpmMDo1NTpkZTpiZTo3NTpiODozMzozMTpkNToy\nNDpiMDowNDpiMzplODo5Nzo1Yjo3ZTA/BgNVHREEODA2hjRzcGlmZmU6Ly8xMjRk\nZjVhMC05ODIwLTc2YzMtOWFhOS02ZjYyMTY0YmExYzIuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgisxMjRkZjVhMC05ODIwLTc2YzMtOWFhOS02ZjYyMTY0YmExYzIu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIQDzkkI7R+0U12a+zq2EQhP/n2mHmta+\nfs2hBxWIELGwTAIgLdO7RRw+z9nnxCIA6kNl//mIQb+PGItespiHZKAz74Q=\n-----END CERTIFICATE-----\n", "IntermediateCerts": null, "Active": true, "PrivateKeyType": "ec", "PrivateKeyBits": 256, "CreateIndex": 8, "ModifyIndex": 8 } ]}
»Service Leaf Certificate
This endpoint returns the leaf certificate representing a single service.
This certificate is used as a server certificate for accepting inbound
connections and is also used as the client certificate for establishing
outbound connections to other services.
The agent generates a CSR locally and calls the
CA sign API to sign it. The resulting certificate
is cached and returned by this API until it is near expiry or the root
certificates change.
This API supports blocking queries. The blocking query will block until
a new certificate is necessary because the existing certificate will expire
or the root certificate is being rotated. This blocking behavior allows
clients to efficiently wait for certificate rotations.
| Method |
Path |
Produces |
GET |
/agent/connect/ca/leaf/:service |
application/json |
The table below shows this endpoint's support for
blocking queries,
consistency modes,
agent caching, and
required ACLs.
| Blocking Queries |
Consistency Modes |
Agent Caching |
ACL Required |
YES |
all |
background refresh |
service:write |
»Parameters
»Sample Request
$ curl \
http://127.0.0.1:8500/v1/agent/connect/ca/leaf/web
$ curl \ http://127.0.0.1:8500/v1/agent/connect/ca/leaf/web
»Sample Response
{
"SerialNumber": "08",
"CertPEM": "-----BEGIN CERTIFICATE-----\nMIIChjCCAi2gAwIBAgIBCDAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjExNjMzMjhaFw0xODA1MjQxNjMzMjhaMA4xDDAKBgNVBAMT\nA3dlYjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJdLqRKd1SRycFOFceMHOBZK\nQW8HHO8jZ5C8dRswD+IwTd/otJPiaPrVzGOAi4MsaEUgDMemvN1jiywHt3II08mj\nggFyMIIBbjAOBgNVHQ8BAf8EBAMCA7gwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsG\nAQUFBwMBMAwGA1UdEwEB/wQCMAAwaAYDVR0OBGEEXzFmOjkxOmNhOjQxOjhmOmFj\nOjY3OmJmOjU5OmMyOmZhOjRlOjc1OjVjOmQ4OmYwOjU1OmRlOmJlOjc1OmI4OjMz\nOjMxOmQ1OjI0OmIwOjA0OmIzOmU4Ojk3OjViOjdlMGoGA1UdIwRjMGGAXzFmOjkx\nOmNhOjQxOjhmOmFjOjY3OmJmOjU5OmMyOmZhOjRlOjc1OjVjOmQ4OmYwOjU1OmRl\nOmJlOjc1OmI4OjMzOjMxOmQ1OjI0OmIwOjA0OmIzOmU4Ojk3OjViOjdlMFkGA1Ud\nEQRSMFCGTnNwaWZmZTovLzExMTExMTExLTIyMjItMzMzMy00NDQ0LTU1NTU1NTU1\nNTU1NS5jb25zdWwvbnMvZGVmYXVsdC9kYy9kYzEvc3ZjL3dlYjAKBggqhkjOPQQD\nAgNHADBEAiBS8kH3UERhBPHM/CQV/jXKLr0kReLqCdq1jZxc8Aq7hQIgFIus/ZX0\nOM/X3Yc1xb/qJiiEVzXcaz3oVFULOzrNAwk=\n-----END CERTIFICATE-----\n",
"PrivateKeyPEM": "-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIAOGglbwY8HdD3LFX6Bc94co2pzeFTto8ebWoML5E+QfoAoGCCqGSM49\nAwEHoUQDQgAEl0upEp3VJHJwU4Vx4wc4FkpBbwcc7yNnkLx1GzAP4jBN3+i0k+Jo\n+tXMY4CLgyxoRSAMx6a83WOLLAe3cgjTyQ==\n-----END EC PRIVATE KEY-----\n",
"Service": "web",
"ServiceURI": "spiffe://11111111-2222-3333-4444-555555555555.consul/ns/default/dc/dc1/svc/web",
"ValidAfter": "2018-05-21T16:33:28Z",
"ValidBefore": "2018-05-24T16:33:28Z",
"Namespace": "default",
"CreateIndex": 5,
"ModifyIndex": 5
}
{ "SerialNumber": "08", "CertPEM": "-----BEGIN CERTIFICATE-----\nMIIChjCCAi2gAwIBAgIBCDAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjExNjMzMjhaFw0xODA1MjQxNjMzMjhaMA4xDDAKBgNVBAMT\nA3dlYjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJdLqRKd1SRycFOFceMHOBZK\nQW8HHO8jZ5C8dRswD+IwTd/otJPiaPrVzGOAi4MsaEUgDMemvN1jiywHt3II08mj\nggFyMIIBbjAOBgNVHQ8BAf8EBAMCA7gwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsG\nAQUFBwMBMAwGA1UdEwEB/wQCMAAwaAYDVR0OBGEEXzFmOjkxOmNhOjQxOjhmOmFj\nOjY3OmJmOjU5OmMyOmZhOjRlOjc1OjVjOmQ4OmYwOjU1OmRlOmJlOjc1OmI4OjMz\nOjMxOmQ1OjI0OmIwOjA0OmIzOmU4Ojk3OjViOjdlMGoGA1UdIwRjMGGAXzFmOjkx\nOmNhOjQxOjhmOmFjOjY3OmJmOjU5OmMyOmZhOjRlOjc1OjVjOmQ4OmYwOjU1OmRl\nOmJlOjc1OmI4OjMzOjMxOmQ1OjI0OmIwOjA0OmIzOmU4Ojk3OjViOjdlMFkGA1Ud\nEQRSMFCGTnNwaWZmZTovLzExMTExMTExLTIyMjItMzMzMy00NDQ0LTU1NTU1NTU1\nNTU1NS5jb25zdWwvbnMvZGVmYXVsdC9kYy9kYzEvc3ZjL3dlYjAKBggqhkjOPQQD\nAgNHADBEAiBS8kH3UERhBPHM/CQV/jXKLr0kReLqCdq1jZxc8Aq7hQIgFIus/ZX0\nOM/X3Yc1xb/qJiiEVzXcaz3oVFULOzrNAwk=\n-----END CERTIFICATE-----\n", "PrivateKeyPEM": "-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIAOGglbwY8HdD3LFX6Bc94co2pzeFTto8ebWoML5E+QfoAoGCCqGSM49\nAwEHoUQDQgAEl0upEp3VJHJwU4Vx4wc4FkpBbwcc7yNnkLx1GzAP4jBN3+i0k+Jo\n+tXMY4CLgyxoRSAMx6a83WOLLAe3cgjTyQ==\n-----END EC PRIVATE KEY-----\n", "Service": "web", "ServiceURI": "spiffe://11111111-2222-3333-4444-555555555555.consul/ns/default/dc/dc1/svc/web", "ValidAfter": "2018-05-21T16:33:28Z", "ValidBefore": "2018-05-24T16:33:28Z", "Namespace": "default", "CreateIndex": 5, "ModifyIndex": 5}
-
SerialNumber string - Monotonically increasing 64-bit serial number
representing all certificates issued by this Consul cluster.
-
CertPEM (string) - The PEM-encoded certificate.
-
PrivateKeyPEM (string) - The PEM-encoded private key for this certificate.
-
Service (string) - The name of the service that this certificate identifies.
-
ServiceURI (string) - The URI SAN for this service.
-
ValidAfter (string) - The time after which the certificate is valid.
Used with ValidBefore this can determine the validity period of the certificate.
-
ValidBefore (string) - The time before which the certificate is valid.
Used with ValidAfter this can determine the validity period of the certificate.