AM 7.3.1

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://openam.example.com:8443/openam/XUI/#login.

The base URL to log out is similar, for example, https://openam.example.com:8443/openam/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 do not use a realm alias, then you must specify the entire hierarchy of the realm. For example: https://openam.example.com:8443/openam/XUI/?realm=/customers/europe#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://openam.example.com:8443/openam/XUI/?realm=/customers/europe#login

Realm alias of the realm as a parameter of XUI

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

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

http://myRealm.example.com:8080/openam/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, do not 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.

authlevel

Request that AM authenticate the user using a module with at least the specified authentication level that you have configured.

As this parameter determines authentication module selection, do not use it with module, service, or user.

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 does one of the following:

  • (Authentication trees only) AM issues new session tokens to users on reauthentication, even if the current session already meets the security requirements.

  • (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. In this configuration, session upgrade is not supported for client-side sessions. When a user attempts to reauthenticate with a client-side session, they will see a ForceAuth fails since session is stateless dialog.

For authentication chains, the forceAuth.enabled advanced server property controls whether the value of the ForceAuth parameter is respected.
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.

IDToken1, IDToken2, …​, IDTokenN

Pass the specified credentials as IDToken parameters in the URL. The IDToken credentials map to the fields in the Login page for the authentication module, such as IDToken1 as user ID and IDToken2 as password for basic user name, password authentication. The order depends on the callbacks in Login page for the module; IDTokenN represents the Nth callback of the Login page.

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.

module

Request that AM use the authentication module instance as configured for the realm where the user is authenticating.

As this parameter determines authentication module selection, do not use it with authlevel, service, or user.

realm

Request that AM authenticate the user to the specified realm.

resource

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

For resource-based authentication, also set the resourceURL parameter.

resourceURL

Authentication chains only. This parameter does not apply to authentication trees.

Set the resourceURL to the URL of the resource for resource-based authentication.

Resource-based authentication applies when an authorization policy has an environment condition of type Authentication by Service or Authentication by Module Instance. When the resource URL matches a policy resource, AM finds the chain or module configured in the policy environment settings and uses the specified chain or module to perform authentication.

For example, if you configure a policy with the resource https://www.example.com:443/index.html and the environment condition Authentication by Service: DataStore, the following login URL causes AM to use the DataStore service to authenticate the user:

https://openam.example.com:8443/openam/XUI/#login?resource=true&resourceURL=https://www.example.com:443/index.html&goto=https://www.example.com/

On successful authentication, AM redirects the user-agent to https://www.example.com/.

As shown in the example, when setting the resourceURL parameter, also set resource=true.

service

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

As this parameter determines authentication module selection, do not use it with authlevel, module, or user.

user

Request that the user, specified by their AM universal ID, authenticate according to the chain specified by the User Authentication Configuration property in their user profile. You can configure this property for a user under Realms > Realm Name > Identities > UserName.

In order for the User Authentication Configuration property to appear in user profiles, the iplanet-am-user-service object class must contain the iplanet-am-user-auth-config attribute in the identity repository schema. The default identity repository schema provided with AM includes this object class and attribute.

For information about identity repository schema, refer to Prepare identity repositories .

As this parameter determines authentication module selection, do not use it with authlevel, module, or service.

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://openam.example.com:8443/openam/XUI/?realm=/&locale=de#login

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

https://openam.example.com:8443/openam/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://openam.example.com:8443/openam/XUI/?realm=/alpha&locale=de&service=myTree#login
Copyright © 2010-2024 ForgeRock, all rights reserved.