Trust a private certificate authority

The Ory Enterprise License (OEL) images of Ory Kratos Identities, Ory Hydra Authorization, Ory Keto Permissions, Ory Oathkeeper IAM Proxy, and Ory Talos Secure API Keys verify outbound TLS connections against a root certificate bundle that is built into each binary. The bundle is Mozilla's set of trusted root certificate authorities (CAs). By default, the services do not read the CA bundle of the container image, and they ignore a bundle in SSL_CERT_FILE or SSL_CERT_DIR.

Outbound connections include calls to webhooks, OIDC providers, JWKS URLs, token introspection endpoints, remote authorizers, and tracing exporters. When one of these endpoints uses a certificate from a private CA, the connection fails with this error:

x509: certificate signed by unknown authority

Use your own CA bundle

To trust a private CA, set these environment variables on the container:

GODEBUG=x509usefallbackroots=0
SSL_CERT_FILE=/etc/ory/certs/ca-bundle.pem

GODEBUG=x509usefallbackroots=0 makes the service use the system certificate store instead of the built-in bundle. SSL_CERT_FILE sets the file that the system store reads. To use a directory of certificates, set SSL_CERT_DIR instead.

The service then trusts only the certificates in your bundle, plus the CA bundle of the image if the image has one. It does not add the built-in bundle to your bundle. If the service also calls public endpoints, such as a social sign-in provider, add the public root CAs to your bundle. A common approach is to append your private CA to a public bundle, such as the ca-certificates package of your Linux distribution.

Ory Kratos and the Landlock sandbox

Ory Kratos Identities restricts its file access with a Landlock sandbox. List your bundle file or directory under security.landlock.allowed_paths, or Ory Kratos Identities cannot read it:

security:
  landlock:
    allowed_paths:
      - /etc/ory/certs/ca-bundle.pem