libre.sh/keycloak-scim
4
0
Fork 0
Code Issues 15 Pull requests Releases 1 Activity Actions

KEYCLOAK-15744 Initial rewording (#49)

Browse source
This commit is contained in:
Brian Dooley 2021-02-19 10:34:22 +00:00 committed by Marek Posolda
parent 2a82132ff5
commit 3326ed1630
6 changed files with 73 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
server_admin/topics/sessions.adoc
View file

@ -1,10 +1,11 @@
== User Session Management
When a user logs into a realm, {project_name} maintains a user session for them and remembers each and every client they
have visited within the session. There are 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 a set of users from the Admin Console. They
can revoke tokens and set up all the token and session timeouts there too.
When users log into realms, {project_name} maintains a user session for each user and remembers each client visited by the user within the session. Realm administrators can perform multiple actions on each user session:
* View login statistics for the realm.
* View active users and where they logged in.
* Log a user out of their session.
* Revoke tokens.
* Set up token timeouts.
* Set up session timeouts.

28
server_admin/topics/sessions/administering.adoc
View file

@ -1,36 +1,32 @@
=== 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.
To see a top-level view of the active clients and sessions in {project_name}, click *Sessions* from the menu.
.Sessions
image:{project_images}/sessions.png[]
A list of clients is given and how many active sessions there currently are for that client. You can also log out all
users in the realm by clicking the `Logout all` button on the right side of this list.
==== The *Logout all* Operation
==== Limitations of the `Logout all` Operation
You can log out all users in the realm by clicking the *Logout all* button.
Any SSO cookies set will now be invalid and clients that request authentication in active browser sessions will now have to
re-login. Only certain clients are notified of this logout event, specifically clients that are using the {project_name}
OIDC client adapter. Other client types, such as SAML, will not receive a backchannel logout request.
When you click the *Logout all* button, all SSO cookies become invalid, and clients requesting authentication within active browser sessions must log in again. {project_name} notifies clients by using the {project_name} OIDC client adapter of the logout event. Client types such as SAML do not receive a back-channel 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 <<_revocation-policy, revocation policy>> out to
clients, but that also only works with clients using the {project_name} OIDC client adapter.
[NOTE]
====
Clicking *Logout all* does not revoke outstanding access tokens. Outstanding tokens must expire naturally. For clients using the {project_name} OIDC client adapter, you can push a <<_revocation-policy, revocation policy>> to revoke the token, but this does not work for other adapters.
====
==== Application Drilldown
==== Application Navigation
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.
On the `Sessions` page, you can click on each client to go to that client's `Sessions` tab. Click the *Show Sessions* button there to see which users are in the application.
.Application Sessions
image:{project_images}/application-sessions.png[]
==== User Drilldown
==== User Navigation
If you go to the `Sessions` tab of an individual user, you can also view the session information.
If you go to the `Sessions` tab of an individual user, you can also view the user's session information.
.User Sessions
image:{project_images}/user-sessions.png[]

33
server_admin/topics/sessions/offline.adoc
View file

@ -1,32 +1,21 @@
[[_offline-access]]
=== Offline Access
[role="_abstract"]
Offline access is a feature described in https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification] .
The idea is that during login, your client application will request an Offline token instead of a 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 when the user is not online.
An example is a periodic backup of some data every night.
During https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[offline access] logins, the client application requests an offline token instead of a refresh token. The client application saves this offline token and can use it for future logins if the user logs out. This action is useful if your application needs to perform offline actions on behalf of the user even when the user is not online. For example, a regular data backup.
Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to retrieve new access token from {project_name} server.
The client application is responsible for persisting the offline token in storage and then using it to retrieve new access tokens from the {project_name} server.
The difference between a classic Refresh token and an Offline token is, that an offline token will never expire by default and is not subject of the `SSO Session Idle timeout` and `SSO Session Max lifespan`.
The offline token is valid even after a user logout or server restart.
However by default you do need to use the offline token for a refresh token action at least once per 30 days (this value, `Offline Session Idle timeout`, can be changed in the administration console in the `Tokens` tab under `Realm Settings`).
Moreover, if you enable the option `Offline Session Max Limited`, then the offline token expires after 60 days regardless of using the offline token for a refresh token action (this value, `Offline Session Max`, can also be changed in the administration console in the Tokens tab under Realm Settings).
Also if you enable the option `Revoke refresh tokens`, then each offline token can be used just once. So after refresh, you always need to store the new offline token from refresh response into your DB instead of the previous one.
The difference between a refresh token and an offline token is that an offline token never expires and is not subject to the `SSO Session Idle` timeout and `SSO Session Max` lifespan. The offline token is valid after a user logout or server restart. You must use the offline token for a refresh token action at least once per thirty days or for the value of the <<_offline-session-idle, Offline Session Idle>>.
If you enable <<_offline-session-max-limited, Offline Session Max Limited>>, offline tokens expire after 60 days even if you use the offline token for a refresh token action. You can change this value, <<_offline-session-max, Offline Session Max>>, in the Admin Console.
Users can view and revoke offline tokens that have been granted by them in the <<_account-service, User Account Service>>.
The admin user can revoke offline tokens for individual users in admin console in the `Consents` 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 <<_revocation-policy, revocation policy>>.
If you enable the <<_revoke-refresh-token, Revoke Refresh Token>> option, you can use each offline token once only. After refresh, you must store the new offline token from the refresh response instead of the previous one.
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. Finally, the client needs to have an `offline_access` client scope added as an `Optional
client scope` to it, which is done by default.
Users can view and revoke offline tokens that {project_name} grants them in the <<_account-service, User Account Service>>. Administrators can revoke offline tokens for individual users in the Admin Console in the `Consents` tab. Administrators can view all offline tokens issued in the `Offline Access` tab of each client. Administrators can revoke offline tokens by setting a <<_revocation-policy, revocation policy>>.
The client can request an offline token by adding the parameter `scope=offline_access` when sending authorization request to {project_name}.
The {project_name} OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e.
$$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.
To issue an offline token, users must have the role mapping for the realm-level `offline_access` role. Clients must also have that role in their scope. Clients must add an `offline_access` client scope as an `Optional client scope` to the role, which is done by default.
Clients can request an offline token by adding the parameter `scope=offline_access` when sending their authorization request to {project_name}. The {project_name} OIDC client adapter automatically adds this parameter when you use it to access your application's secured URL (i.e., $$http://localhost:8080/customer-portal/secured?scope=offline_access$$). The Direct Access Grant and Service Accounts support offline tokens if you include `scope=offline_access` in the authentication request body.

