Sessions in Pomerium

This article describes how sessions work in Pomerium.

Overview

As part of authentication Pomerium creates sessions for users. The process is as follows:

1. A user attempts to access a route handled by the Pomerium Proxy service.
2. The Authorize service evaluates the policy for that route. If the policy requires a signed-in user, the Authorize service initiates a redirect to the Authenticate service to log the user in.
3. The Authenticate service initiates a login with the identity provider (IdP) by redirecting the user through an Open ID Connect login flow.
4. The IdP logs the user in and redirects the user back to the Authenticate service.
5. The Authenticate service verifies the data from the IdP, creates a session in the Databroker and saves a cookie referencing that session.
6. The user is redirected back to the original route on the Pomerium Proxy service.
7. The Authorize service evaluates the policy for the route again. This time it is able to read the session cookie and load the session data from the Databroker.

Tokens

Pomerium supports several identity providers. Most of these are based on Open ID Connect. Pomerium is a Relying Part (RP) and uses an ID Token to establish user identity. ID Tokens contain various claims which can be used in Authorization policy either directly via the claim criterion, or implicitly through the sub claim identifying a user which can be joined to directory data.

An ID Token represents a point-in-time Authentication event. Pomerium also uses claims from the UserInfo Endpoint, queried during Authentication, as well as periodically to refresh the user with updated claims. Since Pomerium performs authorization on every request this means changes in the identity provider will be picked up without requiring the user to go through another login flow.

As part of Open ID Connect, the identity provider also issues OAuth Access Tokens. These are used to query the user info endpoint, and represent an active session with the identity provider. Access tokens typically also have refresh tokens and Pomerium will periodically refresh the access token. If this fails the corresponding Pomerium session will be terminated.

Token Refresh Scheduling

Pomerium will proactively attempt to refresh the identity provider session shortly before the expiration time of the OAuth access token. Starting in Pomerium v0.31, Pomerium will also attempt to refresh the session shortly before the expiration time of the ID token. This allows Pomerium to maintain a valid ID token over the entire lifetime of a Pomerium session, so long as the identity provider issues a new ID token during refresh. (Not all identity providers will do this.)

This matters only if you are forwarding the ID token to an upstream service using the Set Request Headers option. Otherwise, if the ID token has a shorter validity period than the access token, there could be several windows of time over the course of a Pomerium session during which an upstream service would observe an expired ID token.

This change in behavior can be reverted by setting the runtime flag refresh_session_at_id_token_expiration to false.

Data

A session consists of several properties:

• id: The session's ID, typically a random UUID generated during login
• user_id: The session's User ID, corresponding to a user in the IdP
• issued_at: When the session was created
• expires_at: When the session expires (Default is 14 hours after creation)
• id_token: The ID token issued by the IdP
  • issuer: The ID token issuer
  • subject: The ID token subject, typically a user identifier
  • issued_at: When the ID token was issued
  • expires_at: When the ID token expires
• oauth_token: The OAuth token issued by the IdP
  • access_token: The access token used to access IdP endpoints
  • refresh_token: The refresh token used to get retrieve a new access token
  • expires_at: When the OAuth token expires
• claims: A map of the claims from the ID token and user info endpoint

A user object represents a user in Pomerium. A single user may have many sessions, each with the same user id. It consists of:

• id: The user ID
• name: The user's name claim
• email: The user's email claim
• claims: A map of the claims from the ID token and user info endpoint

In addition to the session and user data populated via login (and periodically during refresh), there are directory users and directory groups that come from a directory provider.

A directory user has:

• id: The user ID, the same as user_id in the session
• group_ids: A list of group IDs corresponding to directory groups
• display_name: The user's display name
• email: The user's email

A directory group has:

• id: The group ID, corresponding to the group_ids in a directory user
• name: The group name
• email: The group email (most IdPs do not have group emails)

Configuration Options

There are a couple options related to sessions in Pomerium:

• cookie_expire: Cookie Expiration sets the lifetime of session cookies. After this interval, users must reauthenticate.
• cookie_domain: Cookie Domain sets the scope of session cookies issued by Pomerium.