Jans docs mike auth server 02

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)
+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.  

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.

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/).
+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.

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/).
+Unfortunately, each browser has its own session cookies, and therefore
+its own sessions.

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)

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

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**:
 

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.
+is not shared via OpenID Connect or SCIM.