---
title: Login redirect
description: 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.
component: java-agents
version: 2025.11
page_id: java-agents:user-guide:login-redirect
canonical_url: https://docs.pingidentity.com/java-agents/2025.11/user-guide/login-redirect.html
section_ids:
  login-redirect-default: Default login redirect
  login-redirect-realm: Use the request domain to redirect login to a different realm
  login-redirect-realm-domain: Use the request domain to redirect login to a subrealm
  use_the_request_domain_to_redirect_login_to_different_endpoints: Use the request domain to redirect login to different endpoints
  login-redirect-custom: Custom login redirect
  login-redirect-am-custom-url: Redirect login to a custom URL configured in AM
  redirect_login_to_am_behind_a_firewall: Redirect login to AM behind a firewall
  redirect-limit: Limit the number of allowed redirect attempts
---

# 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](../properties-reference/org.forgerock.agents.legacy.login.enabled.html) is always `false`. Depending on the configuration of [login redirect properties](../properties-reference/preface.html#default_login_redirect), some endpoint parameters can be changed. For example, the agent can conditionally redirect a request to a specific realm or a different AM instance.

To redirect login to a specific authentication tree, add the `service` parameter, for example: `https://am.example.com:8443/am/oauth2/realms/root/realms/alpha/authorize?service=myTree` would authenticate users using an authentication tree called `myTree`.

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

**Don't** use default login redirect mode if session tokens for authentication and authorization are SSO tokens, even if the agent converts SSO tokens into JWTs. Instead, use [custom login redirect mode](#login-redirect-custom).

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

![Flow of a request through default login.](_images/login-default.svg)

### 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](../properties-reference/org.forgerock.agents.legacy.login.enabled.html): Leave with the default value of `false`.

* [AM Login URL List](../properties-reference/com.sun.identity.agents.config.login.url.html): Set to the URL of the login page, and specify the login realm as a parameter: `https://am.example.com:8443/am?realm=/alpha`

The following image builds on [figure 1](#image-login-redirect-default), to configure [AM Login URL List](../properties-reference/com.sun.identity.agents.config.login.url.html) so that the agent redirects the user to log into the `alpha` realm instead of the top-level realm.

![Flow of a request through default login to a subrealm.](_images/login-default-realm.svg)

### 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](../properties-reference/org.forgerock.agents.legacy.login.enabled.html): Leave with the default value of `false`.

* [OAuth Login URL List](../properties-reference/org.forgerock.agents.oauth.login.url.list.html): 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's a match, the agent redirects the user to log in at the matched URI.

The following image builds on [figure 1](#image-login-redirect-default), to configure [OAuth Login URL List](../properties-reference/org.forgerock.agents.oauth.login.url.list.html) (`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.

![Flow of a request through default login](_images/login-default-realm-blue.svg)

Other requests are directed as follows:

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

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

* Requests for a resource in an unmapped domain are passed to the `oauth2/realms/root/realms/alpha/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](../properties-reference/org.forgerock.agents.legacy.login.enabled.html): Leave with the default value of `false`.

* [OAuth Login URL List](../properties-reference/org.forgerock.agents.oauth.login.url.list.html): 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's a match, the agent redirects the user to log in at the matched OIDC endpoint.

The following image builds on [figure 1](#image-login-redirect-default), to configure [OAuth Login URL List](../properties-reference/org.forgerock.agents.oauth.login.url.list.html). Because the request is for a resource in `red.example.com/yellow`, it is directed for authentication to a different IdP.

![Flow of a request through default login](_images/login-default-endpoint.svg)

Requests for a resource in an unmapped domain are passed to the AM `oauth2/realms/root/realms/alpha/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](#login-redirect-default) instead.

The property [Enable Custom Login Mode](../properties-reference/org.forgerock.agents.legacy.login.enabled.html) is always `true`. Depending on the configuration of [login redirect properties](../properties-reference/preface.html#custom_login_redirect), 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](_images/login-custom.svg)

### 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:

   * [Enable Custom Login Mode](../properties-reference/org.forgerock.agents.legacy.login.enabled.html): Set to on

   * [AM Login URL List](../properties-reference/com.sun.identity.agents.config.login.url.html): Set to the custom URL in step 1.

## 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](../properties-reference/org.forgerock.agents.public.am.url.html) 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](../properties-reference/org.forgerock.agents.redirect.attempt.limit.html), 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.