Authenticating (Browser)

When authenticating using a browser, you can send AM a realm and also different authentication parameters that would help you customize the user’s experience.

Specifying the Realm in the URL

When making a request to the UI, specify the realm or realm alias as the value of a realm parameter in the query string, or the DNS alias in the domain component of the URL. If you do not use a realm alias, then you must specify the entire hierarchy of the realm. For example: https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha#login/.

The following table demonstrates additional examples:

Options for Specifying the Realm in UI Login URLs
Description Example URL

Full path of the realm as a parameter of XUI

https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha#login

Realm alias of the realm as a parameter of XUI

https://tenant-name.forgeblocks.com/am/XUI/?realm=alpha#login

The DNS alias is overridden by any use of either the full path or a realm alias as a query string parameter.

Authentication Parameters

AM accepts the following parameters in the query string. With the exception of IDToken parameters, use no more than one occurrence of each.

arg=newsession

Request that AM end the user’s current session and start a new session.

ForceAuth

If ForceAuth=true, request that AM force the user to authenticate even if they already have a valid session. On successful authentication, AM does one of the following:

  • (Authentication trees only) AM issues new session tokens to users reauthenticating to meet higher security requirements.

    Users reauthenticating to meet the same security requirements are not issued a new token. AM updates the existing session token with the new authentication information, if required.

  • (Authentication chains only) AM does not issue new session tokens on reauthentication, regardless of the security level they are authenticating to. Instead, it updates the session token with the new authentication information, if required.

goto

On successful authentication, or successful logout, request that AM redirect the user to the specified location. Values must be URL-encoded. See Configuring Success and Failure Redirection URLs for more information.

gotoOnFail

On authentication failure, request that AM redirect the user to the specified location. Values must be URL-encoded. See Configuring Success and Failure Redirection URLs for more information.

locale

Request that AM display the user interface in the specified, supported locale. Locale can also be set in the user’s profile, in the HTTP header from her browser, configured in AM, and so on.

realm

Request that AM authenticate the user to the specified realm.

resource

Set this parameter to true to request resource-based authentication.

Example UI Login URLs

Use any of the options listed in Authentication Parameters as URL parameters. Note that URL parameters must appear before any occurrences of the pound or hash character (#). The following are example URLs with parameters:

Example UI Login URLs
Description Example URL

Log in to the alpha realm, requesting that AM display the user interface in German.

https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha&locale=de#login

Log in to the alpha realm using the myTree authentication tree, requesting that AM display the user interface in German.

https://tenant-name.forgeblocks.com/am/XUI/?realm=/alpha&locale=de&service=myTree#login