Success and failure redirection URLs

AM determines the redirection URL based on authentication success or failure.

You can configure success and failure URLs in a number of places in AM. For each authentication outcome, the user is redirected to the URL with the highest precedence, which is determined by where it is defined in AM.

Success URL precedence

When a user authenticates successfully, AM evaluates the redirection URL according to the following order of precedence:

The URL set in the authentication chain or authentication tree.
- To specify a URL in an authentication tree, add a Success URL node to the tree and configure the Success URL in the node properties.
- To specify a URL in an authentication chain, in the AM admin UI, go to Realm Name > Authentication > Chains > chain > Settings. Enter a URL in the Successful Login URL field and save your changes.
The URL set in the goto login URL parameter. For example:

https://openam.example.com:8443/openam/XUI/?realm=/alpha&goto=http%3A%2F%2Fwww.example.com#login
The URL set in the Success URL attribute in the user’s profile.

In the AM admin UI, go to Realm Name > Identities > identity. In the Success URL field, enter a URL, and save your changes.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it takes precedence over a regular URL in the user’s profile.
The URL set in the Default Success Login URL attribute in the Top Level Realm.

Go to Configure > Authentication > Core Attributes > Post Authentication Processing. In the Default Success Login URL field, enter a URL, and save your changes.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a Default Success Login URL in the Top Level realm.

Failure URL precedence

When a user fails to authenticate, AM evaluates the redirection URL according to the following order of precedence:

The URL set in the authentication chain or authentication tree.
- To specify a URL in an authentication chain, in the AM admin UI, go to Realm Name > Authentication > Chains > chain > Settings. Enter a URL in the Failed Login URL field and save your changes.
- To specify a URL in an authentication tree, add a Failure URL node to the tree and configure the failure URL in the node properties.
The URL set in the gotoOnFail parameter. For example:

https://openam.example.com:8443/openam/XUI/?realm=/alpha&gotoOnFail=http%3A%2F%2Fwww.example.com#login
The URL set in the Failure URL attribute in the user’s profile.

In the AM admin UI, go to Realm Name > Identities > identity. In the Failure URL field, enter a URL, and save your changes.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a regular URL in the user’s profile.
The URL set in the Default Failure Login URL attribute in the Top Level Realm.

In the AM admin UI, go to Configure > Authentication > Core Attributes > Post Authentication Processing. In the Default Failure Login URL field, enter a URL, and save your changes.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a Default Failure Login URL in the Top Level realm.

Configure trusted URLs

Redirection URLs can be relative to AM’s URL, or absolute.

By default, AM trusts all relative URLs and those absolute URLs that are in the same scheme, FQDN, and port as AM. This increases security against possible phishing attacks through an open redirect.

To configure AM to trust other absolute URLs, add them to the validation service. If they are not added, AM will redirect to the user profile or to the administrator console on log in, and to the default logout page in the UI on log out.

Do I need to add my URL to the validation service?

Consider these example URLS for a deployment configured at https://am.example.com:8443/am:

URL Add to the validation service?

URL	Add to the validation service?
`http://am.example.com:8080/am/XUI/#login`	Yes, the scheme and port are different.
`https://am.example.com:443/am/XUI/#login`	Yes, the port is different.
`/am/XUI/#login`	No, the paths relative to the AM URL are trusted.
`https://mypage.example.com/app/logout.jsp`	Yes, the scheme, port, and FQDN are different.

http://am.example.com:8080/am/XUI/#login

Yes, the scheme and port are different.

https://am.example.com:443/am/XUI/#login

Yes, the port is different.

/am/XUI/#login

No, the paths relative to the AM URL are trusted.

https://mypage.example.com/app/logout.jsp

Yes, the scheme, port, and FQDN are different.

Add a URL to the validation service

In the AM admin UI, go to Realms > Realm Name > Services.

Note that you can add an instance of the validation service on the Top Level Realm, too.
If the Validation Service is not in the list of services, configure a new service:
1. Click Add a Service.
2. From the Choose a service type drop-down list, select Validation Service.
In the Valid goto URL Resources field, enter one or more valid URL patterns to allow.

For example, http://app.example.com:80/*?*.
General examples of URL pattern matching
- If no port is specified, http://www.example.com canonicalizes to http://www.example.com:80 and https://www.example.com canonicalizes to https://www.example.com:443.
- A wildcard before "://" only matches up to "://"
  
  For example, http*://*.com/* matches http://www.example.com/hello/world and https://www.example.com/hello.
- A wildcard between "://" and ":" matches up to ":"
  
  For example, http://*:85 matches http://www.example.com:85.
- A wildcard between ":" and "/" only matches up to the first "/"
  
  For example, http://www.:/ matches http://www.example.com:80. In another example, http://www.example.com:* matches http://www.example.com:<any port> and http://www.example.com:<any port>, but nothing more.
- A wildcard after "/" matches anything, depending on whether it is single-level or a wildcard appropriately.
  
  For example, https://www.example.com/* matches https://www.example.com:443/foo/bar/baz/me.
- If you do not use any wildcards, AM exactly matches the string, so http://www.example.com only matches http://www.example.com, but NOT http://www.example.com/ (trailing slash).
  
  If you put the wildcard after the path, AM expects a path (even if it is blank), so http://www.example.com/* matches http://www.example.com/ and http://www.example.com/foo/bar/baz.html, but NOT http://www.example.com.
- http://www.example.com:*/ matches http://www.example.com/, which also canonicalizes to http://www.example.com:80/.
- https://www.example.com:*/ matches https://www.example.com/, which also canonicalizes to https://www.example.com:443/.
For more information on pattern matching and wildcard rules, refer to Specifying resource patterns with wildcards.
Click Create to save your settings.

Validate a `goto` URL

To validate a goto URL over REST, use the /json/users?_action=validateGoto endpoint (or /json/realms/root/realms/_Realm Name_/users?_action=validateGoto to specify a sub realm). For example:

$ curl \
--request POST \
--header "Accept-API-Version: protocol=2.1,resource=3.0" \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5…ACMDE.*" \
--data '{"goto":"https://www.example.com/"}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users?_action=validateGoto'
{
    "successURL":"https://www.example.com/"
}

If the URL is valid, the endpoint returns the specified URL as the successURL response parameter.

A goto URL is considered valid if one of the following is true:

The URL is configured in the validation service
The URL is relative
The URL is encoded

Encoded URLs are treated as relative URLs for the purposes of validation. To be treated as an absolute URL, the URL must not be encoded.

If the specified URL is invalid, the endpoint returns the default success URL.

Note that a valid session is optional; you can still call the validateGoto endpoint with an expired session.

PingAM 7.5.0