config properties session

Version

v2.1.2

session Type

object (session)

session Properties

Property	Type	Required	Nullable	Defined by
allow_revocation	boolean	Optional	cannot be null	Config
audience	array	Optional	cannot be null	Config
acquire_ip_address	boolean	Optional	cannot be null	Config
acquire_user_agent	boolean	Optional	cannot be null	Config
cookie	object	Optional	cannot be null	Config
enable_auth_token_header	boolean	Optional	cannot be null	Config
issuer	string	Optional	cannot be null	Config
lifespan	string	Optional	cannot be null	Config
limit	integer	Optional	cannot be null	Config
show_on_profile	boolean	Optional	cannot be null	Config
server_side	object	Optional	cannot be null	Config
jwt_template	object	Optional	cannot be null	Config

allow_revocation

allow_revocation allows users to revoke their own sessions.

allow_revocation

• is optional

• cannot be null

allow_revocation Type

boolean

allow_revocation Default Value

The default value is:

true

audience

audience is a list of strings that identifies the recipients that the JWT is intended for. The audiences are placed in the aud claim of the JWT. If not set, it defaults to the value of thewebauthn.relying_party.id configuration parameter.

audience

• is optional

• cannot be null

audience Type

string[]

acquire_ip_address

acquire_ip_address stores the user's IP address in the database.

acquire_ip_address

• is optional

• cannot be null

acquire_ip_address Type

boolean

acquire_ip_address Default Value

The default value is:

true

acquire_user_agent

acquire_user_agent stores the user's user agent in the database.

acquire_user_agent

• is optional

• cannot be null

acquire_user_agent Type

boolean

acquire_user_agent Default Value

The default value is:

true

cookie

cookie contains configuration for the session cookie issued on successful registration or login.

cookie

• is optional

• cannot be null

cookie Type

object (Details)

enable_auth_token_header

enable_auth_token_header determines whether a session token (JWT) is returned in an X-Auth-Token header after a successful authentication. This option should be set to true if API and client applications run on different domains.

enable_auth_token_header

• is optional

• cannot be null

enable_auth_token_header Type

boolean

enable_auth_token_header Default Value

The default value is:

false

issuer

issuer is a string that identifies the principal (human user, an organization, or a service) that issued the JWT. Its value is set in the iss claim of a JWT.

issuer

• is optional

• cannot be null

issuer Type

string

lifespan

lifespan determines the maximum duration for which a session token (JWT) is valid. It must be a (possibly signed) sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

lifespan

• is optional

• cannot be null

lifespan Type

string

lifespan Default Value

The default value is:

"12h"

limit

limit determines the maximum number of server-side sessions a user can have. When the limit is exceeded, older sessions are invalidated.

limit

• is optional

• cannot be null

limit Type

integer

limit Default Value

The default value is:

5

show_on_profile

show_on_profile indicates that the sessions should be listed on the profile.

show_on_profile

• is optional

• cannot be null

show_on_profile Type

boolean

show_on_profile Default Value

The default value is:

true

server_side

Deprecated. Use settings in parent object. server_side contains configuration for server-side sessions.

server_side

• is optional

• cannot be null

server_side Type

object (Details)

jwt_template

jwt_template defines a template for adding custom claims to session JWTs.

These claims are processed at JWT generation time and can include static values, templated strings using Go's text/template syntax, or nested structures (maps and slices).

The template has access to user data via the .User field, which includes:

• .User.UserID: The user's unique ID (string)
• .User.Email: Email details (optional, with .Address, .IsPrimary, .IsVerified)
• .User.Username: The user's username (string, optional)

Claims that fail to process (e.g., due to invalid templates) are logged and skipped, ensuring JWT generation continues without interruption.

Example usage in YAML configuration:

session:
  lifespan: 24h
  jwt_template:
    claims:
      role: "user"                               # Static value
      user_email: "{{.User.Email.Address}}"      # Templated string
      is_verified: "{{.User.Email.IsVerified}}"  # Boolean from user data
      metadata:                                  # Nested map
        source: "hanko"
        greeting: "Hello {{.User.Username}}"
      scopes:                                    # Slice with templated value
        - "read"
        - "write"
        - "{{if .User.Email.IsVerified}}admin{{else}}basic{{end}}"

In this example:

• role is a static string ("user").
• user_email dynamically inserts the user's email address.
• is_verified inserts a boolean indicating email verification status.
• metadata is a nested map with a static source and a templated greeting.
• scopes is a slice combining static values and a conditional template.

Notes:

• Claims with the following keys will be ignored because they are currently added to the JWT by default:
  • sub
  • iat
  • exp
  • aud
  • iss
  • email
  • username
  • session_id
• Templates must be valid Go text/template syntax. Invalid templates are logged and ignored.
• Boolean strings ("true" or "false") from templates are automatically converted to actual booleans.
• Use conditionals (e.g., {{if .User.Email}}) to handle optional fields safely.

For more details on template syntax, see: https://pkg.go.dev/text/template

jwt_template

• is optional

• cannot be null

jwt_template Type

object (Details)