keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/timeouts.xml

<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<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 <code class="literal">Access Token Lifespan For Implicit Flow</code> is how long an access token is valid for when using OpenID Connect implicit flow.
            With implicit flow, there is no refresh token available. That's why the lifespan is usually bigger than default Access Token Lifespan mentioned above.
            See <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth">OpenID Connect specification</ulink> for details about implicit flow and
            <link linkend="javascript-adapter">Javascript Adapter</link> for some additional details on how to use it in Keycloak.
        </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. However you need to use offline token for refresh at least once per each 30 days (
            The value can be changed in admin console. It is <literal>Offline Session Idle timeout</literal> ). Also if you enable option <literal>Revoke refresh tokens</literal>
            , then each offline token can be used just once. So after refresh, you always need to store new offline token from refresh response into your DB instead of the previous one.
        </para>
        <para>
            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>