The Authentication Service user interface is accessed by entering a login URL into the Location Bar of a web browser. Planning an OpenSSO Enterprise Authentication Process has an overview of this login URL and how the authentication type is initiated by appending the appropriate parameter to it. A parameter is a name/value pair appended to the end of a URL. The parameter starts with a question mark (?) which is followed by the form name=value and an ampersand (&) for multiple parameters. The format of the login URL with parameter(s) is:

http://OpenSSO-machine-name.domain:port/service_deploy_uri/UI/Login?
parameter1=value1&parameter2=value2&parameterN=valueN

where service_deploy_uri is configured as opensso, by default. This article documents the parameters that can be appended to the login URL.

If more than one parameter exists, they must adhere to the following guidelines.

• Each parameter can occur only once in one URL. For example, module=LDAP&module=NT is not computable.
• Both the org parameter and the domain parameter determine the login realm. In this case, only one of the two parameters should be used in the login URL. If both are used and no precedence is specified, only one will take effect.
• The parameters user, role, service, module and authlevel are for defining authentication modules based on their respective criteria. Due to this, only one of them should be used in the login URL. If more than one is used and no precedence is specified, only one will take effect.

Simplifying Complex Login URLs To simplify an authentication URL and parameters for distribution throughout a realm, an administrator might configure an HTML page with a simple URL that possesses links to the more complicated login URLs for the configured authentication process.

The following sections describe parameters that, when appended to the login URL, achieve various authentication functionality.

goto Parameter

A goto=successful-authentication-URL parameter defines a URL to which the user will be redirected after successfully authenticating.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?
goto=http://www.sun.com/homepage.html

A goto=logout-URL parameter can also be set to link to a specified URL when the user logs out.

http://OpenSSO-machine-name.domain:port/opensso/UI/Logout?
goto=http://www.sun.com/logout.html

There is an order of precedence in which OpenSSO Enterprise looks for redirection URLs. The order of preference is based on the type of authentication initiated. See Initiating OpenSSO Enterprise Authentication by Type for the order specific to each authentication type.

gotoOnFail Parameter

A gotoOnFail=failed-authentication-URL parameter defines a URL to which the user will be redirected after failing the defined authentication process.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?
gotoOnFail=http://www.sun.com/auth_fail.html

There is an order of precedence in which OpenSSO Enterprise looks for redirection URLs. The order of preference is based on the type of authentication initiated. See Initiating OpenSSO Enterprise Authentication by Type for the order specific to each authentication type.

realm Parameter

The realm=realm-name parameter allows a member of a realm to authenticate using the authentication process configured for that particular realm (or sub realm). A user who is not already a member of the realm will receive an error message when they attempt to authenticate using the realm parameter. Realm authentication is the default authentication type for OpenSSO Enterprise.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?realm=sun

A user profile can be dynamically created in the realm's configured user data store if all of the following are TRUE:

• The User Profile attribute in the Core Authentication module must be set to Dynamic or Dynamic with User Alias. See Configuring Core Authentication Properties Using the OpenSSO Console (wiki).
• The user must successfully authenticate to the required module or authentication chain.
• The user does not already have a profile in the user data store.

If there is a value for this parameter, the correct login page based on the realm name and locale setting will be displayed. If this parameter is not set, the login page for the default top level realm is displayed. For more information, see Realm Authentication.

user Parameter

The user=Universal-ID parameter forces authentication based on the authentication chain configured as the value of the User Authentication Configuration attribute in the user's profile. Using this parameter sends the user to a specific authentication process rather than the process configured for the user's organization.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?user=jsmith

For more information, see User Authentication.

locale Parameter

OpenSSO Enterprise has the capability to display screens that are translated into languages other than English. These localized screens can be configured for the authentication process as well as for the console itself. The locale=language-locale parameter allows the specified locale to take precedence over any other defined locales for the authentication process.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?locale=ja

The login locale is displayed by the client after searching for the configured locale in the following places, order-specific:

1. Value of the locale parameter in login URL
   The value of the locale=language-locale parameter takes precedence over all other defined locales. See Supported Language Locales in the Sun OpenSSO Enterprise 8.0 Administration Reference.
2. Locale defined in user's profile
   If there is no URL parameter, the locale is displayed based on the value set in the User Preferred Language attribute of the user's profile.
3. Locale defined in the HTTP header
   This locale is set by the web browser.
4. Locale defined in Core Authentication module
   This is the value of the Default Auth Locale attribute in the Core Authentication module. See Configuring Core Authentication Properties Using the OpenSSO Console (wiki).
5. Locale defined in Platform Service
   This is the value of the Platform Locale attribute in the OpenSSO Enterprise Platform service.
6. Operating system locale

The locale derived from this pecking order is stored in the user's SSOToken and OpenSSO Enterprise uses it for loading the localized authentication module only. After successful authentication, the locale defined in the User Preferred Language attribute of the user's profile is used. If none is set, the locale used for authentication will be carried over. For more information, see Localizing the Sun OpenSSO Enterprise 8.0 Login Page.

