luxolus/open-consul
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-consul/website/source/api/agent/connect.html.md
Matt Keeler baa89c7c65
Intentions ACL enforcement updates (#7028) 
* Renamed structs.IntentionWildcard to structs.WildcardSpecifier

* Refactor ACL Config

Get rid of remnants of enterprise only renaming.

Add a WildcardName field for specifying what string should be used to indicate a wildcard.

* Add wildcard support in the ACL package

For read operations they can call anyAllowed to determine if any read access to the given resource would be granted.

For write operations they can call allAllowed to ensure that write access is granted to everything.

* Make v1/agent/connect/authorize namespace aware

* Update intention ACL enforcement

This also changes how intention:read is granted. Before the Intention.List RPC would allow viewing an intention if the token had intention:read on the destination. However Intention.Match allowed viewing if access was allowed for either the source or dest side. Now Intention.List and Intention.Get fall in line with Intention.Matches previous behavior.

Due to this being done a few different places ACL enforcement for a singular intention is now done with the CanRead and CanWrite methods on the intention itself.

* Refactor Intention.Apply to make things easier to follow.
2020-01-13 15:51:40 -05:00

10 KiB
Raw Blame History

layout page_title sidebar_current description
api Connect - Agent - HTTP API api-agent-connect The /agent/connect endpoints interact with Connect with agent-local operations.

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

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. This is used to check against revocation lists.

  • Namespace (string: "") - (Enterprise Only) 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 at all, 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"
}

Sample Request

$ 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)"
}

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

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

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

  • Service (string: <required>) - The name of the service for the leaf certificate. This is specified in the URL. The service does not need to exist in the catalog, but the proper ACL permissions must be available.

Sample Request

$ 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",
  "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.