# Autocert Settings

The Autocert settings configure Pomerium to manage public-facing TLS certificates automatically, by integrating with a certificate authority (CA) that supports the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555), such as [Let's Encrypt](https://letsencrypt.org/).

Autocert can be useful in situations where Pomerium may not be behind a TLS-terminating ingress controller, proxy, or load balancer that manages TLS certificates on behalf of your upstream services. Certificates provisioned by Autocert provide also [OCSP stapling](https://en.wikipedia.org/wiki/OCSP_stapling).

You must use the [Autocert Directory](#autocert-directory) setting with Autocert to store and share certificate data between Pomerium services.

Autocert can incorporate also certificates set manually in the Pomerium configuration. These certificates will take precedence over generated certificates when applicable to configured routes.

The suite of Autocert settings listed below are supported only in [Pomerium Core](https://www.pomerium.com/docs/deploy/core.md) configurations. Here's what you should know about ACME support in other Pomerium products:

- Pomerium Enterprise users should note that Autocert cannot be configured in the [Enterprise Console](https://www.pomerium.com/docs/deploy/enterprise.md#enterprise-console) or the Pomerium Enterprise [configuration file](https://www.pomerium.com/docs/deploy/enterprise/configure.md). Autocert is a bootstrap setting, meaning it must be configured in Pomerium Core (either in a configuration file or as an environment variable) before running Pomerium Enterprise.

- Kubernetes users should refer to the [Cert-Manager integration](https://www.pomerium.com/docs/deploy/k8s/ingress.md#cert-manager-integration) section for more information on configuring automated certificate management in the Pomerium Ingress Controller.

- Pomerium Zero users should note that Pomerium automatically manages certificates for [starter domains](https://www.pomerium.com/docs/internals/clusters.md#starter-domain) and [custom domains](https://www.pomerium.com/docs/capabilities/custom-domains.md).

## Autocert

The **Autocert** setting enables Pomerium to automatically retrieve, manage, and renew public-facing TLS certificates from the [Autocert CA](#autocert-ca). Pomerium uses these certificates to secure Pomerium-managed route domains and the authenticate service. If you don't configure Autocert CA, Pomerium will use Let's Encrypt by default.

When requesting or renewing a certificate, Pomerium performs either the HTTP-01 or TLS-ALPN-01 challenge (the DNS-01 challenge is not supported):

- The HTTP-01 challenge requires that you set up an HTTP redirect listener on port 80 (see [HTTP Redirect Address](https://www.pomerium.com/docs/reference/http-redirect-address.md)).
- The TLS-ALPN-01 challenge requires that the [Address](https://www.pomerium.com/docs/reference/address.md) setting specifies port 443.

If you use Let's Encrypt as your CA, you agree to the [Let's Encrypt Subscriber Agreement](https://letsencrypt.org/documents/LE-SA-v1.4-April-3-2024.pdf). Let's Encrypt enforces [*strict* usage limits](https://letsencrypt.org/docs/rate-limits/) per domain you should be aware of. Consider testing Autocert with [`autocert_use_staging`](https://www.pomerium.com/docs/reference/autocert.md) first.

[letsencrypt]: https://letsencrypt.org/

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type**  | **Usage**    |
| :------------------- | :------------------------ | :-------- | :----------- |
| `autocert`           | `AUTOCERT`                | `boolean` | **optional** |

#### Examples

```yaml
autocert: true
```

```bash
AUTOCERT=TRUE
```

**Enterprise:**

## Autocert CA

**Autocert CA** is the directory URL of the ACME CA to use when requesting certificates.

If set, Autocert CA will override the [**Autocert Use Staging**](https://www.pomerium.com/docs/reference/autocert.md) setting.

### How to configure

| **Config file keys** | **Environment variables** | **Type** | **Usage**    |
| :------------------- | :------------------------ | :------- | :----------- |
| `autocert_ca`        | `AUTOCERT_CA`             | `string` | **optional** |

#### Examples

```yaml
autocert_ca: https://acme.zerossl.com/v2/DV90
```

```bash
AUTOCERT_CA=https://acme.zerossl.com/v2/DV90
```

## Autocert Directory

**Autocert Directory** is the path where [Autocert](https://www.pomerium.com/docs/reference/autocert.md) stores X.509 certificate data.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `autocert_dir` | `AUTOCERT_DIR` | \*`string` | \*\* **optional** |

\* `string` must point to the directory path or URL of an S3 or GCS bucket.

\*\* If you don't specify an Autocert directory, Pomerium will generate a directory by default based on your runtime environment. See [Defaults](#autocert-directory-defaults) for more information.

#### Examples

##### S3 bucket

An S3 bucket can be used as storage by using a URL like:

```yaml
autocert_dir: s3://your-bucket.s3.us-east-1.amazonaws.com/some/prefix
```

Credentials are sourced from [the environment](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#EnvConfig).

##### GCS bucket

A Google Cloud Storage bucket can be used as storage by using a URL like:

```yaml
autocert_dir: gs://your-bucket/some/prefix
```

Credentials are sourced from [Google Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials).

**Enterprise:**

### Defaults

| **Default paths** | **Value** |
| :-- | :-- |
| Docker images | `/data/autocert` |
| [OS packages](https://github.com/pomerium/pomerium/blob/5e3ae59658246bfe3d4cc5d12997c6e19350bf80/ospkg/pomerium.service#L8) | `/etc/pomerium/` (Must be manually set with environmental variables.) |
| XDG base directories | [$XDG\_DATA\_HOME](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)`/pomerium/autocert` |
| Home directories | `$HOME/.local/share/pomerium/autocert` |

## Autocert EAB Key ID

**Autocert EAB Key ID** is the key identifier when requesting a certificate from a CA with External Account Binding (EAB) enabled.

### How to configure

| **Config file keys**  | **Environment variables** | **Type** | **Usage**    |
| :-------------------- | :------------------------ | :------- | :----------- |
| `autocert_eab_key_id` | `AUTOCERT_EAB_KEY_ID`     | `string` | **optional** |

See [RFC8555-#7.3.4](https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.4) for more information.

#### Examples

```yaml
autocert_eab_key_id: EAB_KID
```

```bash
AUTOCERT_EAB_KEY_ID=EAB_KID
```

## Autocert EAB MAC Key

**Autocert EAB MAC Key** is the base64-URL-encoded secret key corresponding to the [Autocert EAB Key ID](https://www.pomerium.com/docs/reference/autocert.md).

The Autocert EAB MAC Key setting is required when Autocert EAB Key ID is set.

### How to configure

| **Config file keys**   | **Environment variables** | **Type** | **Usage**    |
| :--------------------- | :------------------------ | :------- | :----------- |
| `autocert_eab_mac_key` | `AUTOCERT_EAB_MAC_KEY`    | `string` | **optional** |

#### Examples

```yaml
autocert_eab_mac_key: base64-URL-encoded_secret_key
```

```bash
AUTOCERT_EAB_MAC_KEY=base64-URL-encoded_secret_key
```

## Autocert Email

**Autocert Email** is the email address to use when requesting certificates from an ACME CA or registering an ACME account.

The CA may contact you at this address when, for example, a certificate expires.

### How to configure

| **Config file keys** | **Environment variables** | **Type** | **Usage**    |
| :------------------- | :------------------------ | :------- | :----------- |
| `autocert_email`     | `AUTOCERT_EMAIL`          | `string` | **optional** |

#### Examples

```yaml
autocert_email: example@domain.com
```

```bash
AUTOCERT_EMAIL=example@domain.com
```

## Autocert Must Staple

If true, **Autocert Must Staple** forces Autocert to request a certificate with the `status_request` extension (commonly called `Must-Staple`).

This allows the TLS client (your browser) to fail immediately if the TLS handshake doesn't include OCSP stapling information.

This setting is only used when [Autocert](https://www.pomerium.com/docs/reference/autocert.md) is set to `true`.

The Autocert Must Staple setting will only take effect when you request or renew your certificates.

### How to configure

| **Config file keys** | **Environment variables** | **Type** | **Usage** | **Default** |
| :-- | :-- | :-- | :-- | :-- |
| `autocert_must_staple` | `AUTOCERT_MUST_STAPLE` | `boolean` | **optional** | `false` |

See [RFC7633](https://tools.ietf.org/html/rfc7633) for more information.

#### Examples

```yaml
autocert_must_staple: true
```

```bash
AUTOCERT_MUST_STAPLE=true
```

## Autocert Trusted Certificate Authority

**Autocert Trusted Certificate Authority** is the X.509 CA (bundle) used when communicating with a CA supporting the ACME protocol.

If not set, the system trusted roots will be used to verify TLS connections to the ACME CA.

### How to configure

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `autocert_trusted_ca` | `AUTOCERT_TRUSTED_CA` | `string` | **optional** |
| `autocert_trusted_ca_file` | `AUTOCERT_TRUSTED_CA_FILE` | `string` | **optional** |

#### Examples

```yaml
autocert_trusted_ca: base64-encoded-string
```

```yaml
autocert_trusted_ca_file: /relative/file/location
```

```bash
AUTOCERT_TRUSTED_CA=base64-encoded-string
```

```bash
AUTOCERT_TRUSTED_CA_FILE=/relative/file/location
```

## Autocert Use Staging

The **Autocert Use Staging** setting allows you to use Let's Encrypt's [staging environment](https://letsencrypt.org/docs/staging-environment/), which has more generous [usage limits](https://letsencrypt.org/docs/staging-environment/) than the production environment. If you're testing or using Autocert in development, you should use the staging environment so that you don't exceed Let's Encrypt's rate limits.

### How to configure

| **Config file keys** | **Environment variables** | **Type** | **Usage** | **Default** |
| :-- | :-- | :-- | :-- | :-- |
| `autocert_use_staging` | `AUTOCERT_USE_STAGING` | `boolean` | **optional** | `false` |

#### Examples

```yaml
autocert_use_staging: true
```

```bash
AUTOCERT_USE_STAGING=true
```