PingAM 8.0.0

Authenticate with a browser

When using AM’s extended user interface (XUI), the base URL to authenticate to points to /XUI/#login under the deployment URL, such as https://am.example.com:8443/am/XUI/#login.

The base URL to log out is similar, for example, https://am.example.com:8443/am/XUI/#logout/.

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.

Specify 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 don’t use a realm alias, you must specify the entire hierarchy of the realm. For example: https://am.example.com:8443/am/XUI/?realm=/customers/europe#login/.

The following table demonstrates additional examples:

How to specify the realm in UI login URLs
Description Example URL

Full path of the realm as a parameter of XUI

https://am.example.com:8443/am/XUI/?realm=/customers/europe#login

Realm alias of the realm as a parameter of XUI

https://am.example.com:8443/am/XUI/?realm=alpha#login

DNS Alias of the realm as the fully qualified host name in the URL

https://myRealm.example.com:8443/am/XUI/#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. Except for the IDToken parameters, don’t set a parameter more than once in a single query.

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.

When ForceAuth=true, on successful authentication, AM issues new session tokens to users on reauthentication, even if the current session already meets the security requirements.

goto

On successful authentication, or successful logout, request that AM redirect the user to the specified location. Values must be URL-encoded. For more information, refer to Success and failure redirection URLs.

gotoOnFail

On authentication failure, request that AM redirect the user to the specified location. Values must be URL-encoded. For more information, refer to Success and failure redirection URLs.

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.

service

Request that AM authenticate the user with the specified authentication tree.

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 Top Level Realm, requesting that AM display the user interface in German.

https://am.example.com:8443/am/XUI/?realm=/&locale=de#login

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

https://am.example.com:8443/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://am.example.com:8443/am/XUI/?realm=/alpha&locale=de&service=myTree#login