10
server_admin/topics/sessions/revocation.adoc
View file

@ -1,14 +1,12 @@
[[_revocation-policy]]
=== Revocation Policies
[role="_abstract"]
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.
If your system is compromised, you can revoke all active sessions and access tokens by clicking the `Sessions` screen *Revocation* tab.
.Revocation
image:{project_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 {project_name}
OIDC client adapter installed.
You can specify a time and date where sessions or tokens issued before that time and date are invalid using this console. Click *Set to now* to set the policy to the current time and date. Click *Push* to push this revocation policy to any registered OIDC client with the {project_name} OIDC client adapter.

73
server_admin/topics/sessions/timeouts.adoc
View file

@ -1,90 +1,89 @@
[[_timeouts]]
=== Session and Token Timeouts
[role="_abstract"]
{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.
{project_name} includes control of the session, cookie, and token timeouts through the *Tokens* tab in the *Realm Settings* menu.
.Tokens Tab
image:{project_images}/tokens-tab.png[]
Let's walk through each of the items on this page.
|===
|Configuration|Description
|Default Signature Algorithm
|The default algorithm that is used to assign tokens for this realm.
|The default algorithm used to assign tokens for the realm.
[[_revoke-refresh-token]]
|Revoke Refresh Token
|For OIDC clients that are doing the refresh token flow, this flag, if on, will revoke that refresh token and issue another token with the request that the client has to use. The result is that each refresh token is used only once.
|When *ON*, {project_name} revokes refresh tokens and issues another token that the client must use. This action applies to OIDC clients performing the refresh token flow.
|SSO Session Idle
|Also pertains to OIDC clients. If the user is not active for longer than this timeout, the user session will be invalidated. The idle timeout is reset by a client requesting authentication or by a refresh token request.
There is a small window of time that is always added to the idle timeout before the session invalidation takes effect. See the note below.
|This setting is for OIDC clients only. If a user is inactive for longer than this timeout, the user session is invalidated. This timeout value resets when clients request authentication or send a refresh token request. {project_name} adds a window of time to the idle timeout before the session invalidation takes effect. See the <<_idle_timeouts_note, note>> later in this section.
|SSO Session Max
|Maximum time before a user session is expired and invalidated. This option controls the maximum time that a user session can remain active, regardless of user activity.
|The maximum time before a user session expires.
|SSO Session Idle Remember Me
|Same as the standard SSO Session Idle configuration but specific to logins with Remember Me enabled. It allows for the specification of longer
session idle timeouts when Remember Me is selected during the login process. It is an optional configuration and if not set to a value
greater than 0 it uses the same idle timeout as set in the SSO Session Idle configuration.
|This setting is similar to the standard SSO Session Idle configuration but specific to logins with `Remember Me` enabled. Users can specify longer session idle timeouts when they click `Remember Me` when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same idle timeout as the SSO Session Idle configuration.
|SSO Session Max Remember Me
|Same as the standard SSO Session Max but specific to logins with Remember Me enabled. It allows for the specification of longer lived
sessions when Remember Me is selected during the login process. It is an optional configuration and if not set to a value greater than 0
it uses the same session lifespan as set in the SSO Session Max configuration.
|This setting is similar to the standard SSO Session Max but specific to `Remember Me` logins. Users can specify longer sessions when they click `Remember Me` when logging in. This setting is an optional configuration and, if its value is not greater than zero, it uses the same session lifespan as the SSO Session Max configuration.
[[_offline-session-idle]]
|Offline Session Idle
|For <<_offline-access, offline access>>, this is the time the session is allowed to remain idle before the offline token is revoked.
There is a small window of time that is always added to the idle timeout before the session invalidation takes effect. See the note below.
|This setting is for <<_offline-access, offline access>>. The amount of time the session remains idle before {project_name} revokes its offline token. {project_name} adds a window of time to the idle timeout before the session invalidation takes effect. See the <<_idle_timeouts_note, note>> later in this section.
[[_offline-session-max-limited]]
|Offline Session Max Limited
|For <<_offline-access, offline access>>, if this flag is on, Offline Session Max is enabled to control the maximum time the offline token can remain active, regardless of user activity. Also Client Offline Session Idle and Client Offline Session Max are enabled.
|This setting is for <<_offline-access, offline access>>. If this flag is *ON*, Offline Session Max can control the maximum time the offline token remains active, regardless of user activity. Client Offline Session Idle and Client Offline Session Max are enabled.
[[_offline-session-max]]
|Offline Session Max
|For <<_offline-access, offline access>>, this is the maximum time before the corresponding offline token is revoked. This option controls the maximum time the offline token can remain active, regardless of user activity.
|This setting is for <<_offline-access, offline access>>, and it is the maximum time before {project_name} revokes the corresponding offline token. This option controls the maximum amount of time the offline token remains active, regardless of user activity.
|Client Offline Session Idle
|For <<_offline-access, offline access>>, if the user is not active for longer than this timeout, offline token requests will bump the idle timeout. It allows for the specification of a shorter idle timeout of offline token than offline session idle timeout. However, it can be overridden on individual clients. It is an optional configuration and if not set to a value bigger than 0, it uses the same idle timeout set in the Offline Session Idle configuration.
|This setting is for <<_offline-access, offline access>>. If a user is inactive for longer than this timeout, offline token requests bump the idle timeout. This setting specifies a shorter idle timeout of an offline token than the offline session idle. Users can override this setting for individual clients. This setting is an optional configuration and, when set to zero, uses the same idle timeout in the Offline Session Idle configuration.
|Client Offline Session Max
|For <<_offline-access, offline access>>, the maximum time before a offline token is expired and invalidated. It allows for the specification of a shorter timeout of offline token than offline session timeout. However, it can be overridden on individual clients. It is an optional configuration and if not set to a value bigger than 0, it uses the same idle timeout set in the Offline Session Max configuration.
|This setting is for <<_offline-access, offline access>>. The maximum time before an offline token expires and invalidates. This setting specifies a shorter token timeout than an offline session timeout, but users can override it for individual clients. This setting is an optional configuration and, when set to zero, uses the same idle timeout in the Offline Session Max configuration.
|Client Session Idle
|If the user is not active for longer than this timeout, refresh token requests will bump the idle timeout. It allows for the specification of a shorter idle timeout of refresh token than session idle timeout. And it can be overridden on individual clients. It is an optional configuration and if not set to a value bigger than 0 it uses the same idle timeout set in the SSO Session Idle configuration.
|If the user is inactive for longer than this timeout, refresh token requests bump the idle timeout. This setting specifies a shorter idle timeout of refresh tokens than the session idle timeout, but users can override it for individual clients. This setting is an optional configuration and, when set to zero, uses the same idle timeout in the SSO Session Idle configuration.
|Client Session Max
|The maximum time before a refresh token is expired and invalidated. It allows for the specification of a shorter timeout of refresh token than session timeout. And it can be overridden on individual clients. It is an optional configuration and if not set to a value bigger than 0 it uses the same idle timeout set in the SSO Session Max configuration.
|The maximum time before a refresh token expires and invalidates. This setting specifies a shorter timeout of refresh tokens than the session timeout, but users can override it for individual clients. This setting is an optional configuration and, when set to zero, uses the same idle timeout in the SSO Session Max configuration.
|Access Token Lifespan
|When an OIDC access token is created, this value affects the expiration.
|When {project_name} creates an OIDC access token, this value controls the lifetime of the token.
|Access Token Lifespan For Implicit Flow
|With the Implicit Flow no refresh token is provided. For this reason there's a separate timeout for access tokens created with the Implicit Flow.
|With the Implicit Flow, {project_name} does not provide a refresh token. A separate timeout exists for access tokens created by the Implicit Flow.
|Client login timeout
|This is the maximum time that a client has to finish the Authorization Code Flow in OIDC.
|The maximum time before clients must finish the Authorization Code Flow in OIDC.
|Login timeout
|Total time a login must take. If authentication takes longer than this time then the user will have to start the authentication process over.
|The total time a logging in must take. If authentication takes longer than this time, the user must start the authentication process again.
|Login action timeout
|Maximum time a user can spend on any one page in the authentication process.
|The Maximum time users can spend on any one page during the authentication process.
|User-Initiated Action Lifespan
|Maximum time before an action permit sent by a user (e.g. forgot password e-mail) is expired. This value is recommended to be short because it is expected that the user would react to self-created action quickly.
|The maximum time before a user's action permission expires. Keep this value short because users generally react to self-created actions quickly.
|Default Admin-Initiated Action Lifespan
|Maximum time before an action permit sent to a user by an admin is expired. This value is recommended to be long to allow admins send e-mails for users that are currently offline. The default timeout can be overridden right before issuing the token.
|The maximum time before an action permission sent to a user by an administrator expires. Keep this value long to allow administrators to send e-mails to offline users. An administrator can override the default timeout before issuing the token.
|Override User-Initiated Action Lifespan
|Permits the possibility of having independent timeouts per operation (for example, e-mail verification, forgot password, user actions and Identity Provider E-mail Verification). This field is optional. If nothing is specified, it defaults to the value configured at _User-Initiated Action Lifespan_.
|Specifies independent timeouts per individual operation (for example, e-mail verification, forgot password, user actions, and Identity Provider E-mail Verification). This value defaults to the value configured at _User-Initiated Action Lifespan_.
|===
NOTE: For idle timeouts, there is a small window of time (2 minutes) during which the session is kept unexpired. For example, when you have
timeout set to 30 minutes, it will be actually 32 minutes before the session is expired. This is needed for some corner-case scenarios in
cluster and cross-datacenter environments, in cases where the token was refreshed on one cluster node for a very short time before the
expiration and the other cluster nodes would in the meantime incorrectly consider the session as expired, because they had not yet received
the message about successful refresh from the node which did the refresh.
[[_idle_timeouts_note]]
[NOTE]
====
For idle timeouts, a two-minute window of time exists that the session is active. For example, when you have the timeout set to 30 minutes, it will be 32 minutes before the session expires.
This action is necessary for some scenarios in cluster and cross-data center environments where the token refreshes on one cluster node a short time before the expiration and the other cluster nodes incorrectly consider the session as expired because they have not yet received the message about a successful refresh from the refreshing node.
====

9
server_admin/topics/sessions/transient.adoc
View file

@ -1,11 +1,8 @@
[[_transient-session]]
=== Transient sessions
{project_name} has concept of transient sessions. When transient sessions are used, there is no real user session created after successful authentication.
Only a temporary transient session is created for the scope of the current request that successfully authenticated the user. This transient session allows {project_name}
to run <<_protocol-mappers, protocol mappers>> after the authentication.
You can conduct transient sessions in {project_name}. When using transient sessions, {project_name} does not create a user session after successful authentication. {project_name} creates a temporary, transient session for the scope of the current request that successfully authenticates the user. {project_name} can run <<_protocol-mappers, protocol mappers>> using transient sessions after authentication.
When transient sessions are used, the client application has no way to refresh or introspect the token or check if a specific session is valid.
In some situations, these actions are not needed, so you can avoid the additional overhead for persistence of user sessions.
This would mean the save of performance, memory and network communication (in case of cluster and cross-datacenter environments).
During transient sessions, the client application cannot refresh tokens, introspect tokens, or validate a specific session. Sometimes these actions are unnecessary, so you can avoid the additional resource use of persisting user sessions. This session saves performance, memory, and network communication (in cluster and cross-data center environments) resources.