Web Agents 2024.3

Login redirect

When an unauthenticated user requests access to a protected resource, the agent redirects the user to log in. The choice of the login endpoint, and the parameters it receives, is defined by the login redirect mode and whether the agent accepts SSO tokens and ID tokens as session cookies.

Configure login redirect options as follows:

0

1

0

  • Does not accept SSO tokens as session cookies.

  • Accepts SSO tokens and ID tokens as session tokens during and after the login flow.

  • Does not convert SSO tokens to ID tokens.

1

  • Redirects login to the originally requested resource.

  • Converts SSO tokens to ID tokens.

  • Configure AM Login URL to point to a custom login page.

  • (Optional) Configure AM Conditional Login URL to point to the same URL as AM Login URL with additional parameters such as the login realm. Requests are logged conditionally to this URL.

  • Do not configure AM Conditional Login URL or AM Login URL to point to the AM admin UI or the AM oauth2/authorize URL.

  • Not supported.

2

  • Not supported.

  • This non-standard flow has limitations. Use only for environments migrating from earlier versions of the agent.

  • Redirects login with a goto query parameter to the originally requested resource

  • Accepts SSO tokens

  • Configure AM Login URL to point to a custom login page

  • (Optional) Configure AM Conditional Login URL to point to the same URL as AM Login URL with additional parameters such as the login realm. Requests are logged conditionally to this URL.

  • Do not configure AM Conditional Login URL or AM Login URL to point to the AM admin UI or the AM oauth2/authorize URL.

Default login redirect

In default login redirect, the agent redirects users for authentication to a page on the AM admin UI. The agent uses OpenID Connect ID JTWs as session tokens. Default login always redirects users to the top-level realm, irrespective of the user realm.

The following image shows the flow of data during a default login redirect. When an unauthenticated user requests access to a protected resource. The agent wraps the SSO session token inside an OpenID Connect JWT. Authentication requires access to the /oauth2/authorize endpoint, which invokes the AM admin UI and other endpoints such as oauth2/authorize, json/authenticate, json/sessions, json/serverinfo, and XUI/*.

login-redirection-default

Custom login redirect

In custom login redirect, the agent can redirect login in the following ways:

  • Redirect login to custom login pages, in the same or a different realm

  • Conditionally redirect login to different AM instances, AM sites, or authentication realms, based on the request URL.

  • Use AM-specific SSO tokens as session tokens

Same domain custom login redirect

The agent redirects unauthenticated users to a custom login page in the same domain, adding the original_request_url parameter to the redirect. The parameter records the requested URL, which can then be used by custom login application or page.

The custom login page posts an SSO token to agent/custom-login-response, with the realm as an optional parameter, and sets an SSO token in the same domain as the agent.

The agent attempts to validate the SSO token against the AM endpoints.

At the end of the login flow, the agent can do the final redirect to the protected resource, or to the originally requested resource, with a goto query parameter

Same domain custom login redirect with final redirect to the protected resource

Set the following properties:

If the custom login page is a part of the agent’s protected application, add the custom login pages to the not-enforced lists.

The following image shows the data flow for a custom login redirect when the custom login pages are in the same domain as the agent, and the agent redirects the the request to the originally requested resource.

login-redirection-custom1-accepttoken0

Same domain custom login redirect with final redirect to the originally requested resource (migration mode)

Use this mode to migrate from Web Agents Documentation 4 to Web Agents Documentation 5.

Set the following properties:

The agent redirects the client with a goto query parameter to the originally requested resource. This mode only operates on HTTP GET requests; POST requests are not supported.

The custom login pages obtain the SSO token from AM, but the agent does not create the pre-authentication cookie, which is used (among other things) to protect against CSRF attacks.

Because part of this flow happens outside the agent’s control, the SSO token can expire or become invalid before the agent validates it. If so, the user/client must re-authenticate.

Cross-domain custom login redirect

The agent redirects unauthenticated users to a custom login page in a different domain, including the original-request-uri parameter in the redirect. The parameter records the requested URL, which can then be used by custom login application or page.

The custom login page provides a custom-login-response, and sets an SSO token, which can be accessed only in that domain. Because the agent cannot access the cookie, it redirects to AM for the Default login redirection mode.

Depending on your environment, the agent can contact AM to validate the cookie even if it cannot detect it. In other cases, you need to configure an additional property.

If AM can validate the SSO token, it returns an ID token as part of the default redirection login flow.

Consider the following points:

  • Ensure that the login pages do not set the SSO token cookie with the SameSite=Strict attribute.

  • If AM cannot validate the SSO token (for example, because it cannot recognize the domain set for the cookie), it redirects the end user to authenticate again using the Default login redirection mode.

  • AM must be visible to the custom login pages, either because they both are in the same network/domain, or because you exposed the relevant AM endpoints using a proxy:

Cross-domain custom login redirect on a shared network

On a shared network, the server where AM is running has two interfaces: one connected to the internal network, where the agent is, and another connected to the external network, where the custom login pages are.

Use the following properties to configure this scenario:

The following image illustrates the environment. The web server housing the protected resources can be connected to the external network in different ways; with two interfaces, or through a proxy. It is not important for the purposes of custom login, so it is not shown.

The agent and the custom login pages are on different domains. There is no proxy between AM and the custom login pages

The following image shows the data flow:

login-redirection-custom1-different-domain

Cross-domain custom login redirect with AM behind a proxy

The server where AM is running has one interface to the internal network, where the agent is. A proxy hides AM from the external network, which forwards traffic to the /oauth2/authorize endpoint.

Use the following properties to configure this scenario:

The following image illustrates the environment. The web server where the protected resources are may be connected to the external network in different ways; with two interfaces, or through a proxy. It is not important for the purposes of custom login, so it is not shown in the following diagram:

The agent and the custom login pages are on different domains. There is a proxy between AM and the custom login pages.

The following image shows the data flow:

login-redirection-custom1-different-domain-publicAM

Conditional login redirect

Use conditional redirects to redirect the end user to different AM instances or sites, or to different custom pages, depending on the incoming request URL.

Conditionally redirect login by domain name

When the incoming request URL matches a specified domain name, configure the following properties to redirect to a specified URL:

The following image shows the data flow when a requests to the domain customers.example.com are redirected to the customers realm. Other requests are redirected to the top-level realm.

login-redirection-default-conditional

Conditionally redirect login by matching regular expressions

When the incoming request URL matches a regular expression, configure the following properties to redirect to a specified URL:

In the following example, when the request matches the regular expression .*shop, the agent redirects it to the sales realm for authentication:

org.forgerock.openam.agents.config.allow.custom.login = 0
org.forgerock.agents.config.conditional.login.pattern[0] = .*shop
org.forgerock.agents.config.conditional.login.url[0] = http://am.example.com/am/oauth2/authorize?realm=sales

Redirect login to a custom URL configured in AM

AM’s OAuth2 Provider service can be configured to use a custom URL to handle login, to override the default AM login page. When a custom login page is configured in AM, configure the agent to ensure that it redirects the login to that page.

  1. In the AM admin UI, go to Services > OAuth2 Provider > Advanced > Custom Login URL Template, and note the custom URL.

  2. Go to Applications > Agents > Web, and select your Web Agents Documentation.

  3. On the AM Services tab set the following properties: