Cookies Settings

This reference covers all of Pomerium's Cookies Settings:

• Cookie Name
• Cookie Secret
• Cookie Domain
• Cookie Secure
• Cookie HTTP Only
• Cookie Expiration
• Cookie SameSite
• 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

Enterprise

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

Kubernetes

Name	Type	Default
cookie.name	string	_pomerium

See Kubernetes Cookie Reference for more information.

Examples

# config file key
cookie_name: cookie_name

# environment variable
COOKIE_NAME=cookie_name

# ingress
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

Enterprise

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

Kubernetes

See Kubernetes bootstrap secrets for more information.

Examples

Generate a random, base64-encoded key:

head -c32 /dev/urandom | base64

Add the value to your configuration:

cookie_secret: tdkuWzUelRukP/6VYzopfh6kis7y5u5Ldl3MrIq9ZR0=

COOKIE_SECRET=tdkuWzUelRukP/6VYzopfh6kis7y5u5Ldl3MrIq9ZR0=

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

Enterprise

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

Kubernetes

Name	Type	Usage	Default
cookie.domain	string	optional	The host that set the cookie

See Kubernetes Cookie Reference for more information.

Examples

# config file key
cookie_domain: localhost.pomerium.io

# environment variable
COOKIE_DOMAIN=localhost.pomerium.io

# ingress
cookie.domain: localhost.pomerium.io

Cookie Secure

If true, Cookie Secure instructs browsers to only send user session cookies over HTTPS.

danger

Setting this to false may result in session cookies being sent in clear text.

Note: this cannot be set to false if Cookie SameSite is set to None.

How to configure

Core

Config file keys	Environment variables	Type	Default
cookie_secure	COOKIE_SECURE	boolean	true

Enterprise

Configure Cookie Secure with the HTTPS only toggle button in the Console. The button has three states:

• Unset ("-") uses the value in your configuration file
• Checkmark sets cookie_secure to true
• Empty sets cookie_secure to false

Kubernetes

Name	Type	Default
cookie.secure	boolean	true

See Kubernetes Cookie Reference for more information.

Examples

# config file key
cookie_secure: false

# environment variable
COOKIE_SECURE=false

# ingress
cookie.secure: false

Cookie HTTP Only

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

How to configure

Core

Config file keys	Environment variables	Type	Default
cookie_http_only	COOKIE_HTTP_ONLY	boolean	true

Enterprise

Configure Cookie HTTP Only with the Javascript Security toggle button in the Console. The button has three states:

• Unset ("-") uses the value in your configuration file
• Checkmark sets cookie_http_only to true
• Empty sets cookie_http_only to false

Kubernetes

Name	Type	Default
cookie.httpOnly	boolean	true

See Kubernetes Cookie Reference for more information.

Examples

# config file key
cookie_http_only: false

# environment variable
COOKIE_HTTP_ONLY=false

# ingress
cookie.httpOnly: false

Cookie Expiration

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

How to configure

Core

Config file keys	Environment variables	Type	Default
cookie_expiration	COOKIE_EXPIRATION	string (Go Duration formatting)	14h

Enterprise

Set Cookie Expiration in the Console:

Kubernetes

Name	Type	Default
authenticate.expiration	string (Go Duration formatting)	14h

See Kubernetes Cookie Reference for more information.

Examples

# config file key
cookie_expiration: 13h15m0.5s

# environment variable
COOKIE_EXPIRATION=13h15m0.5s

# ingress
cookie.expiration: 13h15m0.5s

Cookie SameSite

Cookie SameSite sets the SameSite 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	Lax (if unset)	See Cookie SameSite Options

Enterprise

Set the Cookie SameSite attribute in the Console:

See Cookie SameSite Options for more information.

Kubernetes

Name	Type	Usage	Default	Options
cookie.sameSite	string	optional	Lax (if unset)	See Cookie SameSite Options

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 HTTPS only setting must be set to true.

Examples

# config file key
cookie_same_site: Lax

# environment variable
COOKIE_SAME_SITE=Strict

# ingress
cookie.sameSite: None

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	required (for proxy service)

Enterprise

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

Kubernetes

See Kubernetes Secrets reference for more information.

Examples

Generate a random, base64-encoded key:

head -c32 /dev/urandom | base64

Add the value to your configuration:

cookie_secret_file: '/run/secrets/POMERIUM_COOKIE_SECRET'

COOKIE_SECRET_FILE='/run/secrets/POMERIUM_COOKIE_SECRET'

This is useful when deploying in environments that provide secret management like Docker Swarm.