PingAM

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.

Common use cases

Customize the browser sign-on URL to direct users to the right realm and journey:

  • Realm-specific sign-on: Direct users of a specific realm to it in the URL, so they sign on against the correct identity store. Learn more in Specify the realm in the URL.

  • Selecting a journey: Specify a tree with the service parameter when users must sign on through a specific journey, such as MFA or passwordless registration. Learn more in Authentication parameters.

  • Forced reauthentication: Set ForceAuth=true to require users to authenticate again even when they hold a valid session, such as before a sensitive action. Learn more in Authentication parameters.

  • Locale and redirects: Request a supported UI language with locale, and control where users land after authentication with goto and gotoOnFail. Learn more in Authentication parameters.

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.

This parameter is case-sensitive. Using forceAuth or forceauth has no effect.
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