diff --git a/docs/admin/auth-server/openid-features/logout/README.md b/docs/admin/auth-server/openid-features/logout/README.md index ff91f256c5f..2401b9646a7 100644 --- a/docs/admin/auth-server/openid-features/logout/README.md +++ b/docs/admin/auth-server/openid-features/logout/README.md @@ -9,7 +9,13 @@ tags: # Overview -Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page. +Although Jans Auth Server has a `session_id` for each person who has authenticated, +applications generally have their *own* sessions. Upon logout from an OpenID Provider, ideally all RPs are notified, so they can also their local sessions. The OpenID solution to implement logout is currently described in the [OpenID Connect Front Channel Logout specification](http://openid.net/specs/openid-connect-frontchannel-1_0.html). -!!! Contribute -If you’d like to contribute to this document, get started with the [Contribution Guide](https://docs.jans.io/head/CONTRIBUTING/#contributing-to-the-documentation) \ No newline at end of file +In practice, here's how it works: + + - Jans Auth Server `end_session` endpoint returns an HTML page, which contains an iFrame for each application to which the user has authenticated. + - The iFrame contains a link to each application's respective logout URL. + - The special HTML page should be loaded in the background and not displayed to the user. + - The iFrame URLs should be loaded by the browser. + - Now, upon logout, the user is calling the logout page of each application, the local cookies are cleared, and the user is signed out of all applications. diff --git a/docs/admin/auth-server/session-management/README.md b/docs/admin/auth-server/session-management/README.md index 7d823f05be5..cdeac0c893f 100644 --- a/docs/admin/auth-server/session-management/README.md +++ b/docs/admin/auth-server/session-management/README.md @@ -7,41 +7,46 @@ tags: # Overview -A session is a reference identifier on the Jans Auth Server that connect to a -person's authentication state. Most commonly, the session is stored in -the person's web browser, in the `session_id` cookie. OpenID Native SSO also -defines a way for mobile apps from the same vendor to use the iOS or Android -protected secret storage to store a session. By correlating the session, the IDP -can return an identity assertion (id_token) to a client without needing to -authenticate the person. Thus sessions enable SSO. +A session is a reference identifier on the Jans Auth Server that connects to a +person's authentication state. During an authentication workflow, Auth Server writes a cookie with the `session_id` in the person's browser. OpenID Native +SSO defines a way for mobile apps from the same vendor to use the iOS or Android +protected secret storage to store the `session_id`. By correlating the session, +the IDP can return an identity assertion (id_token) to a client without needing +to re-authenticate the person. SSO ensues. For example, let's say a person uses a browser to navigate to the website of Relying Party (RP1), which redirects to Jans Auth Server for authentication. Once the person is authenticated, the OP creates a `session_id` cookie, sets the -state to `authenticated`, and places it in the cache. If the user hits RP2, -it will redirect the user to the OP for authentication, and since the session is -already authenticated, the OP authenticates the user automatically for RP2 -(without an authentication prompt). - -Jans Auth Server stores user session data in its cache, whether it's in-memory, -redis, memcached or the databse, depending on the `cacheProviderType` -configuration property. - -The OP session can have one of two states: - -- `unauthenticated` - when the end-user reaches the OP but has not yet authenticated, a session object is created and put in the cache with the `unauthenticated` state. -- `authenticated` - when the user has successfully authenticated at the OP. - - -- **sessionIdLifetime** - lifetime of the OP session in seconds. It sets both the - -- **session_id** cookie expiration property as well as the OP session object expiration (if -- **serverSessionIdLifetime** is not set or equals `0` which is default behavior) in the persistence. It's a global property for sessions. Starting in version `4.1`, it is possible to set value to 0 or -1, which means that expiration is not set (not available in `3.1.3` or earlier except `2.4.4`). In this case, the `session_id` cookie expiration value is set to the `session` value, which means it's valid until the browser session ends. -- **serverSessionIdLifetime** - dedicated property to control lifetime of the server side OP session object in seconds. Overrides `sessionIdLifetime`. By default value is 0, so object lifetime equals `sessionIdLifetime` (which sets both cookie and object expiration). It can be useful if goal is to keep different values for client cookie and server object. -- **sessionIdUnusedLifetime** - unused OP session lifetime in seconds (set by default to 1 day). If an OP session is not used for a given amount of time, the OP session is removed. -- **sessionIdUnauthenticatedUnusedLifetime** - lifetime in seconds of `unauthenticated` OP session. This determines how long the user can be on the login page while unauthenticated. -- **sessionIdRequestParameterEnabled** - Boolean value specifying whether to enable session_id HTTP request parameter. Default value is `false` (since 4.2). -- **sessionIdPersistOnPromptNone** - specifies whether to persist or update the session object with data if `prompt=none`. Default value is `true`, so session is persisted by default. +state to `authenticated`, and places it in the cache. If the person mavigates +their browser to the website of RP2, it redirects to the OP for authentication; since the `session_id` detected via the cookie is already authenticated, the OP +authenticates the person automatically for RP2 (without an authentication +prompt). + +Jans Auth Server stores user session data in its cache. Auth Server performance +retrieving the session will vary depending on whether the session is stored in memory, Redis, Memcached or the database, as controlled by the +`cacheProviderType` Auth Server configuration property. + +The Auth Server session can have one of two states: + +- `unauthenticated` - a browser that has started, but not completed an authentication workflow. +- `authenticated` - when a person has successfully authenticated + +The following Auth Server configuration properties are related to sessions: + +- **sessionIdLifetime** - lifetime of the OP session in seconds. It sets both the `session_id` cookie expiration property as well as the OP session object expiration (if `serverSessionIdLifetime` is not set or equals 0 which is default behavior) in the persistence. Upi cam set the value to 0 or -1, which means that expiration is not set. In this case, the sesion is valid until the browser +session ends. Default value is `86400`. +- **serverSessionIdLifetime** - dedicated property to control lifetime of the server side OP session object in seconds. Overrides `sessionIdLifetime`. By default value is `0`, so object lifetime equals `sessionIdLifetime` (which sets both cookie and object expiration). It can be useful if goal is to keep +different values for client cookie and server object. Default value is `86400`. +- **sessionIdUnusedLifetime** - unused OP session lifetime in seconds. If an OP session is not used for a given amount of time, the OP session is removed. +Default value is `86400`. +- **sessionIdUnauthenticatedUnusedLifetime** - lifetime in seconds of `unauthenticated` OP session. This determines how long the user can be on the login page while unauthenticated. Default value is `120`. +- **sessionIdRequestParameterEnabled** - Boolean value specifying whether to enable `session_id` HTTP request parameter. Default value is `False`. +- **sessionIdPersistOnPromptNone** - specifies whether to persist or update the session object with data if `prompt=none`. Default value is `True`. - **invalidateSessionCookiesAfterAuthorizationFlow** - this is special property which specifies whether to invalidate `session_id` and `consent_session_id` cookies right after successful or unsuccessful authorization. +- **changeSessionIdOnAuthentication** - Using a different session after the user authenticates improves security. The default value is `True`. +- **sessionIdPersistInCache** - If True, sessions are stored according to `cacheProviderType`. Otherwise, sessions are persisted in the database. + Default value is `False`. +- **sessionIdPersistInCache** Default value is `False`. For both `unused` properties, Jans Auth Server calculates this period as `currentUnusedPeriod = now - session.lastUsedAt`. So for OP session with states: @@ -50,36 +55,20 @@ For both `unused` properties, Jans Auth Server calculates this period as `curren Jans Auth Server updates `lastUsedAt` property of the session object: -- initially, it is set during creation -- it is updated during each authentication attempt (whether successful or not successful) - -It is important to note that the OP session `lastUsedAt` property is not updated -during RP usage. - -## Logout - -An application may also store its *own* session for the user. Upon logout from the OP, all RPs need to be notified so local sessions can also be cleared/ended. The best way to handle this currently is through "front-channel logout", as described in the [OpenID Connect Front Channel Logout specification](http://openid.net/specs/openid-connect-frontchannel-1_0.html). - -In practice, here's how it works: - - - Jans Auth Server `end_session` endpoint returns an HTML page, which contains an iFrame for each application to which the user has authenticated. - - The iFrame contains a link to each application's respective logout URL. - - The special HTML page should be loaded in the background and not displayed to the user. - - The iFrame URLs should be loaded by the browser. - - Now, upon logout, the user is calling the logout page of each application, the local cookies are cleared, and the user is signed out of all applications. +- During creation +- For each Auth Server authentication attempt (regardless of success) -Learn more about the flow for logout across many applications in the -[logout docs](../openid-features/logout/README.md). +## Killing Sessions -## Session Revocation +The [End Session endpoint](../endpoints/end-session.md) (`/end_session`) +is where the user can end their own session. See [OpenID Logout](../logout/README.md) for more information. -Note, the [End Session endpoint](../endpoints/end-session.md) (`/end_session`) is where the user can end their own session. To end another person's session, you need to use the [Session -Revocation Endpoint](../endpoints/session-revocation.md) (`/revoke_session`). +To end another person's session, Jans Auth Server has a [Session Revocation Endpoint](../endpoints/session-revocation.md) (`/revoke_session`). ## Session Event Interception Script It is possible to add custom business logic as Jans Auth Server detects -different session events. See: +session events, see: * [Application Session](../../../developer/scripts/application-session.md) * [End Session](../../../developer/scripts/end-session.md) @@ -88,8 +77,9 @@ different session events. See: ### How can we force the user to log out if the user is idle on the RP for 4 hours? -The OP doesn't know anything about end-user activity on the RP. Therefore, the RP has to track activity internally, and when the inactivity period is reached (in this case, 4 hours) the RP has to perform front-channel logout. +The OP doesn't know anything about end-user activity on the RP. Therefore, the RP has to track activity internally, and when the inactivity period is reached (in this case, 4 hours) the RP should perform front-channel logout. ### How can we force the user to log out if the browser is closed? -Setting `sessionIdLifetime` to `-1` value sets the `session_id` cookie value to `expires=session`, and sets the OP session object to not have an expiration time. Most browsers clear cookies with `expires=session` when the browser is closed, removing the session object at that time. +Setting `sessionIdLifetime` to `-1` value sets the `session_id` cookie value to `expires=session`, and sets the OP session object to not have an expiration time. Most browsers clear cookies with `expires=session` when the browser is closed, removing the session object at that time. Javascript may be necessary to override +undesirable default browser behavior. diff --git a/docs/admin/auth-server/session-management/idp-v-rp.md b/docs/admin/auth-server/session-management/idp-v-rp.md index f156df4c649..e704e0dfd3f 100644 --- a/docs/admin/auth-server/session-management/idp-v-rp.md +++ b/docs/admin/auth-server/session-management/idp-v-rp.md @@ -5,14 +5,18 @@ tags: - session --- -## This content is in progress +## IDP versus RP session -The Janssen Project documentation is currently in development. Topic pages are being created in order of broadest relevance, and this page is coming in the near future. +Applications generally have their own session cookie (the "RP Session"). +This makes sense, because the RP only redirects to the IDP for authentication +if it cannot find its own local cookie. If a user has a session with many +RP's, achieving simultaneous logout across all sites is a challenge--something +which your business leaders may not appreciate. While OpenID proposes several +solutions to logout, none are idea. Fundamentally, logout is an asynchronous +challenge. A given RP may be disconnected from the network. Thus logout +messages sent to RP's that are not received must be replayed. The +[IETF Sec Events Workgroup](https://datatracker.ietf.org/doc/charter-ietf-secevent/01/) has been working on standards to handle logout (and other asynchronous +requirements). But adoption of this architecture is not common. -## Have questions in the meantime? - -While this documentation is in progress, you can ask questions through [GitHub Discussions](https://github.com/JanssenProject/jans/discussion) or the [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). Any questions you have will help determine what information our documentation should cover. - -## Want to contribute? - -If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/). \ No newline at end of file +Another challenge of RP sessions is that they may have a different timeout +for inactivity. See [Planning Guide Timeout Management](../../planning/timeout-management.md) for more details. diff --git a/docs/admin/auth-server/session-management/multiple-browser-sessions.md b/docs/admin/auth-server/session-management/multiple-browser-sessions.md index f156df4c649..397dca647f4 100644 --- a/docs/admin/auth-server/session-management/multiple-browser-sessions.md +++ b/docs/admin/auth-server/session-management/multiple-browser-sessions.md @@ -5,14 +5,7 @@ tags: - session --- -## This content is in progress +## Multiple Browser Authentication -The Janssen Project documentation is currently in development. Topic pages are being created in order of broadest relevance, and this page is coming in the near future. - -## Have questions in the meantime? - -While this documentation is in progress, you can ask questions through [GitHub Discussions](https://github.com/JanssenProject/jans/discussion) or the [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). Any questions you have will help determine what information our documentation should cover. - -## Want to contribute? - -If you have content you'd like to contribute to this page in the meantime, you can get started with our [Contribution guide](https://docs.jans.io/head/CONTRIBUTING/). \ No newline at end of file +Unfortunately, each browser has its own session cookies, and therefore +its own sessions. diff --git a/docs/admin/auth-server/session-management/multiple-sessions-one-browser.md b/docs/admin/auth-server/session-management/multiple-sessions-one-browser.md index 056a9d371a3..377fcb1abf6 100644 --- a/docs/admin/auth-server/session-management/multiple-sessions-one-browser.md +++ b/docs/admin/auth-server/session-management/multiple-sessions-one-browser.md @@ -3,24 +3,28 @@ tags: - administration - auth-server - session + - Account Chooser --- ## Select Account -AS supports different accounts. To be able select account or login as another user within same user-agent authorization request must have `prompt=select_account`. +A person may have several accounts in a single Jans Auth Server instance. For +example, you may have several diffent Gmail ids. An RP can enable a person +to choose their account by sending an [OpenID Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) with the +parameter `prompt=select_account`. + +For example, following an initial authentication, the session cookie on a person's browser would contain the following data: -When user is logged in cookies looks as: ``` session_id: de510ab6-b06c-4393-86d8-12a7c501aafe current_sessions: ["de510ab6-b06c-4393-86d8-12a7c501aafe"] ``` -If RP sends Authorization Request with `prompt=select_account` and selects hits `Login as another user` button and authenticate then cookies looks as: +Continuing this example, if an RP sent an additional Authentication Request with `prompt=select_account`, Auth Server may return a page enabling the person +to select their account, or even to login as a different account. Once authenticated as a different user, the `current_sessions` cookie would reference +all the current sessions, like this: + ``` session_id: c691e83d-eb1b-41f0-b453-fab905681b5b current_sessions: ["de510ab6-b06c-4393-86d8-12a7c501aafe", "c691e83d-eb1b-41f0-b453-fab905681b5b"] ``` - -AS represents accounts based on `current_sessions` cookies. It may contain outdated references but AS will filter it out and update on request. Thus page represents always actual/active sessions. - -![selectAccount](../img/admin-guide/selectAccount.png) diff --git a/docs/admin/planning/caching.md b/docs/admin/planning/caching.md index 392263aec97..7181044e890 100644 --- a/docs/admin/planning/caching.md +++ b/docs/admin/planning/caching.md @@ -9,7 +9,9 @@ tags: There are two reasons to use caching. First, to improve performance by reducing the number of writes to the disk. Second, to share session data in a clustered deployment. Janssen supports a few different options for -caching. +caching, as controlled by the `cacheProviderType`. Also keep in mind that unless +the `sessionIdPersistInCache` is set to `True`, Auth Server will store sessions +in the database. 1. **In-Memory** If you only have one server, you can use RAM as the cache. Watch the memory usage of Auth Server--if it gets too high you may want to @@ -25,7 +27,7 @@ for caching. 1. **Redis** The best choice if you need a cache service for LDAP, RDBMS, or Spanner. Great performance and low cache miss rate. Commercial Redis -supports TLS, which is a good option if you need secure communication. +supports TLS, which is a good option if you need secure communication. 1. **Memcached** Still a good choice, especially if that's what you already run for other applications. We have observed a slightly higher cache miss diff --git a/docs/admin/planning/timeout-management.md b/docs/admin/planning/timeout-management.md index 6c78d61cdcd..2a13971f8a5 100644 --- a/docs/admin/planning/timeout-management.md +++ b/docs/admin/planning/timeout-management.md @@ -12,7 +12,8 @@ is rarely attainable. Normally the application needs to handle gracefully the case when the IDP session expires first. And if the application session expires first, it may need to trigger a logout event at the OpenID Provider. -Below is a list of some of the timeouts to consider: +Below is a list of some of the Auth Server configuration properties for timeouts +that you should consider: 1. **sessionIdLifetime**: diff --git a/docs/admin/planning/use-cases.md b/docs/admin/planning/use-cases.md index e9f37a1447f..a06e0c32e06 100644 --- a/docs/admin/planning/use-cases.md +++ b/docs/admin/planning/use-cases.md @@ -9,8 +9,8 @@ tags: Web browser SSO is one of the main use cases for Janssen. The OpenID Connect interfaces of the Auth Server provide the identity layer that manages -authentication and B-SSO. Auth Server tracks web browser sessions via a cookie. An -end user may actually have several active sessions, although only one session is +authentication and B-SSO. Auth Server tracks web browser sessions via a cookie. +An end user may actually have several active sessions, although only one session is active. For example, below is a hypothetical session cookie: ``` @@ -162,4 +162,4 @@ to something. Note: Authorizations are stored relative to a person's entity in the database. How a person views and revokes consent is outside the scope of Auth Server. To view a person's consents, you need to use the config API, as this information -is not shared via OpenID Connect or SCIM. \ No newline at end of file +is not shared via OpenID Connect or SCIM.