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 |
|
||
|
|
||
1 |
|
|
|
2 |
|
|
|
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/*.
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:
-
Enable Custom Login Mode as
1, to use the OIDC-compliant custom login redirection mode -
AM Login URL, to the URL of the custom login page
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.
Same domain custom login redirect with final redirect to the originally requested resource (migration mode)
| Use this mode to migrate from Web Agent 4 to Web Agent 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:
-
Ensure that the login pages do not set the SSO token cookie with the
SameSite=Strictattribute. -
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 following image shows the data flow:
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 following image shows the data flow:
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.
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=salesRedirect 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 Applications > Agents > Web, and select your Web Agent.
-
On the AM Services tab set the following properties:
-
Enable Custom Login Mode: Set to
1. -
AM Conditional Login URL: Set to the custom URL in step 1.
-