# OpenAM Administration Guide
Chapter 2. Defining Authentication Services

Sidebar | Prev | Up | Next

## 2.5. Authenticating To OpenAM

This section explains how to connect to OpenAM for user authentication by adding parameters to the login URL when testing your configuration.

The base URL to authenticate to OpenAM points to `/UI/Login` under the deployment URL, such as `http://openam.example.com:8080/openam/UI/Login`. [4] You can, however, specify parameters in the query string of the URL to request a specific authentication configuration. For example, `http://openam.example.com:8080/openam/UI/Login?module=LDAP` requests that OpenAM use the LDAP authentication module.

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

| Note
The way you enter parameters depends on whether you are using the classic UI or the XUI. For example, if you want to request that OpenAM end the user's current session and start a new session in the classic UI, you might enter a URL similar to: `http://openam.example.com:8080/openam/UI/Login?locale=fr`. Alternatively, for the JavaScript-based XUI, the corresponding URL would be subtly different: `http://openam.example.com:8080/openam/XUI/#login/&arg=newsession`.

arg=newsession

  Request that OpenAM end the user's current session and start a new session.

authlevel

  Request that OpenAM 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 OpenAM force the user to authenticate even if she already has a valid session. On successful authentication, OpenAM updates the session token.

goto

  On successful authentication, or successful logout, request that OpenAM redirect the user to the specified location. Values must be URL encoded.

gotoOnFail

  On authentication failure, request that OpenAM redirect the user to the specified location. Values must be URL encoded.

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.

iPSPCookie=yes

  Applicable only if you configure persistent cookies based on Section 2.2.5.3, “Core - Persistent Cookie (Legacy)”

  Request that OpenAM return a persistent cookie that remains in the browser after the browser is closed, allowing the user to login again without being prompted for credentials. This only works if you have configured persistent cookie mode for the realm where the user logs in.

  OpenAM sets an `DProPCookie` that persists until expiry. The following screen shot shows an example.

  An alternative persistent cookie mechanism extends the lifetime of the normal `iPlanetDirectoryPro` using the advanced server settings, `openam.session.persist_am_cookie` or `openam.session.allow_persist_am_cookie`, and `com.iplanet.am.cookie.timeToLive`.

  To set the mechanism globally for the server, browse in the OpenAM console to Configuration > Servers and Sites > `Server Name` > Advanced, and then set `openam.session.persist_am_cookie` to `true` and `com.iplanet.am.cookie.timeToLive` to the cookie lifetime in seconds.

  To allow users to use this mechanism on a per-session basis, browse in the OpenAM console to Configuration > Servers and Sites > `Server Name` > Advanced, and then set `openam.session.allow_persist_am_cookie` to `true` and `com.iplanet.am.cookie.timeToLive` to the cookie lifetime in seconds. (If the OpenAM .war deployed does not include the console, set these properties in the .properties configuration file.) Also configure the session properties either globally under Configuration > Global > Session > Dynamic Attributes, or per realm under Access Control > `Realm Name` > Services > Session. Then, to request the cookie, use `openam.session.persist_am_cookie=Yes` as one of the query string parameters in the login URL.

  | Note
  Neither the XUI nor the Persistent Cookie module supports the deprecated `iPSPCookie`.

locale

  Request that OpenAM 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 OpenAM, and so on.

module

  Request that OpenAM 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 OpenAM authenticate the user to the specified realm.

service

  Request that OpenAM 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 her OpenAM universal ID, authenticate according to the chain specified in her profile.

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

[4] The base URL to logout is similar, for example `http://openam.example.com:8080/openam/UI/Logout`.