Access Management 7.2.2

Configure success and failure redirection URLs

AM determines the redirection URL based on authentication success or failure. During success, AM redirects the user to the URL specified in the goto parameter and, during failure, AM redirects the user to the URL specified in the gotoOnFail parameter.

AM provides a number of places where you can configure success or failure URLs:

Successful authentication URL precedence, and where to configure success URLs

Upon a successful authentication, AM determines the redirection URL in the following order:

  1. The URL set in the authentication chain or authentication tree.

    • To specify a URL in an authentication chain, in the AM admin UI, set the Successful Login URL parameter by navigating to Realm Name > Authentication > Chains > chain > Settings.

    • To specify a URL in an authentication tree, add a Success URL node to the tree and specify the Success URL in the node properties.

  2. 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

  3. The URL set in the Success URL attribute in the user’s profile.

    In the AM admin UI, you can set the Success URL parameter by navigating to Realm Name > Identities > identity. In Success URL, enter a URL, and click Save 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.

  4. The URL set in the Default Success Login URL attribute in the Top Level realm.

    You can set this property on the AM admin UI by navigating to Configure > Authentication > Core Attributes > Post Authentication Processing.

    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.

Failed authentication URL precedence, and where to configure failure URLs

Upon a failed authentication, AM determines the redirection URL in the following order:

  1. The URL set in the authentication chain or authentication tree.

    • To specify a URL in an authentication chain, in the AM admin UI, set the Failed Login URL parameter by navigating to Realm Name > Authentication > Chains > chain > Settings.

    • To specify a URL in an authentication tree, add a Failure URL node to the tree and specify the Failure URL in the node properties.

  2. 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

  3. The URL set in the Failure URL attribute in the user’s profile.

    In the AM admin UI, you can set the Failure URL parameter by navigating to Realm Name > Identities > identity. Under Failure URL, enter a URL, and click Save 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.

  4. The URL set in the Default Failure Login URL attribute in the Top Level realm.

    You can set this property on the AM admin UI by navigating to Configure > Authentication > Core Attributes > Post Authentication Processing.

    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.

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 open redirect.

To configure AM to trust other absolute URLs, add them to the Validation Service. If you do not, on login AM will redirect to the user profile or to the administrator console, and on logout to the default logout page in the UI instead.

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

Consider an example AM deployment configured in https://am.example.com:8443/am:

URL Needs to be configured in 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.

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

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

Configure the Validation service

  1. 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.

  2. Click Add a Service.

  3. From the Choose a service type list, select Validation Service.

  4. In the Valid goto URL Resources field, enter one or more valid URL patterns to allow.

    For example, http://app.example.com:80/*?*.

    For information on pattern matching and wildcard rules, see Specifying resource patterns with wildcards.

    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/.

  5. 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":"http://www.example.com/"}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/users?_action=validateGoto'
{
    "successURL":"http://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.