module Parameter

The module=module-name parameter allows authentication using the specified authentication module. Any authentication module can be specified although it must first be registered and configured under the realm to which the user belongs. The authentication module names are case-sensitive when used as a value of the module parameter in the login URL.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=Unix

For more information, see Module Authentication.

service Parameter

The service=authentication-chain-name parameter allows a user to authenticate using a specific authentication chain. For authentication to be successful, the user must authenticate to each authentication module defined in the chain.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?service=chain1

For more information, see Service Authentication.

arg Parameter

The arg=newsession parameter is used to end a user's current session and begin a new one. (The parameter and value are appended as is; there is no variable.) The Authentication Service will destroy a user's existing session token and perform a new login in one request. This option is typically used by the Anonymous authentication module. The user first authenticates with an anonymous session, and then clicks a register or login link.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?arg=newsession

authlevel Parameter

An authlevel=integer parameter tells the Authentication Service to call a module with an authentication level equal to or greater than the specified authentication level integer. The Authentication Level value is set in each authentication module's profile whether defined globally or per realm.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?authlevel=3

When Authentication Level-based authentication is initiated, the Authentication Service displays a login page with a menu containing the authentication modules that have authentication levels equal to or greater then the value specified in the authlevel parameter. Users can select a module from the presented list. For more information, see Authentication Level-based Authentication.

ForceAuth Parameter

The ForceAuth=true query parameter forces the user to authenticate - even if the user currently has a valid session. This parameter is useful in the following cases:

• If a user is authenticated with http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=LDAP and accesses the URL again, there would be no prompt for authentication. However, if the user is authenticated with http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=LDAP and accesses http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=LDAP&ForceAuth=true, the user is prompted to authenticate again. The session identifier and the session cookie are not changed for the user.
• If a user is authenticated with http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=LDAP and accesses http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=DataStore, the user is prompted to authenticate again using the Data Store authentication module. In this situation, after successfully authenticating to the second module, OpenSSO Enterprise creates a new session and copies the properties from the old session before destroying it. However, if the user is authenticated with http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=LDAP and accesses http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=DataStore&ForceAuth=true, the user is prompted to authenticate again but, after successfully authenticating using Data Store, the session cookie is not changed.

IDTokenN Parameters

The IDTokenN=credential parameter enables a user to pass authentication credentials using the login URL, allowing authentication without accessing the Authentication Service User Interface. This zero page login process works only for authentication modules with one login page. The values of IDToken1=credential&IDToken2=credential&IDTokenN=credential map to the fields on the authentication module's login page. For example, the LDAP authentication module might use IDToken1 for the user identifier and IDToken2 for the password. In this example, the URL would be http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=LDAP&IDToken1=awhite&IDToken2=awhite12. (module=LDAP may be omitted if LDAP is the default authentication module.) The Anonymous authentication module URL would be http://OpenSSO-machine-name.domain:port/opensso/UI/Login?module=Anonymous&IDToken1=anonymous as anonymous is a default OpenSSO Enterprise anonymous user.

iPSPCookie Parameter

The iPSPCookie=yes parameter allows a user to login with a persistent cookie. A persistent cookie is one that continues to exist after the browser window is closed. If the user is successfully authenticated and the browser is closed, the user can login with a new browser session and will be directed to the console without having to authenticate again.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?realm=hr&iPSPCookie=yes

To use this parameter, the Persistent Cookie Mode attribute must be enabled in the realm to which the user is logging in. The process will work until the value of the Persistent Cookie Maximum Time attribute elapses. For more information on these attributes, see Configuring Core Authentication Properties Using the OpenSSO Console (wiki).

PersistAMCookie Parameter

The PersistAMCookie parameter will save the OpenSSO Enterprise cookie to memory, allowing an application (other than the browser) on the same machine to read it and create an SSOToken.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?
realm=people&iPersistAMCookiee=yes

role Parameter (Legacy Mode)

A role=role-name parameter sends the user to the authentication process configured for the specified role. A user who is not already a member of the specified role will receive an error message when they attempt to authenticate with this parameter.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?role=manager

For more information, see Role Authentication (Legacy Mode).

org Parameter (Legacy Mode)

The org=organization-name parameter allows a member of the specified organization to authenticate using the authentication process configured for that particular organization. This is a legacy parameter for use with legacy directory information trees (DITs).

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?org=sun

The parameter would work much the same as the realm parameter. See realm Parameter for more information.

domain Parameter (Legacy Mode)

The domain=domain-name parameter allows a user to login to a realm identified as the specified domain. The specified domain must be set as a value in the Realm/DNS Aliases attribute of the realm's General profile.

http://OpenSSO-machine-name.domain:port/opensso/UI/Login?domain=sun.com

The parameter would work much the same as the realm parameter. See realm Parameter for more information.