Java Agents 5.10.3

Logout

This section describes how to trigger a logout based on the properties of a request, and how to redirect users after logout to a specified logout resource.

The URL used to trigger logout can be the agent’s own URL, or one overridden by the configuration. The logout URL is expected to register the session destruction with AM.

The agent maintains the user realm for each session, either by obtaining the realm info from the JWT, or by calling the sessioninfo endpoint (when SSO tokens are used). When the user logs out, the stored realm is passed to the logout endpoint automatically.

AM manages session cookies as follows, and the agent is responsible for destroying the cookies:

  • From AM 7, AM places the session cookie in the Authorization header, prefixed with X-Requester-Token.

  • Before AM 7, AM places the session cookie in the HTTP parameter requester.

If Convert SSO Tokens Into OIDC JWTs is true, the logout URL is invoked twice—once with the JWT, and again with the SSO token. If Enable SSO Token Acceptance is true, the logout URL can be invoked only by an SSO token.

Configure logout with the properties described in Logout.

Trigger logout with a URL

Set the property Logout URI Map to specify a URL to trigger logout. When the URL is invoked, the agent kills the current session by invoking the AM REST logout endpoint or the endpoint configured by Conditional Logout URL List.

The URL is a dummy URL. Even if a resource exists at the URL, it is never accessed.

Log out of a specific web application

The following example triggers a logout from an application called bank, when the URL http://app.example.com:80/mywebapp/bank/log-me-out is invoked:

org.forgerock.agents.logout.endpoint.map[bank]=/bank/log-me-out

When a web application is specified, it must exist and the agent must have access to it. If the bank application in the above example doesn’t exist, the web container throws an error.

Log out of all web applications

If a web application is not specified, the current sessions are killed for all web applications. The following examples trigger a logout from any application when the specified URL is invoked:

org.forgerock.agents.logout.endpoint.map=/agentapp/log-me-out

The agent must be able to access the context for the URL. For example, unless the agent is deployed in the root context, the following configuration fails:

org.forgerock.agents.logout.endpoint.map=/dummy-logout

Trigger logout with a parameter

Set the property Logout Request Parameter Map to specify a URL parameter to trigger logout. The agent searches every incoming request for the parameter. When the agent detects the parameter, it invokes AM to kill the current session for the specified web application.

To speed up the search for a logout parameter, set the property Enable Logout Introspection to true.

Log out of a specific web application

The following example triggers a logout from an application called bank when the request URL contains the parameter log-out:

org.forgerock.agents.logout.request.param.map[bank]=log-out

The request URL must contain the log-out parameter, but does not need to assign a value to the parameter. The following request URLs would trigger a logout for the previous configuration:

http://am.example.com:8080/protectedapp/index.html?log-out
http://am.example.com:8080/examples/index.html?examplelog-out=

Log out of all web applications

If a web application is not specified, the current sessions are killed for all web applications. The following example triggers a logout from any application when the request URL contains the parameter logout:

org.forgerock.agents.logout.request.param.map=logout

Conditionally log out to different URLs

Set the property Conditional Logout URL List to define a URL to which the agent can conditionally direct the user on logout.

If Conditional Logout URL List is set to a URL that does not perform a REST logout to AM, set Always invalidate sessions to true. The agent additionally invokes the AM REST logout endpoint to invalidate the session.

Configure one or more conditions. The request URL is compared to each condition in the list until the closest match is found. Conditions are evaluated by order of length, starting with the longest, irrespective of their order in the list.

In the following example, example.com/path is evaluated before example.com; the default condition is the shortest, and is evaluated last:

org.forgerock.agents.conditional.logout.url.list[0]=example.com|?additional=value
org.forgerock.agents.conditional.logout.url.list[1]=example.com/path|?one=red&two=green&three=blue
org.forgerock.agents.conditional.logout.url.list[2]=mybank.com|http://mybank.com/myapp/logout?param=override
org.forgerock.agents.conditional.logout.url.list[3]=|?alpha=beta

Using the above configuration, consider the following evaluations:

Request URL Action

http://example.com:9010/path/index.html

The following parameter name:value pairs are added to the logout URL: one:red, two:green, and three=blue

http://example.com:9010:/path/public/index.html

http://example.com:9010:/index.html

The following parameter name:value pair is added to the logout URL: additional:value

https://mybank.com:443/path/index.html

http://mybank.com/myapp/logout is used for logout, overriding the AM logout REST endpoint that the agent would use by default.

The administrator is responsible for making sure that the overriding URL kills all tokens associated with login, but is not responsible for removing cookies containing either JWTs or SSO tokens.

Any URL that does not match on of the other conditions

Parameter alpha:beta added to logout URL

Redirect logout to a landing page

Set the property Logout Entry URI Map to redirect users to a specified resource after logout using an endpoint defined in Logout URI Map or Logout Request Parameter Map.

The specified resource can be an HTML page or JSP file. It is automatically added to the not-enforced list, so that it can be accessed without authentication.

Configure a logout landing page for a specific web application

The following example directs requests to the bank application to logout-page.html, after logout:

org.forgerock.agents.logout.goto.map[bank]=/banking-app/logout-page.html

Configure a logout landing page for all web applications

To redirect requests for any web application, leave the web application name field empty, and set the logout URI as a specific URL. The following example directs all requests to goodbye.html after logout:

org.forgerock.agents.logout.goto.map=/agentapp/goodbye.html