# Cookies Settings

This reference covers all of Pomerium's **Cookies Settings**:

- [Cookie Name](#cookie-name)
- [Cookie Secret](#cookie-secret)
- [Cookie Domain](#cookie-domain)
- [Cookie HTTP Only](#cookie-http-only)
- [Cookie Expiration](#cookie-expiration)
- [Cookie SameSite](#cookie-samesite)
- [Cookie Secret File](#cookie-secret-file)

## Cookie Name

**Cookie Name** sets the name of the session cookie sent to clients.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :------------------- | :------------------------ | :------- | :---------- |
| `cookie_name`        | `COOKIE_NAME`             | `string` | `_pomerium` |

#### Examples

```yaml
cookie_name: cookie_name
```

```bash
COOKIE_NAME=cookie_name
```

**Enterprise:**

**Kubernetes:**

| **[Parameter name](https://www.pomerium.com/docs/deploy/k8s/reference.md#cookie)** | **Type** | **Default** |
| :-- | :-- | :-- |
| `cookie.name` | `string` | `_pomerium` |

#### Examples

```yaml
cookie:
  name: cookie_name
```

## Cookie Secret

**Cookie Secret** is the secret used to encrypt and sign session cookies. If you don't provide a cookie secret, Pomerium will generate one for you.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage**    |
| :------------------- | :------------------------ | :------- | :----------- |
| `cookie_secret`      | `COOKIE_SECRET`           | `string` | **optional** |

#### Examples

Generate a random, base64-encoded key:

```shell
head -c32 /dev/urandom | base64
```

Add the value to your configuration:

```yaml
cookie_secret: tdkuWzUelRukP/6VYzopfh6kis7y5u5Ldl3MrIq9ZR0=
```

```bash
COOKIE_SECRET=tdkuWzUelRukP/6VYzopfh6kis7y5u5Ldl3MrIq9ZR0=
```

**Enterprise:**

**Kubernetes:**

See Kubernetes [bootstrap secrets](https://www.pomerium.com/docs/deploy/k8s/configure.md#bootstrap-secrets) for more information.

## Cookie Domain

**Cookie Domain** sets the scope of session cookies issued by Pomerium.

If you specify the domain explicitly, then subdomains would also be included.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** | **Default** |
| :-- | :-- | :-- | :-- | :-- |
| `cookie_domain` | `COOKIE_DOMAIN` | `string` | **optional** | The host that set the cookie |

#### Examples

```yaml
cookie_domain: localhost.pomerium.io
```

```bash
COOKIE_DOMAIN=localhost.pomerium.io
```

**Enterprise:**

**Kubernetes:**

| **[Parameter name](https://www.pomerium.com/docs/deploy/k8s/reference.md#cookie)** | **Type** | **Usage** | **Default** |
| :-- | :-- | :-- | :-- |
| `cookie.domain` | `string` | **optional** | The host that set the cookie |

#### Examples

```yaml
cookie:
  domain: localhost.pomerium.io
```

## Cookie HTTP Only

If true, **Cookie HTTP Only** forbids JavaScript from accessing the cookie.

While the HttpOnly flag is enabled by default for security reasons, some users may choose to disable it for specific use cases that require JavaScript access to cookies. However, disabling HttpOnly cookies significantly increases security risks:

- **XSS Vulnerability**: Without the HttpOnly flag, cookies become accessible to JavaScript code, making them vulnerable to Cross-Site Scripting (XSS) attacks. Malicious scripts could steal session cookies and hijack user sessions.
- **Client-Side Attacks**: Any compromised or malicious JavaScript running on the page can read and exfiltrate cookie values.
- **Third-Party Script Risks**: If your application includes third-party JavaScript libraries or scripts, they would also have access to non-HttpOnly cookies.

Disabling the HttpOnly flag (`cookie_http_only: false`) is strongly discouraged and should only be done when absolutely necessary. If you must disable HttpOnly:

1. Ensure your application has robust XSS protection mechanisms
2. Regularly audit all JavaScript code, including third-party dependencies
3. Consider implementing additional security measures like Content Security Policy (CSP)
4. Limit the scope and lifetime of non-HttpOnly cookies
5. Monitor for suspicious activity that could indicate cookie theft

The security implications of disabling HttpOnly far outweigh most convenience benefits. Carefully evaluate whether your use case truly requires JavaScript cookie access before making this change.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type**  | **Default** |
| :------------------- | :------------------------ | :-------- | :---------- |
| `cookie_http_only`   | `COOKIE_HTTP_ONLY`        | `boolean` | `true`      |

#### Examples

```yaml
cookie_http_only: false
```

```bash
COOKIE_HTTP_ONLY=false
```

**Enterprise:**

**Kubernetes:**

| **[Parameter name](https://www.pomerium.com/docs/deploy/k8s/reference.md#cookie)** | **Type** | **Default** |
| :-- | :-- | :-- |
| `cookie.httpOnly` | `boolean` | `true` |

#### Examples

```yaml
cookie:
  httpOnly: false
```

## Cookie Expiration

**Cookie Expiration** sets the lifetime of session cookies. After this interval, users must reauthenticate.

Pomerium sets its own session timeout (14 hours by default) because it has no way to know if a user simply closed their browser or cleared their cookies. Without an expiration, the server would keep refreshing identity provider tokens for abandoned sessions indefinitely. The timeout acts as a garbage-collection mechanism so that unused session state is eventually cleaned up.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Default** |
| :-- | :-- | :-- | :-- |
| `cookie_expire` | `COOKIE_EXPIRE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `14h` |

#### Examples

```yaml
cookie_expire: 13h15m0.5s
```

```bash
COOKIE_EXPIRE=13h15m0.5s
```

**Enterprise:**

**Kubernetes:**

| **[Parameter name](https://www.pomerium.com/docs/deploy/k8s/reference.md#cookie)** | **Type** | **Default** |
| :-- | :-- | :-- |
| `cookie.expire` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `14h` |

#### Examples

```yaml
cookie:
  expire: 13h15m0.5s
```

## Cookie SameSite

**Cookie SameSite** sets the [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) option for cookies, which determines whether or not a cookie is sent with cross-site requests.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** | **Default** | **Options** |
| :-- | :-- | :-- | :-- | :-- | :-- |
| `cookie_same_site` | `COOKIE_SAME_SITE` | `string` | **optional** | not set (browsers default to `Lax`) | See [Cookie SameSite Options](#cookie-samesite-options) |

#### Examples

```yaml
cookie_same_site: Lax
```

```bash
COOKIE_SAME_SITE=Strict
```

**Enterprise:**

**Kubernetes:**

| **[Parameter name](https://www.pomerium.com/docs/deploy/k8s/reference.md#cookie)** | **Type** | **Usage** | **Default** | **Options** |
| :-- | :-- | :-- | :-- | :-- |
| `cookie.sameSite` | `string` | **optional** | not set (browsers default to `Lax`) | See [Cookie SameSite Options](#cookie-samesite-options) |

#### Examples

```yaml
cookie:
  sameSite: None
```

### Cookie SameSite options

| **Attribute** | **Value** |
| :-- | :-- |
| `Lax` | The cookie is *not* sent on cross-site requests, such as on requests to load images or frames, but is sent when a user is navigating to the origin site from an external site (for example, when following a link). |
| `Strict` | The browser sends the cookie only for same-site requests, that is, requests originating from the same site that set the cookie. |
| `None` | The browser sends the cookie with both cross-site and same-site requests. If you set `SameSite=none`, the cookie must be served over HTTPS. |

## Cookie Secret File

**Cookie Secret File** sets the path to the file containing a secret used to encrypt and sign session cookies.

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage**    |
| :------------------- | :------------------------ | :------- | :----------- |
| `cookie_secret_file` | `COOKIE_SECRET_FILE`      | `string` | **optional** |

#### Examples

Generate a random, base64-encoded key:

```shell
head -c32 /dev/urandom | base64
```

Add the value to your configuration:

```yaml
cookie_secret_file: '/run/secrets/POMERIUM_COOKIE_SECRET'
```

```bash
COOKIE_SECRET_FILE='/run/secrets/POMERIUM_COOKIE_SECRET'
```

This is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/).

**Enterprise:**

`cookie_secret_file` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

See Kubernetes [Secrets reference](https://www.pomerium.com/docs/deploy/k8s/reference.md#spec) for more information.