Java Agents 2024.6

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 redirection resource.

The resource to trigger logout can be the agent URL or a URL overridden by the configuration. The agent expects the logout to register 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:

https://am.example.com:8443/protectedapp/index.html?log-out
https://am.example.com:8443/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 Conditional Logout URL List to define URLs to which the agent can conditionally direct the user on logout.

Configure one or more conditions. The agent compares the request URL to each condition in the list to find the closest match. It evaluates conditions in order of length, starting with the longest, irrespective of their position in the list.

Depending on the value of the redirection URL, perform this additional configuration:

  • If the URL doesn’t 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.

  • If the URL isn’t relative to AM or in the same scheme, FQDN, and port, add it to the AM validation service.

    For more information, refer to Advanced Identity Cloud’s Configure trusted URLs or AM’s Configure trusted URLs.

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 Logout Entry URI Map to redirect users to a specified resource after logout. Use this property for logout triggered by Logout URI Map or Logout Request Parameter Map.

The redirection resources can be HTML pages or JSP files. They are automatically added to the not-enforced list so that they can be accessed without authentication.

Depending on the type and value of a redirection resource, perform this additional configuration:

  • If it is a URL that doesn’t 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.

  • If it is a URL that isn’t relative to AM or in the same scheme, FQDN, and port, add it to the AM validation service.

    For more information, refer to Advanced Identity Cloud’s Configure trusted URLs or AM’s Configure trusted URLs.

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