Web Agents 2023.11.1

AM Conditional Login URL

Conditionally redirect users based on the incoming request URL.

If the incoming request URL matches a domain name in this list, the agent redirects the unauthenticated request to the specified URL for login. The URL can be an AM instance, site, or a different website.

Format, with no spaces between values:

[String]|[URL, URL…​][?realm=value&module=value2&service=value3]

[String]

Incoming login request URLs, with the following values:

  • Domain: Agents match both the domain and its subdomains. For example, example.com matches mydomain.example.com and www.example.com. To combine domain and path, provide the port number: www.example.com:8080/market.

  • Subdomain: For example, example.com. To combine subdomain and path, provide the port number: example.com:8080/market.

  • Path: For example, /myapp.

  • Anything in the request URL: For example, a port, such as 8080.

  • No value: Nothing is specified before the pipe (|) character. Conditional rules that do not specify the incoming request’s domain apply to every incoming request.

To specify the string as a regular expression, configure the following properties instead: Regular Expression Conditional Login Pattern and Regular Expression Conditional Login URL.

[URL, URL…​]

The URL to which incoming login requests are redirected. The URL can be the following:

  • AM instance or site: Specify the URL of an AM instance or site in the format protocol://FQDN[:port]/URI/oauth2/authorize, where the port is optional if it is 80 or 443. For example, https://am.example.com/am/oauth2/authorize.

  • Website other than AM: Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or `443. For example, https://myweb.example.com/authApp.

  • List of AM instances or sites, or websites other than AM: If the redirection URL is not specified, the agent redirects the request to the AM instance or site specified by AM Connection URL.

?realm=/value

The AM realm to where the agent should log the users. For example, ?realm=/marketplace. You do not need to specify the realm in the login URL if any of the following conditions is true:

  • The custom login page sets the realm parameter, for example, because it lets the user chose it. In this case, ensure the custom login page always appends a realm parameter to the goto URL.

  • The realm where the agent must log the user to has DNS aliases configured in AM. AM logs the user in to the realm whose DNS alias matches the incoming request URL. For example, an inbound request from http://marketplace.example.com URL logs into the marketplace realm if the realm alias is set to marketplace.example.com.

  • The users should always log in to the top level realm.

If you specify the realm by default, this parameter can be overwritten by the custom login page if, for example, the user can chose the realm for authentication.

&module=value2&service=value3

Parameters that can be added to the URL(s), such as:

  • module: The authentication module the user authenticates against. For example, ?module=myAuthModule.

  • service: An authentication chain or tree the user authenticates against. For example, ?service=myAuthChain.

  • Any other parameters your custom login pages require.

    Chain parameters with an ampersand (&) character, for example, realm=value&service=value.

When configuring conditional login with multiple URLs, set up the parameters for each URL.

Examples:

com.forgerock.agents.conditional.login.url[0]=example.com|https://am.example.com/am/oauth2/authorize

com.forgerock.agents.conditional.login.url[1]=myapp.domain.com|https://am2.example.com/am/oauth2/authorize?realm=/sales

com.forgerock.agents.conditional.login.url[3]=sales.example.com/marketplace|https://am1.example.com/am/oauth2/authorize?realm=/sales, https://am2.example.com/am/oauth2/authorize?realm=/marketplace

com.forgerock.agents.conditional.login.url[4]=myapp.domain.com|http://mylogin.example.com?realm=/customers

com.forgerock.agents.conditional.login.url[5]=|https://am3.example.com/am/oauth2/authorize?realm=/customers&module=myAuthModule

For more information, refer to Login redirect in the User Guide.

Property name

com.forgerock.agents.conditional.login.url
  Introduced in Web Agent 4.x

Function

Login redirect

Type

String Map

Bootstrap property

No

Required property

No

Restart required

No

AM console

Tab: AM Services

Title: AM Conditional Login URL