Skip to main content

Sessions

You sign in to one app in the morning, then open another that uses the same Odudu. It does not ask for your password again. That is a session at work: a record that you proved who you are, kept so that you do not have to prove it twice.

How long a session lastsA timeline from sign-in to a ceiling, with stretches of activity and quiet. A session ends when it has been quiet longer than the idle limit, 30 minutes by default, or when it reaches the absolute limit, 10 hours by default, whichever comes first.Sign inCeilingactivequietactivetoo longShort quiet stretches keep the session alive.One longer than the idle limit ends it.Idle limitquiet for too long, and it endsdefault 30 minutesAbsolute limithowever busy, it ends at the ceilingdefault 10 hours

In words: A timeline from sign-in to a ceiling, with stretches of activity and quiet. A session ends when it has been quiet longer than the idle limit, 30 minutes by default, or when it reaches the absolute limit, 10 hours by default, whichever comes first.

What a session is​

When a person signs in, Odudu records a session and sets a cookie in their browser. The cookie says which session is theirs, and with ODUDU_TLS on it is Secure and prefixed __Host- (the names). The next time any app in the same tenant sends the person to Odudu, the cookie is found and the person is sent straight back signed in.

While the sign-in page is open, a second, short-lived cookie remembers which sign-in this browser started. It signs nobody in. It lets a link mailed during the sign-in, such as a password reset, bring that browser, and no other, back to the application's original request. Anyone using the same browser profile can continue that sign-in until it expires; the cookie is HttpOnly and lives only as long as the login lifetime.

A session belongs to a tenant, to a person and to a browser. It also remembers which clients it signed the person in to, so that signing out can reach them all.

How long it lasts​

Two limits apply, and the earlier one ends the session:

  • The idle limit ends a session nobody has used. It is 30 minutes by default and set with sso_session_idle_seconds.
  • The absolute limit ends a session however busy it is. It is 10 hours by default and set with sso_session_max_seconds.

The idle limit cannot be longer than the absolute one. A tenant that offers a "stay signed in" box on the sign-in form, with remember_me_allowed, gives those people their own pair of limits, remember_me_idle_seconds and remember_me_max_seconds.

One browser can hold several sessions, for example when two people share it. The tenant's max_sessions_per_browser caps them at 25 sessions by default, and when a new one would go past the cap the one used longest ago is ended.

How a session ends​

  • By itself, when a limit is reached.
  • On purpose, when an app sends the person to the tenant's end-session address. Refresh and end a session shows it.
  • By an administrator, who can end one person's sessions, or call DELETE /admin/tenants/{tenant}/sessions to end a tenant's live sessions a few hundred at a time.

Ending a session ends the refresh tokens bound to it, which is what a sign-in in a browser produces. A grant made with the offline_access scope has no session, so ending sessions leaves it alone: its refresh tokens work until their own lifetime runs out or an administrator revokes them. GET /admin/tenants/{tenant}/subjects/{id}/grants lists what a person holds, with offline set on those grants, and DELETE /admin/tenants/{tenant}/subjects/{id}/grants/{clientId} revokes every grant the person holds through one client, offline ones included. An API that checks only an access token's signature keeps accepting it until it expires, which is why access tokens are short. One that asks the introspection endpoint is told at once that it is inactive.

Recovery codes​

A password and an authenticator app, such as a phone, are two things a person has. Lose the phone and the second is gone. Recovery codes are the way back in.

Each person who has set up an authenticator app is given one set of ten recovery codes. You see them once, when they are made, and are asked to keep them somewhere safe. Making a new set replaces the old one, so there are never two sets.

A few rules are worth knowing:

  1. Each code works once. A code that has been used is refused if it is tried again.
  2. A code stands in for an authenticator code, and only that. It is accepted on the step that asks for an authenticator code. It is never accepted after a passkey, because a passkey already proves two things. A person with no authenticator app has no use for a code, and any they hold are not accepted.
  3. Removing the last authenticator app removes the whole set, used codes included, and writes an entry to the audit trail with the action subject.recovery_codes_revoke. A code that outlived its authenticator would otherwise work again after the person set a new one up, and it may have left with the lost phone.
  4. An administrator can revoke a set, with DELETE /admin/tenants/{tenant}/subjects/{id}/recovery-codes. If the person still has an authenticator, the next sign-in asks them to make a new set, unless the call says require_new_set=false. If they have none, nothing more is asked.
  5. A wrong code counts towards the lockout that follows too many wrong second-factor attempts.

The person is told by email when their set is revoked, whether an administrator did it or the last authenticator went.

Working with sessions​

  1. Choose the two limits for your tenant, shorter for sensitive tenants.
  2. Decide whether to offer "stay signed in", and set its limits.
  3. Make sure each app ends the session when its own sign-out is chosen.
  4. When somebody loses a phone, remove the authenticator, end their sessions, revoke their grants so no offline refresh token survives, and let them enrol a new one.

Where to go next​