sessions

SUMMARY.adoc

@@ -76,7 +76,11 @@
  .. link:topics/identity-broker/session-data.adoc[Available User Session Data]
  .. link:topics/identity-broker/first-login-flow.adoc[First Login Flow]
  .. link:topics/identity-broker/tokens.adoc[Retrieving External IDP Tokens]
- . link:topics/timeouts.adoc[Cookie settings, Session Timeouts, and Token Lifespans]
+ . link:topics/sessions.adoc[User Session Management]
+ .. link:topics/sessions/administering.adoc[Administering Sessions]
+ .. link:topics/sessions/revocation.adoc[Revocation Policies]
+ .. link:topics/sessions/timeout.adoc[Session and Token Timeouts]
+ .. link:topics/sessions/offline.adoc[Offline Access]
  . link:topics/events.adoc[Auditing and Events]
  . link:topics/ldap.adoc[LDAP/AD Integration]
  . link:topics/export-import.adoc[Export and Import]

topics/sessions.adoc

@@ -0,0 +1,10 @@
+
+== User Session Management
+
+When a user logs into a realm, {{book.project.name}} maintains a user session for them and remembers each and every client they
+have visited within the session.  There's a lot of administrative
+functions that realm admins can perform on these user sessions.  They can view login stats for the entire realm and dive down
+into each client to see who is logged in and where.  Admins can logout a user or set of users from the Admin Console. They
+can revoke tokens and setup all the token and session timeouts there too.
+
+

topics/sessions/administering.adoc

@@ -0,0 +1,36 @@
+
+=== Administering Sessions
+
+If you go to the `Sessions` left menu item you can see a top level view of the number of sessions that are currently active in the realm.
+
+.Sessions
+image:../../{{book.images}}/sessions.png[]
+
+A list of clients is given and how many active sessions there currently are for that client. You can also logout all
+users in the realm by clicking the `Logout all` button on the right side of this list.
+
+==== Logout All Limitations
+
+Any SSO cookies set will now be invalid and clients that request authentication in active browser sessions will now have to
+relogin.  Only certain clients are notified of this logout event, specifically clients that are using the {{book.projec.name}}
+OIDC client adapter. Other client types (i.e. SAML) will not receive a backchannel logout request.
+
+It is important to note that any outstanding access tokens are not revoked by clicking `Logout all`.  They have to
+expire naturally.  You have to push a <<fake/../../sessions/revocation.adoc#_revocation-policy, revocation policy>> out to
+clients, but that also only works with clients using the {{book.project.name}} OIDC client adapter.
+
+==== Application Drilldown
+
+On the `Sessions` page, you can also drill down to each client. This will bring you to the `Sessions` tab of that client.
+Clicking on the `Show Sessions` button there allows you to see which users are logged into that application.
+
+.Application Sessions
+image:../../{{book.images}}/application-sessions.png[]
+
+==== User Drilldown
+
+If you go to the `Sessions` tab of an individual user, you can also view there session information.
+
+.User Sessions
+image:../../{{book.images}}/user-sessions.png[]
+

topics/sessions/offline.adoc

