89 lines
No EOL
6.5 KiB
XML
Executable file
89 lines
No EOL
6.5 KiB
XML
Executable file
<chapter id="timeouts">
|
|
<title>Cookie settings, Session Timeouts, and Token Lifespans</title>
|
|
<para>
|
|
Keycloak has a bunch of fine-grain settings to manage browser cookies, user login sessions, and token lifespans.
|
|
Sessions can be viewed and managed within the admin console for all users, and individually in the user's account
|
|
management pages. This chapter goes over configuration options for cookies, sessions, and tokens.
|
|
</para>
|
|
<section>
|
|
<title>Remember Me</title>
|
|
<para>
|
|
If you go to the admin console page of Settings->General, you should see a <literal>Remember Me</literal> on/off switch.
|
|
Your realm sets a SSO cookie so that you only have to enter in your login credentials once.
|
|
This <literal>Remember Me</literal> admin config option, when turned on, will show a "Remember Me" checkbox on the user's login page.
|
|
If the user clicks this, the realm's SSO cookie will be persistent. This means that if the user closes their browser
|
|
they will still be logged in the next time they start up their browser.
|
|
</para>
|
|
</section>
|
|
<section id="session-timeouts">
|
|
<title>Session Timeouts</title>
|
|
<para>
|
|
If you go to the Sesions and Tokens->Timeout Settings page of the Keycloak adminstration console there is a bunch of fine tuning
|
|
you can do as far as login session timeouts go.
|
|
</para>
|
|
<para>
|
|
The <literal>SSO Session Idle Timeout</literal> is the idle time of a user session. If there is no activity
|
|
in the user's session for this amount of time, the user session will be destroyed, and the user will become logged
|
|
out. The idle time is refreshed with every action against the keycloak server for that session, i.e.: a user login,
|
|
SSO, a refresh token grant, etc.
|
|
</para>
|
|
<para>
|
|
The <literal>SSO Session Max Lifespan</literal> setting is the maximum time a user session is allowed to be alive. This
|
|
max lifespan countdown starts from when the user first logs in and is never refreshed. This works great with <literal>Remember Me</literal>
|
|
in that it allow you to force a relogin after a set timeframe.
|
|
</para>
|
|
</section>
|
|
<section id="token-timeouts">
|
|
<title>Token Timeouts</title>
|
|
<para>
|
|
The <literal>Access Token Lifespan</literal> is how long an access token is valid for. An access token contains everything
|
|
an application needs to authorize a client. It contains roles allowed as well as other user information. When
|
|
an access token expires, your application will attempt to refresh it using a refresh token that it obtained in the
|
|
initial login. The value of this configuration option should be however long you feel comfortable with the
|
|
application not knowing if the user's permissions have changed. This value is usually in minutes.
|
|
</para>
|
|
<para>
|
|
The <literal>Client login timeout</literal> is how long an access code is valid for. An access code is obtained
|
|
on the 1st leg of the OAuth 2.0 redirection protocol. This should be a short time limit. Usually seconds.
|
|
</para>
|
|
<para>
|
|
The <literal>Login user action lifespan</literal> is how long a user is allowed to attempt a login. When a user tries
|
|
to login, they may have to change their password, set up TOTP, or perform some other action before they are redirected
|
|
back to your application as an authentnicated user. This value is relatively short and is usually measured in minutes.
|
|
</para>
|
|
</section>
|
|
<section id="offline-access">
|
|
<title>Offline Access</title>
|
|
<para>
|
|
The Offline access is the feature described in <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess">OpenID Connect specification</ulink> .
|
|
The idea is that during login, your client application will request Offline token instead of classic Refresh token.
|
|
Then the application can save this offline token in the database and can use it anytime later even if user is logged out.
|
|
This is useful for example if your application needs to do some "offline" actions on behalf of user even if user is not online. For example
|
|
periodic backup of some data every night etc.
|
|
</para>
|
|
<para>
|
|
Your application is responsible for persist the offline token in some storage (usually database) and then use it to
|
|
manually retrieve new access token from Keycloak server.
|
|
</para>
|
|
<para>
|
|
The difference between classic Refresh token and Offline token is, that offline token will never expire and is not subject of <literal>SSO Session Idle timeout</literal> .
|
|
The offline token is valid even after user logout or server restart. User can revoke the offline tokens in Account management UI. The admin
|
|
user can revoke offline tokens for individual users in admin console (The <literal>Consent</literal> tab of particular user) and he can
|
|
see all the offline tokens of all users for particular client application in the settings of the client. Revoking of all offline tokens for particular
|
|
client is possible by set <literal>notBefore</literal> policy for the client.
|
|
</para>
|
|
<para>
|
|
For requesting the offline token, user needs to be in realm role <literal>offline_access</literal> and client needs to have
|
|
scope for this role. If client has <literal>Full scope allowed</literal>, the scope is granted by default. Also users are automatically
|
|
members of the role as it's the default role.
|
|
</para>
|
|
<para>
|
|
The client can request offline token by adding parameter <literal>scope=offline_access</literal>
|
|
when sending authorization request to Keycloak. The adapter automatically adds this parameter when you use it to access secured
|
|
URL of your application (ie. http://localhost:8080/customer-portal/secured?scope=offline_access ).
|
|
The <link linkend='direct-access-grants'>Direct Access Grant</link> or <link linkend="service-accounts">Service account</link> flows also support
|
|
offline tokens if you include <literal>scope=offline_access</literal> in the body of the authentication request. For more details,
|
|
see the <literal>offline-access-app</literal> example from Keycloak demo.
|
|
</para>
|
|
</section>
|
|
</chapter> |