--- title: Success and failure redirection URLs description: AM determines the redirection URL based on authentication success or failure. component: pingam version: 8.1 page_id: pingam:am-authentication:redirection-url-precedence canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/redirection-url-precedence.html keywords: ["Authentication", "Realms", "REST API"] page_aliases: ["authentication-guide:redirection-url-precedence.adoc"] section_ids: success-url-precedence: Success URL precedence failed-url-precedence: Failure URL precedence configure-trusted-urls: Configure trusted URLs configure-validation-service: Add a URL to the validation service validate_a_goto_url: Validate a goto URL --- # 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. AM redirects the user to the URL with the highest precedence, determined by where it's defined in AM. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | By default, the maximum length of redirection URLs is 2000 characters. If your redirection URLs are longer than this, you should increase the value of the [org.forgerock.openam.redirecturlvalidator.maxUrlLength](../setup/server-advanced.html#org.forgerock.openam.redirecturlvalidator.maxUrlLength) advanced server property as needed. | ## Success URL precedence When a user authenticates successfully, AM evaluates the redirection URL according to the following order of precedence: 1. The URL set in the `goto` login URL parameter. For example: `https://am.example.com:8443/am/XUI/?realm=/alpha&goto=http%3A%2F%2Fwww.example.com#login` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Unless the URLs are in the same domain as PingAM, any URLs specified in the `goto` parameter must be explicitly listed in the [Valid `goto` URL Resources](../setup/services-configuration.html#valid-goto-urls) property of the Validation Service. Otherwise, they're ignored. | 2. The URL set in the authentication tree. Add a [Success URL node](https://docs.pingidentity.com/auth-node-ref/8.1/success-url.html) to the tree and configure the Success URL in the node properties. 3. The URL set in the Success URL attribute in the user's profile. 1. In the AM admin UI, go to *realm name* > Identities > *identity*. 2. In the Success URL field, enter a URL, and save your changes. 4. The URL set in the Default Success Login URL attribute in the Top Level Realm. 1. Go to Configure > Authentication > Core Attributes > Post Authentication Processing. 2. In the Default Success Login URL field, enter a URL, and save your changes. ## Failure URL precedence When a user fails to authenticate, AM evaluates the redirection URL according to the following order of precedence: 1. The URL set in the `gotoOnFail` parameter. For example: `https://am.example.com:8443/am/XUI/?realm=/alpha&gotoOnFail=http%3A%2F%2Fwww.example.com#login` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Unless the URLs are in the same domain as PingAM, any URLs specified in the `gotoOnFail` parameter must be explicitly listed in the [Valid goto URL Resources](../setup/services-configuration.html#valid-goto-urls) property of the Validation Service. Otherwise, they're ignored. | 2. The URL set in the authentication tree. Add a [Failure node](https://docs.pingidentity.com/auth-node-ref/8.1/failure.html) to the tree and configure the failure URL in the node properties. 3. The URL set in the Failure URL attribute in the user's profile. 1. In the AM admin UI, go to *realm name* > Identities > *identity*. 2. In the Failure URL field, enter a URL, and save your changes. 4. The URL set in the Default Failure Login URL attribute in the Top Level Realm. 1. In the AM admin UI, go to Configure > Authentication > Core Attributes > Post Authentication Processing. 2. In the Default Failure Login URL field, enter a URL, and save your changes. ## Configure trusted URLs Redirection URLs can be relative to AM's URL, or absolute. By default, AM trusts all relative URLs and absolute URLs with 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](#configure-validation-service). If they're not listed there, AM redirects the end user to their profile and admin users to the AM admin UI on login. AM redirects to the default logout page in the UI on log out. > **Collapse: 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? | > | ------------------------------------------- | ------------------------------------------------- | > | `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. | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | By default, the maximum length of redirection URLs is 2000 characters. If your redirection URLs are longer than this, you should increase the value of the [org.forgerock.openam.redirecturlvalidator.maxUrlLength](../setup/server-advanced.html#org.forgerock.openam.redirecturlvalidator.maxUrlLength) advanced server property as needed. | ### Add a URL to 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. 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, `http://app.example.com:80/*?*`. > **Collapse: 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:` and `http://www.example.com:`, 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](../am-authorization/resource-types-ui.html#policy-patterns-wildcards). 4. 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: ```bash $ 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://am.example.com:8443/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.