@@ -0,0 +1,30 @@
+[[_offline-access]]
+
+=== Offline Access
+
+The Offline access is the feature described in http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification] .
+The idea is that during login, your client application will request Offline token instead of classic Refresh token.
+The application can save this offline token in a database or on disk and can use it later even if user is logged out.
+This is useful if your application needs to do some "offline" actions on behalf of user even if user is not online
+like periodic backup of some data every night etc.
+
+Your application is responsible to persist the offline token in some storage (usually database) and then use it to manually retrieve new access token from {{book.project.name}} server.
+
+The difference between classic Refresh token and Offline token is, that offline token will never expire and is not subject of `SSO Session Idle timeout` .
+The offline token is valid even after a user logout or server restart.
+However you do need to use the offline token for refresh token action at least once per each 30 days ( The value can be changed in admin console.
+It is `Offline Session Idle timeout` ). Also if you enable option `Revoke refresh tokens`, 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.
+
+Users can view and revoke offline tokens that have been granted by them in the <<fake/../../account.adoc#_account-service, User Account Service>>.
+The admin user can revoke offline tokens for individual users in admin console in the `Consent` tab of a particular user.
+The admin can also view all the offline tokens issued in the `Offline Access` tab of each client.
+Offline tokens can also be revoked by setting a <<fake/../../sessions/revocation.adoc#_revocation-policy, revocation policy>>.
+
+To be able to issue an offline token, users need to have the role mapping for the realm-level role `offline_access`.
+Clients also need to have that role in their scope.
+
+The client can request offline token by adding the parameter `scope=offline_access` when sending authorization request to {{book.project.name}.
+The {{book.project.name}} OIDC client 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 Direct Access Grant and Service Accounts also
+support offline tokens if you include `scope=offline_access` in the body of the authentication request.

topics/sessions/revocation.adoc

@@ -0,0 +1,14 @@
+[[_revocation-policy]]
+
+=== Revocation Policies
+
+If your system is compromised you will want a way to revoke all sessions and access tokens that have been handed out.
+You can do this by going to the `Revocation` tab of the `Sessions` screen.
+
+.Revocation
+image:../../{{book.images}}/revocation.png[]
+
+You can only set a time-based revocation policy.  The console allows you to specify a time and date where any session
+or token issued before that time and date is invalid.  The `Set to now` will set the policy to the current time and date.
+The `Push` button will push this revocation policy to any registered OIDC client that has the {{book.project.name}}
+OIDC client adapter installed.

topics/sessions/timeouts.adoc

@@ -0,0 +1,43 @@
+[[_timeouts]]
+
+=== Session and Token Timeouts
+
+{{book.project.name}} gives you fine grain control of session, cookie, and token timeouts.  This is all done on the
+`Tokens` tab in the `Realm Settings` left menu item.
+
+.Tokens Tab
+image:../../{{book.images}}/tokens-tab.png[]
+
+Let's walk through each of the items on this page.
+
+|===
+|Configuration|Description
+
+|Revoke Refresh Token
+|For OIDC clients that doing the refresh token flow, this flag, if on, will revoke that refresh token and issue another with the request that the client has to use.
+ This basically means that refresh tokens have a one time use.
+
+|SSO Session Idle
+|Also pertains to OIDC clients.  If the user is not active for long than this timeout, the user session will be invalidated.  How is idle time checked?
+ A client requesting authentication will bump the idle timeout.  Referesh token requests will also bump the idle timeout.
+
+|SSO Session Max
+|Maximum time before a user session is expired and invalidated.  This is a hard number and time.  It controls the maximum time
+ a user session can remain active, irregardless of activity.
+
+|Offline Session Idle
+|For <<fake/../../sessions/offline.adoc#_offline-access, offline access>>, this is the time the session is allowed
+ to remain Idle before the offline token is revoked.
+
+|Access Token Lifespan
+|When an OIDC access token is created, this value effects the expiration.
+
+|Client login timeout
+|This is the maximum time that a client has to finish the Authentication Code Flow in OIDC.
+
+|Login timeout
+|Total time a login must take.  Anything beyond this time and the user will have to start the authentication process over.
+
+|Login action timeout
+|Maximum time a user can spend on any one page in the authentication process.
+|===

topics/timeouts.adoc

@@ -1,76 +0,0 @@
-[[_timeouts]]
-= Cookie settings, Session Timeouts, and Token Lifespans
-
-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. 
-
-== Remember Me
-
-If you go to the admin console page of Settings->General, you should see a `Remember Me` on/off switch.
-Your realm sets a SSO cookie so that you only have to enter in your login credentials once.
-This `Remember Me` 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. 
-
-== Session Timeouts
-
-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. 
-
-The `SSO Session Idle Timeout` 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. 
-
-The `SSO Session Max Lifespan` 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 `Remember Me`            in that it allow you to force a relogin after a set timeframe. 
-
-== Token Timeouts
-
-The `Access Token Lifespan` 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. 
-
-The `Access Token Lifespan For Implicit Flow` 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 http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[OpenID Connect specification] for details about implicit flow and <<_javascript_adapter,Javascript Adapter>> for some additional details on how to use it in Keycloak. 
-
-The `Client login timeout` 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. 
-
-The `Login user action lifespan` 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. 
-
-== Offline Access
-
-The Offline access is the feature described in http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification] . 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. 
-
-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. 
-
-The difference between classic Refresh token and Offline token is, that offline token will never expire and is not subject of `SSO Session Idle timeout` . 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 `Offline Session Idle timeout` ). Also if you enable option `Revoke refresh tokens`            , 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. 
-
-User can revoke the offline tokens in Account management UI.
-The admin user can revoke offline tokens for individual users in admin console (The `Consent` 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 `notBefore` policy for the client. 
-
-For requesting the offline token, user needs to be in realm role `offline_access` and client needs to have scope for this role.
-If client has `Full scope allowed`, the scope is granted by default.
-Also users are automatically members of the role as it's the default role. 
-
-The client can request offline token by adding parameter `scope=offline_access`            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 <<_direct_access_grants,Direct Access Grant>> or <<_service_accounts,Service account>> flows also support offline tokens if you include `scope=offline_access` in the body of the authentication request.
-For more details, see the `offline-access-app` example from Keycloak demo.