--- title: Authenticate with a browser description: 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. component: pingam version: 7.3 page_id: pingam:authentication-guide:authn-from-browser canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/authn-from-browser.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Authentication", "Realms", "Browser"] section_ids: authn-from-browser-XUI-realm: Specify the realm in the URL authn-from-browser-parameters: Authentication parameters authn-from-browser-XUI-examples: Example UI login URLs --- # 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](#authn-from-browser-XUI-realm) and also different [authentication parameters](#authn-from-browser-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`](../reference/deployment-configuration-reference.html#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](redirection-url-precedence.html). - 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](redirection-url-precedence.html). - 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](../install-guide/prepare-identity-repository.html) . 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](#authn-from-browser-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` |