Authenticating (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.

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://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
DescriptionExample 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. 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.

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. 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, AM updates the session token with the new authentication information, if required.

    Important

    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. 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.

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 username, 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 this parameter to the URL of the resource for resource-based authentication.

Resource-based authentication applies when an authorization policy has an environment setting of type Authentication by Module Chain or Authentication by Module Instance. When the specified resource URL matches a policy resource, AM finds the chain or module configured in the policy environment settings. AM then 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 Authentication by Module Chain: DataStore, then the following login URL causes AM to use the DataStore chain 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, authenticates 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 schemas provided with AM include this object class and attribute. See "Preparing Identity Repositories" for information about identity repository schema.

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
DescriptionExample 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


Read a different version of :