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:
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.
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.
Other requests are directed as follows:
-
Requests for a resource in
red.example.com/rubyare passed to theoauth2/authorizeendpoint to log the user into the red realm. -
Requests for a resource in
red.example.com/yellow/are passed to theoauth2/authorizeendpoint to log the user into the yellow realm. -
Requests for a resource in an unmapped domain are passed to the
oauth2/authorizeendpoint 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.
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:
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.
-
In the AM admin UI, go to Services > OAuth2 Provider > Advanced > Custom Login URL Template, and note the custom URL.
-
Go to Application > Agents > Java, and select your Java Agent.
-
On the AM Services tab set the following properties:
-
Enable Custom Login Mode: Set to on
-
AM Login URL List: 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 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.