Auth Server Guide updates to OpenID Config and Sessions (#3407)

docs/admin/auth-server/endpoints/README.md

@@ -10,4 +10,4 @@ tags:
 Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page.
 
 !!! 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)
+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)

docs/admin/auth-server/endpoints/configuration.md

@@ -5,14 +5,87 @@ tags:
   - endpoint
 ---
 
-## This content is in progress
+## OpenID Configuration Endpoint aka `.well-known/openid-configuration`
 
-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.
+The Configuration Endpoint returns both the OP server metadata, and OAuth
+AS metdata, most of which
+is defined in the [OpenID Discovery Spec](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata), although other configuration metadata is defined
+in other OpenID specifications, or in OAuth specifications.
 
-## Have questions in the meantime?
+If you want to customize the configuration response, you can use the
+[OpenID Config Interception Script](../../developer/scripts/config/openid-config.md),
+which enables you to filter the results, modify claim values, or add claims.
 
-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.
+If you want to explicitly allow only certain OpenID Metadata claims, you can
+supply a list of the claims in the `opConfigMetadataAllowList` Auth Server
+Property.
 
-## Want to contribute?
+Below is a list of all the current available claims, and where they are specified.
 
-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/).
+| Claim | Origin |
+| ----- | -----:|
+|  access_token_signing_alg_values_supported | ? |
+|  acr_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  authorization_encryption_alg_values_supported | ? |
+|  authorization_encryption_enc_values_supported | ? |
+|  authorization_endpoint | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  authorization_signing_alg_values_supported | ? |
+|  backchannel_authentication_endpoint | ? |
+|  backchannel_logout_session_supported | ? |
+|  backchannel_logout_supported | ? |
+|  backchannel_token_delivery_modes_supported | ? |
+|  backchannel_user_code_parameter_supported | ? |
+|  check_session_iframe | ? |
+|  claim_types_supported | ? |
+|  claims_locales_supported | ? |
+|  claims_parameter_supported | ? |
+|  claims_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  clientinfo_endpoint | ? |
+|  device_authorization_endpoint | ? |
+|  display_values_supported | ? |
+|  dpop_signing_alg_values_supported | ? |
+|  end_session_endpoint | ? |
+|  frontchannel_logout_session_supported | ? |
+|  frontchannel_logout_supported | ? |
+|  grant_types_supported | ? |
+|  id_token_encryption_alg_values_supported | ? |
+|  id_token_encryption_enc_values_supported | ? |
+|  id_token_signing_alg_values_supported | ? |
+|  id_token_token_binding_cnf_values_supported | ? |
+|  introspection_endpoint | ? |
+|  issuer | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  jwks_uri | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  op_tos_uri | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  pushed_authorization_request_endpoint | ? |
+|  registration_endpoint | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  request_object_encryption_alg_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  request_object_encryption_enc_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  request_object_signing_alg_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  request_parameter_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  request_uri_parameter_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  require_pushed_authorization_requests | ? |
+|  require_request_uri_registration | ? |
+|  response_modes_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  response_types_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  revocation_endpoint | ? |
+|  scopes_supported | ? |
+|  service_documentation | ? |
+|  session_revocation_endpoint | ? |
+|  ssa_endpoint | Janssen |
+|  subject_types_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  tls_client_certificate_bound_access_tokens | ? |
+|  token_endpoint | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  token_endpoint_auth_methods_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  token_endpoint_auth_signing_alg_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  ui_locales_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  userinfo_encryption_alg_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  userinfo_encryption_enc_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  userinfo_endpoint | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+|  userinfo_signing_alg_values_supported | [OpenID](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) |
+
+## Notes on specific OP Server Metadata claims
+
+* **claims_supported** Each user claim (in Jans jargon, "Attribute") has a property called `jansHideOnDiscovery`--if you don't want a claim to appear in `.well-known/openid-configuration`, set this to `true` for the Attribute entity.
+
+* **ssa_endpoint** This is the endpoint which issues Software Statement
+Assertions JWT's. It is an OAuth protected endpoint.

docs/admin/auth-server/session-management/README.md

@@ -7,7 +7,89 @@ 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.
+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.
 
