Java Agents 2023.11.1

Login redirect

When an unauthenticated user requests access to a protected resource, Java Agent redirects the user’s browser to a login endpoint. The choice of endpoint and the parameters it receives is defined by the login redirect mode, default or custom.

Default login redirect

In default login redirect mode, the property Enable Custom Login Mode is always false. Depending on the configuration of login redirect properties, some endpoint parameters can be changed. For example, the agent can conditionally redirect a request to a specific realm or a different AM instance.

The /oauth2/authorize endpoint returns an OIDC ID token, and this is the only response the agent accepts.

Do not use default login redirect mode if session tokens for authentication and authorization are SSO tokens, even if you intend that the agent converts the SSO tokens into JWTs. Instead, use custom login redirect mode.

The following image shows the flow of data during a default login redirect:

Data flow for default login redirect mode
Figure 1. Data flow for default login redirect mode

Use the request domain to redirect login to a different realm

Set the following properties to redirect login to a different realm based on the domain of the request:

  • Enable Custom Login Mode: Leave with the default value of false.

  • AM Login URL List: Set to the URL of the login page, and specify the login realm as a parameter: https://am.example.com:8443/am?realm=/myrealm

The following image builds on figure 1, to configure AM Login URL List so that the agent redirects the user to log in to myrealm instead of the top-level realm.

Data flow for default login redirect mode, where the user authenticates to a subrealm
Figure 2. Data flow for default login redirect mode, where the user authenticates to a subrealm

Use the request domain to redirect login to a subrealm

Set the following properties to redirect a request to a login realm, based on the request domain:

  • Enable Custom Login Mode: Leave with the default value of false.

  • OAuth Login URL List: Map the request domain to the required login realm. When this property is set, the agent tries to match the request domain to the list of domains in this property. If there is a match, the agent redirects the user to log in at the matched URI.

The following image builds on figure 1, to configure OAuth Login URL List (org.forgerock.agents.oauth.login.url.list). Because the request is for a resource in blue.example.com, it is directed for authentication to the blue realm.

Data flow for default login redirect mode, where the user authenticates to a subrealm based on the request domain
Figure 3. Data flow for default login redirect mode, where the user authenticates to a subrealm based on the request domain

Other requests are directed as follows:

  • Requests for a resource in red.example.com/ruby are passed to the oauth2/authorize endpoint to log the user into the red realm.

  • Requests for a resource in red.example.com/yellow/ are passed to the oauth2/authorize endpoint to log the user into the yellow realm.

  • Requests for a resource in an unmapped domain are passed to the oauth2/authorize endpoint to log the user in to the specified default realm.

Use the request domain to redirect login to different endpoints

In default login redirect mode, the agent can redirect requests to any AM instance supporting the /oauth2/authorize endpoint.

Set the following properties to redirect a request to a different OIDC endpoint, based on the request domain:

  • Enable Custom Login Mode: Leave with the default value of false.

  • OAuth Login URL List: Map the request domain to the required OIDC endpoint. When this property is set, the agent tries to match the request domain to the list of domains in this property. If there is a match, the agent redirects the user to log in at the matched OIDC endpoint.

The following image builds on figure 1, to configure OAuth Login URL List. Because the request is for a resource in red.example.com/yellow, it is directed for authentication to a different IDP.

Data flow for default login redirect mode, where the user authenticates to an identity provider based on the request domain
Figure 4. Data flow for default login redirect mode, where the user authenticates to an identity provider based on the request domain

Requests for a resource in an unmapped domain are passed to the AM oauth2/authorize endpoint, to log the user in to the specified default realm.

Custom login redirect

In custom login redirect mode, the agent is not confined to invoking a fixed endpoint in AM, but can redirect login anywhere. The agent handles JWTs or SSO tokens as session tokens for authentication and authorization.

Use custom login redirect mode for legacy deployments, where SSO tokens, instead of JWTs, are used for authentication and authorization. Otherwise, use default login redirect instead.

The property Enable Custom Login Mode is always true. Depending on the configuration of login redirect properties, the agent can:

  • Convert SSO tokens into JWTs, through a direct "backdoor" call to AM

  • Use caches to stop the SSO to JWT conversion from occurring more than once

  • Leave SSO tokens unconverted

The following image shows the possible data flows for custom login redirect mode:

Data flow for customized login redirect
Figure 5. Data flow for customized login redirect

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 > Java, and select your Java Agent.

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

Redirect login to AM behind a firewall

When login must be completed in a network where AM is behind a firewall, set Public AM URL to a proxy which can access AM.

Limit the number of allowed redirect attempts

To mitigate the risk of infinite redirection loops, limit the number of redirects allowed for a browser session. After this number, the agent blocks the request.

Configure Redirect Attempt Limit, to specify a non-zero value. For example, if the limit is set to three, then the agent blocks the request on the fourth redirect.