User sessions

User sessions facilitate the single sign-on (SSO) functionality of Goiabada. Once a user logs in, a new session starts. If they try to log in again and their session is still good, they don’t need to go through the authentication process again.

Session configuration

There are two configurations related to user sessions:

Property	Description
User session idle timeout in seconds	If there is no activity from the user within this timeframe, the session will be terminated. This checks the last_accessed timestamp of the session.
User session max lifetime in seconds	The maximum duration a user session can last, irrespective of user activity. This is checked against the started timestamp of the session.

Session refresh

A user session is “bumped” (receives a new last_accessed timestamp) in two situations:

1. When a new authorization request completes
2. When a refresh token associated with the session is used to request a new access token

Forcing re-authentication

There are two ways to force re-authentication in an authorization request:

Using max_age

Include the max_age parameter to define the maximum acceptable time (in seconds) since the session started.

For instance, if you add max_age=120 to the authentication request, the user needs to re-authenticate if their session started more than 120 seconds (2 minutes) ago, regardless of having a valid session or recent activity.

This is useful when the client needs to ensure that the user authenticated within a specific timeframe. Unlike the session idle timeout (which resets with activity), max_age is always measured from when the session was originally created.

Using prompt=login

Include prompt=login in the authorization request to always force re-authentication, regardless of session age. Unlike max_age, which only triggers re-authentication for stale sessions, prompt=login will require the user to log in again every time.

See Prompt parameter for details on all supported prompt values.

Example

GET /auth/authorize?
  client_id=my-app&
  redirect_uri=https://my-app.com/callback&
  response_type=code&
  scope=openid&
  max_age=120&
  code_challenge=...&
  code_challenge_method=S256