-!!! 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)
+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.
+- **invalidateSessionCookiesAfterAuthorizationFlow** - this is special property which specifies whether to invalidate `session_id` and `consent_session_id` cookies right after successful or unsuccessful authorization.
+
+For both `unused` properties, Jans Auth Server calculates this period as `currentUnusedPeriod = now - session.lastUsedAt`. So for OP session with states:
+
+- `unauthenticated` - if `currentUnusedPeriod` >= `sessionIdUnauthenticatedUnusedLifetime`, then the session object is removed.
+- `authenticated` - if `currentUnusedPeriod` >= `sessionIdUnusedLifetime`, then the session object is removed.
+
+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.  
+
+Learn more about the flow for logout across many applications in the
+[logout docs](../openid-features/logout/README.md).  
+
+## Session Revocation
+
+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`).
+
+## Session Event Interception Script
+
+It is possible to add custom business logic as Jans Auth Server detects
+different session events. See:
+
+  * [Application Session](../../../developer/scripts/application-session.md)
+  * [End Session](../../../developer/scripts/end-session.md)
+
+## FAQ
+
+### 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.
+
+### 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.

docs/admin/auth-server/session-management/multiple-sessions-one-browser.md

@@ -5,14 +5,22 @@ tags:
   - session
 ---
 
-## This content is in progress
+## Select Account
 
-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.
+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`.
 
-## Have questions in the meantime?
+When user is logged in cookies looks as:
+```
+session_id: de510ab6-b06c-4393-86d8-12a7c501aafe
+current_sessions: ["de510ab6-b06c-4393-86d8-12a7c501aafe"]
+```
 
-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.
+If RP sends Authorization Request with `prompt=select_account` and selects hits `Login as another user` button and authenticate then cookies looks as:
+```
+session_id: c691e83d-eb1b-41f0-b453-fab905681b5b
+current_sessions: ["de510ab6-b06c-4393-86d8-12a7c501aafe", "c691e83d-eb1b-41f0-b453-fab905681b5b"]
+```
 
-## Want to contribute?
+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.
 
-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/).
+![selectAccount](../img/admin-guide/selectAccount.png)

docs/admin/config-guide/jans-cli/cli-jwk-json-web-key-jwk.md

@@ -15,7 +15,7 @@ This operation is used to get the JSON Web Key Set (JWKS) from OP host. The JWKS
 There are few operations we can do using `jans-cli` commands. To get list of operations id run below command:
 
 ```
-/opt/jans/jans-cli/config-cli.py --info ConfigurationJWKJSONWebKeyJWK
+/opt/jans/jans-cli/config-cli.py --info ConfigurationJwkJsonWebKeyJwk
 ```
 
 It returns operations id with details information.
@@ -147,7 +147,7 @@ So, let's get the schema file and update it with keys data:
 }
 ```
 
-Let's update the json file; In our case, I have added sample data for testing purpose only. 
+Let's update the json file; In our case, I have added sample data for testing purpose only.
 
 ```
 "kid": "dd550214-7969-41b9-b919-2a0cfa36047b_enc_rsa1_5",
@@ -174,7 +174,7 @@ Now let's post this keys into the list using below command:
 
 ## Update / Replace JSON Web Key (JWK)
 
-To `update / replace` any JWK configuration, let get the schema first. 
+To `update / replace` any JWK configuration, let get the schema first.
 
 ```
 Operation ID: put-config-jwks

docs/admin/config-guide/tui.md

@@ -25,12 +25,24 @@ OAuth Device Flow for user authentication--the default `admin` user created
 during setup has the correct roles to use all the TUI features. Client
 credentials, tokens and other data is stored in file `~/.config/jans-cli.ini` in
 encoded format. The user-role mappings roles are defined in a Jans Auth Server
-[introspection scrip](https://github.com/JanssenProject/jans/blob/main/docs/script-catalog/introspection/introspection-role-based-scope/introspection_role_based_scope.py)
+[introspection script](https://github.com/JanssenProject/jans/blob/main/docs/script-catalog/introspection/introspection-role-based-scope/introspection_role_based_scope.py)
 
 ```
 ~/.config/jans-cli.ini
 ```
 
+## Plugins
+
+It's possible to extend the TUI by writing a plugin. Each plugin is loaded
+dynamically according to the numeric priority of the folders in
+`/opt/jans/jans-cli/plugins`. To enable a plugin, you need to edit
+`jans-cli.ini`. The default plugins are:
+
+```
+jca_plugins = user-mgt,scim,fido2,admin-ui
+
+```
+
 ## Administration
 
 When you run the TUI, this is the home panel: