»Certificate Authority (CA) - Connect HTTP API

The /connect/ca endpoints provide tools for interacting with Connect's Certificate Authority mechanism.

»List CA Root Certificates

This endpoint returns the current list of trusted CA root certificates in the cluster.

MethodPathProduces
GET/connect/ca/rootsapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenone

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/ca/roots

»Sample Response

{
  "ActiveRootID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
  "TrustDomain": "7f42f496-fbc7-8692-05ed-334aa5340c1e.consul",
  "Roots": [
    {
      "ID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
      "Name": "Consul CA Root Cert",
      "SerialNumber": 7,
      "SigningKeyID": "2d:09:5d:84:b9:89:4b:dd:e3:88:bb:9c:e2:b2:69:81:1f:4b:a6:fd:4d:df:ee:74:63:f3:74:55:ca:b0:b5:65",
      "ExternalTrustDomain": "a1499528-fbf6-df7b-05e5-ae81e1873fc4",
      "NotBefore": "2018-05-25T21:39:23Z",
      "NotAfter": "2028-05-22T21:39:23Z",
      "RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjUyMTM5MjNaFw0yODA1MjIyMTM5MjNaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEq4S32Pu0/VL4\nG75gvdyQuAhqMZFsfBRwD3pgvblgZMeJc9KDosxnPR+W34NXtMD/860NNVJIILln\n9lLhIjWPQqOCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDplMzo4ODpiYjo5Yzpl\nMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2MzpmMzo3NDo1NTpj\nYTpiMDpiNTo2NTBqBgNVHSMEYzBhgF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDpl\nMzo4ODpiYjo5YzplMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2\nMzpmMzo3NDo1NTpjYTpiMDpiNTo2NTA/BgNVHREEODA2hjRzcGlmZmU6Ly83ZjQy\nZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgis3ZjQyZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIBBBDOWXWApx4S6bHJ49AW87Nw8uQ/gJ\nJ6lvm3HzEQw2AiEA4PVqWt+z8fsQht0cACM42kghL97SgDSf8rgCqfLYMng=\n-----END CERTIFICATE-----\n",
      "IntermediateCerts": null,
      "Active": true,
      "PrivateKeyType": "ec",
      "PrivateKeyBits": 256,
      "CreateIndex": 8,
      "ModifyIndex": 8
    }
  ]
}

»Get CA Configuration

This endpoint returns the current CA configuration.

MethodPathProduces
GET/connect/ca/configurationapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneoperator:read

»Sample Request

$ curl \
    http://127.0.0.1:8500/v1/connect/ca/configuration

»Sample Response

{
  "Provider": "consul",
  "Config": {
    "LeafCertTTL": "72h",
    "RotationPeriod": "2160h",
    "IntermediateCertTTL": "8760h"
  },
  "CreateIndex": 5,
  "ModifyIndex": 5
}

»Update CA Configuration

This endpoint updates the configuration for the CA. If this results in a new root certificate being used, the Root Rotation process will be triggered.

MethodPathProduces
PUT/connect/ca/configurationapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneoperator:write

»Parameters

  • Provider (string: <required>) - Specifies the CA provider type to use.

  • Config (map[string]string: <required>) - The raw configuration to use for the chosen provider. For more information on configuring the Connect CA providers, see Provider Config.

  • ForceWithoutCrossSigning (bool: <optional>) - Indicates that the CA change should be force to complete even if the current CA doesn't support cross signing. Changing root without cross-signing may cause temporary connection failures until the rollout completes. See Forced Rotation Without Cross-Signing for more detail.

»Sample Payload

{
  "Provider": "consul",
  "Config": {
    "LeafCertTTL": "72h",
    "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----...",
    "RootCert": "-----BEGIN CERTIFICATE-----...",
    "RotationPeriod": "2160h",
    "IntermediateCertTTL": "8760h"
  },
  "ForceWithoutCrossSigning": false
}

»Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/connect/ca/configuration