Java Agents 2024.6

OAuth Login URL List

Use only when Enable Custom Login Mode is false and AM Login URL List is empty.

Specify rules to evaluate the incoming request URL, based on domain, path, request header, or query parameters. Specify a URL for login redirect with optional parameters.

Format, with no spaces between values:

[domain/path][header:value][?param=value[,param=value]]|[URL][?param=value&param=value]

When an unauthenticated request URL matches a rule specified by this property, the agent redirects the request to the specified URL for login.

When this property configures multiple rules, the agent sorts the rules into the following order and applies them in that order until it finds a match:

  1. Header specification - a rule with a header specification is applied before other rules

  2. Longest domain

  3. Longest path

  4. Highest number of parameter specifications

During redirect, the agent appends the goto parameter configured in Goto Parameter Name, and a nonce parameter, to the agent’s CDSSO endpoint. If Enable FQDN Checking is true, the agent iterates through the list of URLs until it finds a redirect URL that matches the FQDN check values. Otherwise, the agent redirects the user to the URL configured in the conditional redirect rules.

[domain/path]

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain and its subdomains. For example, example.com matches mydomain.example.com and www.example.com. Domains can also include path information, for example, example.com/market, but cannot specify ports.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

[header:value]

One header/value pair provided in the incoming request. If the header value is not provided, the header can take any value. For example:

Requests containing a header called X-local with the value provided are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|

Requests containing a header called X-local with any value are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:|

[?param=value[,param=value]

One or more parameter and value pairs provided in the incoming request. If the parameter value is not provided, the parameter can take any value. For example:

Requests containing a parameter called site with the value shopping are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|

Requests containing a parameter called target`with the value `cooking AND a parameter called price with the value low are redirected to the default URL:+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking,price=low|

[URL]

The login URL. The URL can be an AM instance, an AM site, or a 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/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If [URL] is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

[?param=value&param=value]

One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example, realm=value&parameter1=value1&parameter2=value2.

When the parameter is ?realm=value it specifies the AM realm into which the agent logs the users. For example, ?realm=marketplace.

When redirecting to AM’s XUI, use an ampersand (&) instead of a question mark (?). For example, https://am.example.com:8443/openam/XUI/#login/&realm=marketplace.

A realm parameter is not required in the login URL when any of the following conditions are true:

  • The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

  • The realm that the agent is logging the user into has DNS aliases configured in AM.

  • AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The users should always log in to the Top Level Realm.

Examples

+

Requests containing a header called X-local with the value provided are redirected to the specified URL in the beta realm:

+

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|http://mysite.local.com:8081/login?realm=beta

+

Requests containing a header called X-local with any value are redirected to the default URL in the gamma realm:

+

org.forgerock.agents.oauth.login.url.list[1]= X-local:|?realm=gamma

+

Requests containing a parameter called site with the value shopping AND a parameter called mode with the value discount are redirected to the default URL in the discountshopping realm:

+

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping,mode=discount|?realm=discountshopping

+

Requests containing a parameter called target with the value cooking are redirected to the AM XUI page in the kitchen realm. Note the use of & before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://am.example.com:8443/openam/XUI/#login/&realm=kitchen

+

Requests containing a parameter called target with the value cooking are redirected to a non-AM login page in the kitchen realm. Note the use of ? before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://mysite.example.com:8443/login/?realm=kitchen

Property name

org.forgerock.agents.oauth.login.url.list

Aliases

org.forgerock.agents.oauth.login.url.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: OAuth Login URL List

Legacy title: AM Conditional Login URL