PingOne Advanced Identity Cloud

Success and failure redirection URLs

PingOne Advanced Identity Cloud determines the redirection URL based on authentication success or failure.

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

Success URL precedence

When a user authenticates successfully, PingOne Advanced Identity Cloud evaluates the redirection URL according to the following order of precedence:

  1. The URL set in the authentication journey.

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

  2. The URL set in the goto login URL parameter. For example:

    https://<tenant-env-fqdn>/am/login/?realm=/alpha&goto=http%3A%2F%2Fwww.example.com#login

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

    Under Native Consoles > Access Management, go to Realm Name > Identities > identity. In Success URL, 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.

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

    Under Native Consoles > Access Management, go to Realm Name > Authentication > Settings > Post Authentication Processing. In Default Success Login URL, 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 Default Success Login URL in the realm.

Failure URL precedence

When a user fails to authenticate, PingOne Advanced Identity Cloud evaluates the redirection URL according to the following order of precedence:

  1. The URL set in the authentication journey.

    To specify a URL in an authentication journey, add a Failure URL node to the journey and configure the failure URL in the node properties.

  2. The URL set in the gotoOnFail parameter. For example:

    https://<tenant-env-fqdn>/am/login/?realm=/alpha&gotoOnFail=http%3A%2F%2Fwww.example.com#login

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

    Under Native Consoles > Access Management, go 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 realm.

    Under Native Consoles > Access Management, go to Realm Name > Authentication > Settings > Post Authentication Processing. In Default Failure Login URL, 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 realm.

Configure trusted URLs

Redirection URLs can be relative to PingOne Advanced Identity Cloud’s URL, or absolute.

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

To configure PingOne Advanced Identity Cloud to trust other absolute URLs, add them to the validation service. If they are not added, PingOne Advanced Identity Cloud 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 tenant environment URL, https://openam-example-mytenant-usw1.id.forgerock.io:

URL Add to the validation service?

http://openam-example-mytenant-usw1.id.forgerock.io

Yes, the scheme is different.

https://openam-example-mytenant-usw1.id.forgerock.io:8080/login/?realm=/#/

Yes, the port is different.

/login/?authIndexType=service&authIndexValue=mytreename#/

No, the paths relative to the PingOne Advanced Identity Cloud URL are trusted.

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

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

Add a URL to the validation service

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services.

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

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

    For example, https://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, PingOne Advanced Identity Cloud 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, PingOne Advanced Identity Cloud 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 Specify resource patterns with wildcards.

  4. Click Create to save your settings.

Validate a goto URL

To validate a goto URL over REST, use the /json/realms/root/realms/Realm Name/users?_action=validateGoto endpoint. For example:

$ curl \
--request POST \
--header "Accept-API-Version: protocol=2.1,resource=3.0" \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5...ACMDE.*" \
--data '{"goto":"https://www.example.com/"}' \
'https://<tenant-env-fqdn>/am/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.

Copyright © 2010-2024 ForgeRock, all rights reserved.