Chapter 3 Configuring Authentication

The function of the OpenSSO Enterprise Authentication Service is to retrieve credentials from an authenticating party (a user, administrator, or client application), and validate them against a configured repository. Towards this end, the OpenSSO Enterprise console is used to specify the authentication process by instantiating an authentication module, and using the instantiated modules to establish an authentication chain (one or more authentication module instances configured so that a user must pass authentication credentials to all of them). The following sections describe how to configure and manage authentication for your deployment.

• Understanding the Authentication Service

• Configuring the Core Authentication Service

• Configuring the Authentication Process

• Initiating the Authentication Type

• Accessing the Authentication Service User Interface with a Login URL

• Customizing Authentication

Understanding the Authentication Service

The core function of the Authentication Service is to validate the required credentials of end users, administrators or applications requesting access to information or protected resources in the OpenSSO Enterprise single sign-on environment. When creating the end-to-end authentication process by which a user (for example) will be authenticated, there are things to consider such as where the authentication process will be initiated, which authentication module(s) will be used in the process, and what, if any, post authentication steps will be implemented. The authentication type (where the authentication process will be initiated) is specified by appending an appropriate parameter to the login URL, or through the authentication API. The authentication process is configured (simply) by instantiating the desired authentication module(s) or (with more complexity) by creating an authentication chain. Post authentication processing steps are developed programmatically through implementation of a provided interface. The following sections contain information on these considerations.

• Authentication Service User Interface

• Authentication Modules

• Authentication Types

• Authentication Post Processing

A detailed technical explanation of the authentication process through session validation and policy evaluation is in Chapter 6, Models of the User Session and Single Sign-On Processes, in Sun OpenSSO Enterprise 8.0 Technical Overview.

Authentication Service User Interface

The Authentication Service user interface provides a means for gathering the credentials needed by the Authentication Service to validate a user. In most cases, the Authentication Service user interface is accessed by entering a login URL into the Location Bar of a web browser. A URL parameter may be appended to the end of the URL to define, for example, specific authentication types or redirection URLs. The format of this URL is:

http://OpenSSO-server..domain_name:port/service_deploy_uri/UI/Login?parameter1=value1&parameter2=value2&parameterN=valueN

During installation, the service_deploy_uri is configured as opensso.

After entering this URL, login screens are dynamically displayed based on the invoked authentication module, and a user is able to communicate an identifier and password, for example, back to the Authentication Service to receive (or not receive) validation. For more information on accessing the Authentication Service, see Accessing the Authentication Service User Interface with a Login URL.

Authentication Modules

An authentication module is a plug-in that collects information from a principal requesting access to a protected resource and checks the information against entries in a data store. If the information provided meets the authentication criteria, the user is validated. If the information provided does not meet the authentication criteria, the user is denied validation. OpenSSO Enterprise provides a number of authentication modules. You instantiate an authentication module before accessing it for a simple authentication process (see Authentication Types), or adding it to an authentication chain. (In an authentication chain, you can configure, for example, two instances of the LDAP authentication module — each pointing to a different LDAP data store configured within the same realm; or you can configure different authentication modules so a user must pass authentication credentials to all of them for validation.)

The following sections contain information about the individual authentication modules provided by OpenSSO Enterprise. Some of them require configuration before they can be instantiated. Where applicable, the configuration steps are listed in the module type descriptions.

• Active Directory

• Anonymous

• Certificate

• Data Store

• Federation

• HTTP Basic

• JDBC

• LDAP

• Membership

• MSISDN

• RADIUS

• SAE

• SafeWord

• SecurID

• Unix

• Windows Desktop SSO

• Windows NT

• WSSAuth

Active Directory

The Active Directory authentication module performs authentication in a manner similar to that of the LDAP module, but uses Microsoft’s Active Directory™ server. Although the LDAP authentication module can be configured for Active Directory, using this module allows you to have both LDAP and Active Directory authentication exist under the same realm. For information on the Active Directory authentication module attributes, see Active Directory in Sun OpenSSO Enterprise 8.0 Administration Reference.

For this release, the Active Directory authentication module only supports user authentication and password policy is only supported in the LDAP authentication module.

Anonymous

The Anonymous authentication module allows a user to log in to OpenSSO Enterprise without specifying validating credentials. Anonymous connections are usually customized by the OpenSSO Enterprise administrator so that Anonymous users have limited access to the server (for example, access for read or access for search), or to specific trees or entries within the identity data store. A list of anonymous users can be defined by adding the applicable user identifier(s) to the module's Valid Anonymous Users attribute. Granting anonymous access means that it can be accessed without providing a password. A default anonymous user is created during OpenSSO Enterprise installation. For information on the Anonymous authentication module attributes, see Anonymous in Sun OpenSSO Enterprise 8.0 Administration Reference.

Certificate

The Certificate authentication module requires a personal digital certificate (PDC) to identify and authenticate a user. The module can be configured to require a match between the user's PDC and a PDC stored in the configuration data store, as well as verification against a Certificate Revocation List. It can also require the use of the Online Certificate Status Protocol (OCSP) to determine the state of a certificate. Successful or failed authentication is dependent on whether or not the certificate is valid. The following information should be considered before using the Certificate authentication module.

• The web container that is installed with the OpenSSO Enterprise needs to be secured and configured for Certificate-based Authentication.

• To add this module, log in to OpenSSO Enterprise as the realm Administrator and have OpenSSO Enterprise and the web container configured for SSL and with client authentication enabled.

• To check the certificates presented by a client against those found in a directory server, import the root CA certificate for the client certificate into the trust store of the JVM on the OpenSSO Enterprise host machine (by default JDK_HOME/jre/lib/security/cacerts). You can use the keytool command line interface.

• If you are configuring OpenSSO Enterprise Certificate authentication with an SSL-enabled Sun Java System Web Server 6.1 instance, and wish to have the Web Server defined to accept both certificate based and non certificate based authentication requests, you must set the following value in the Web Server's obj.conf file:

  PathCheck fn="get-client-cert" dorequest="1" require="0

  This is due to a limitation in the Web Server console when setting the optional attribute for this behavior. Is this the web container on which OSSO is deployed?

• Before enabling the Certificate-based module, see Using Certificates and Keys in the Sun ONE Web Server 6.1 Administration Guide at http://docs.sun.com/db/prod/s1websrv#hic or the Sun ONE Application Server Administrator’s Guide to Security at http://docs.sun.com/db/prod/s1appsrv#hic for initial configuration steps.

• Each user that will authenticate using the Certificate authentication module must request a PDC for the browser. Instructions depend upon the browser being used. See the specific documentation for more information.

For information on the Certificate authentication module attributes, see Certificate in Sun OpenSSO Enterprise 8.0 Administration Reference.

Data Store

The Data Store authentication module allows a user to authenticate against one or more of a realm's identity data stores (depending on the authentication process configuration). This authentication module is enabled after installation to authenticate to the identity data store configured for the top level realm during installation. Depending on the deployment, this might be the embedded configuration data store (for user storage in sample deployments) or a defined external data store (for user storage in real world deployments). If you change the identity data store definition for the top level realm, the Data Store authentication module adapts to the modified data store definition. After installation, additional identity data stores can be added to the top level or sub realms and configured for Data Store authentication. The Data Store authentication module extends the com.sun.identity.idm.IdRepo interface. You can include or remove a configured data store from identity authentication by unchecking User in the Identity Types That Can Be Authenticated attribute in the Data Store profile. For more information on the Data Store authentication module attributes, see Data Store in Sun OpenSSO Enterprise 8.0 Administration Reference.

Federation

The Federation authentication module is used by all federation protocols implemented by OpenSSO Enterprise (including SAML v1.x and SAML v2, Liberty ID-FF, and WS-Federation). This module can not be invoked as other authentication modules. (If you do this, you have to provide the necessary authentication callbacks as it will not initiate single sign-on and provide them itself.) The Federation authentication module requires a federation setup and will be invoked internally on the service provider side to create an SSOToken after validating the federation protocol messages. For information on the Federation authentication module attributes, see Federation in Sun OpenSSO Enterprise 8.0 Administration Reference.

HTTP Basic

The HTTP Basic authentication module uses basic authentication in the context of HTTP communication. A web browser issues a request for a username and password, and sends the credentials to the web server as part of the authentication request. OpenSSO Enterprise retrieves the username and password and authenticates the user using the LDAP authentication module. In order for HTTP Basic to function correctly, both the LDAP authentication module and the HTTP Basic authentication module must be added to the appropriate realm. Once the user successfully authenticates, the user will be able to authenticate again without being prompted for username and password. For information on the HTTP Basic authentication module attributes, see HTTP Basic in Sun OpenSSO Enterprise 8.0 Administration Reference.

JDBC

The Java Database Connectivity (JDBC) authentication module provides a mechanism to allow OpenSSO Enterprise to authenticate users through any SQL database that provides JDBC technology-enabled drivers. The connection to the SQL database can be either directly through a JDBC driver, or through a JNDI connection pool. For information on the HTTP Basic authentication module attributes, see JDBC in Sun OpenSSO Enterprise 8.0 Administration Reference.

This module has been tested on MySQL4.0 and Oracle 8i.

LDAP

The LDAP authentication module uses a Distinguished Name (DN) and password to authenticate to an LDAP data store. If the submitted credentials are found in the directory, the user is authenticated and an SSOToken created. This module is enabled during OpenSSO Enterprise installation for the top level realm. For information on the LDAP authentication module attributes, see LDAP in Sun OpenSSO Enterprise 8.0 Administration Reference.

Membership

The Membership authentication module is implemented for personalized sites where a user is able to create an account and define preferences without the aid of an administrator. Once created, the user can access the resource as an added user. After the account is created, the user can authenticate to the appropriate OpenSSO Enterprise realm as configured. For information on the Membership authentication module attributes, see Membership in Sun OpenSSO Enterprise 8.0 Administration Reference.

MSISDN

The Mobile Station Integrated Services Digital Network (MSISDN) authentication module enables authentication using a mobile subscriber ISDN associated with a device such as a cellular telephone. It is a non-interactive module. The module retrieves the subscriber ISDN and compares it against the data store to find a user that matches the number. If found, the user is validated. For information on the MSISDN authentication module attributes, see MSISDN in Sun OpenSSO Enterprise 8.0 Administration Reference.

RADIUS

The RADIUS authentication module enables authentication to an installed and configured RADIUS server currently being used for authentication. For information on the RADIUS authentication module attributes, see RADIUS in Sun OpenSSO Enterprise 8.0 Administration Reference. See Before You Begin for special pre-configuration instructions when using the RADIUS authentication module.

SAE

The Secure Attribute Exchange (also known as Virtual Federation) authentication module is used when an external entity (such as an existing application) has already authenticated the user and wishes to securely inform a local instance of OpenSSO Enterprise to trigger the creation of an SSOToken for the user. This module is also used when the existing entity instructs the local instance of OpenSSO Enterprise to use federation protocols to transfer authentication and attribute information to a partner application. This module can not be invoked as other authentication modules. It requires setting up parties for Secure Attribute Exchange and will be invoked internally. For information on the Secure Attribute Exchange authentication module attributes, see SAE in Sun OpenSSO Enterprise 8.0 Administration Reference.

SafeWord

The SafeWord authentication module handles authentication requests to Secure Computing’s SafeWord™ or SafeWord PremierAccess™ authentication servers. The SafeWord server may exist on the system on which OpenSSO Enterprise is installed, or on a separate system. For information on the SafeWord authentication module attributes, see SafeWord in Sun OpenSSO Enterprise 8.0 Administration Reference. See Before You Begin for special pre-configuration instructions when using the SafeWord authentication module.

SecurID

The SecurID authentication module handles authentication requests to RSA’s ACE/Server authentication servers. OpenSSO Enterprise provides the client portion of SecurID authentication. The ACE/Server may exist on the system on which OpenSSO Enterprise is installed, or on a separate system. For information on the SecurID authentication module attributes, see SecurID in Sun OpenSSO Enterprise 8.0 Administration Reference.

The SecurID Authentication module is available for the Solaris/SPARC, Solaris/x86, Linux, and Windows platforms.

Unix

The Unix authentication module is a Pluggable Authentication Module (PAM) that authenticates user identifiers known to the Solaris or Linux system (local or NIS) on which OpenSSO Enterprise is installed. This module makes use of an authentication helper daemon called amunixd which opens a socket on a specified port in order to listen for Unix authentication requests. This daemon process is separate from the authentication process. The PAM Service Name attribute defaults to other for Solaris, and password for Linux. For information on the Unix authentication module attributes, see Unix in Sun OpenSSO Enterprise 8.0 Administration Reference. For instructions on setting up and running amunixd, see Running the Unix Authentication Helper (amunixd Daemon) in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

Windows Desktop SSO

The Windows Desktop SSO authentication module is a Kerberos-based authentication plug-in module targeted for Windows™ desktop users. It allows a user who has already authenticated to a Kerberos Distribution Center (KDC) to authenticate to OpenSSO Enterprise without re-submitting login credentials (in effect, single sign-on). In order to perform Kerberos-based single sign-on to OpenSSO Enterprise, the user on the client side must support the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. (In general, any user that supports this protocol should be able to use this module.) The user presents the Kerberos token to OpenSSO Enterprise using SPNEGO and the client sends back a SPNEGO token embedded with a Kerberos token. The module retrieves the Kerberos token, authenticates the user using the Java GSS API and, if successful, returns an SSOToken to the client.

You must use JDK 1.4 or above to utilize the new features of Kerberos V5 authentication module and Java GSS API to perform Kerberos based SSO in this SPNEGO module.

For information on the Windows Desktop SSO authentication module attributes, see Windows Desktop SSO in Sun OpenSSO Enterprise 8.0 Administration Reference. See Before You Begin for special pre-configuration instructions when using the Windows Desktop SSO authentication module.

Windows NT

The Windows NT authentication module handles authentication against an installed Windows NT or Windows 2000 server. For information on the Windows NT authentication module attributes, see Windows NT in Sun OpenSSO Enterprise 8.0 Administration Reference. See Before You Begin for special pre-configuration instructions when using the Windows NT authentication module.

WSSAuth

The WSSAuth authentication module is used for authenticating the WS-Security Username Token profile when using the digest option. When configured as part of the authentication chain in the web services provider (wsp) agent profile, the user is authenticated using the user name and password (or password equivalent) presented via the Username Token profile. The communicating WSC and WSP must agree upon a common password policy in their back end.

Authentication Types

The authentication type specifies from where the authentication process will be initiated. The authentication type is specified by appending the appropriate parameter to a login URL, or through the authentication API. OpenSSO Enterprise supports the following authentication types:

• Authentication level allows authentication based on a security level defined for each authentication module by an administrator.

• Module allows authentication by specifying an authentication module instance.

• Realm allows authentication using the authentication process defined for a specific realm.

• Service allows authentication using the authentication process defined for a specific service or application.

• User allows a user to authenticate using the authentication process defined in the user's profile.

For each of these authentication types, the user can either pass or fail the defined authentication process (either a module or a chain). For more information, see Initiating the Authentication Type. For more information on specifying an authentication type, see Accessing the Authentication Service User Interface with a Login URL.

Authentication Post Processing

Post processing functionality can be added to the authentication process. This would define actions taken after a successful or failed authentication. For more information see Adding Authentication Post Processing Features in Sun OpenSSO Enterprise 8.0 Developer’s Guide.

Configuring the Core Authentication Service

Core Authentication contains general Authentication Service properties that can be defined globally for the OpenSSO Enterprise deployment (under the Configuration tab) or specifically for a configured realm (under the Access Control tab). The Core authentication module is added and enabled for the top level realm during installation. As new realms are created under the top level realm, these properties (and the values defined globally for them) are dynamically added to each new realm. Once added, new values can be defined and configured values can be modified by the realm's administrator. The values are then used if no overriding value is defined in the specified authentication module instance or authentication chain. The Authentication Service finds the general operating data it needs in the following order of precedence.

1. Authentication process property values (specified authentication module instance, authentication chain or both) in the configured realm.

2. Realm property values defined for the realm's users, roles, services, and so forth.

3. Global property values if no overriding value is defined in the configured realm or authentication process.

The following procedures illustrate the levels at which the Core Authentication module can be modified after installation.

• To Modify Core Authentication Properties Globally

• To Modify Core Authentication Properties By Realm

To Modify Core Authentication Properties Globally

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator.

1. Click the Configuration tab.

2. Click Core under the Authentication tab.

3. Modify the Global attributes by adding or changing the values.

   These properties contain operating values that are applied to the Authentication Service throughout the OpenSSO Enterprise deployment.

   Pluggable Authentication Module Classes

   Specifies the Java classes of the available authentication modules. Takes a text string specifying the full class name (including package) of each authentication module. After writing a custom authentication module (by implementing the OpenSSO Enterprise AMLoginModule or the Java Authentication and Authorization Service [JAAS] LoginModule service provider interfaces), the new class value must be added to this property.

   Supported Authentication Modules for Clients

   Specifies a list of authentication modules supported for a specific client. Formatted as:

   clientType | module1,module2,module3

   This attribute is read by the Client Detection Service when it is enabled.

   LDAP Connection Pool Size

   Specifies the minimum and maximum connection pool to be used on a specific LDAP server and port. Formatted as:

   host:port:min:max

   This attribute is for LDAP and Membership authentication services only.

   Default LDAP Connection Pool Size

   Sets the default minimum and maximum connection pool to be used with all LDAP authentication module configurations. Formatted as:

   min:max

   This value is superseded by a value defined for a specific host and port in the LDAP Connection Pool Size property.

   Remote Auth Security

   Requires that OpenSSO Enterprise validate the identity of the calling application; thus all remote authentication requests require the calling application's SSOToken. This allows the Authentication Service to obtain the username and password associated with the application.

   Keep Post Process Objects for Logout Processing

   Requires that the user session hold the instances of any post processing authentication classes used during the log in process after authentication is complete. When user log out is later invoked, the onLogout() method of these instances is called. If this attribute is not enabled, the post processing instances are not preserved and new instances are created when logout is invoked.

   Keep Authentication Module Objects for Logout Processing

   Requires that the user session hold the instances of authentication modules used during the log in process after authentication is complete. When user log out is later invoked, the destroyModuleState() method of these instances is called. If this attribute is not enabled, the authentication module instances are not preserved and no method on the authentication modules is called upon log out.

4. Modify the top level Realm attributes by adding or changing the values.

   These realm properties (as defined globally under the Configuration tab) are specific to the top level realm. Top level realm properties can also be modified by navigating to the top level realm itself. See To Modify Core Authentication Properties By Realm for instructions and definitions of the attributes.

5. Click Save.

6. Click Back to Service Configuration.

7. Logout of the OpenSSO Enterprise console.

To Modify Core Authentication Properties By Realm

Realm attributes are applied to the realm under which they are configured.

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator.

1. Click the Access Control tab.

2. Click the name of the realm that contains the properties to be modified.

3. Click the Authentication tab.

   The Core authentication module's General properties for the realm are displayed.

4. Modify the values of the realm's General properties.

   The General properties are defined in the Core authentication module and are configurable by realm. Those documented in this step are the ones most likely to be modified.

   Default Authentication Chain

   Defines the default authentication chain used by the realm's users. The authentication chain must first be created before it is displayed as an option in the drop down list. For more information see To Create an Authentication Chain.

   Administrator Authentication Chain

   Defines the authentication chain used by administrators when the process needs to be different from the authentication chain defined for end users. The authentication chain must first be created before it is displayed as an option in the drop down list. For more information see To Create an Authentication Chain.

   Default Success Login URL

   Specifies a URL that the user will be redirected to upon successful authentication to the realm.

5. Click Advanced Properties.

   The Core authentication module's General Advanced Properties for the realm are displayed.

6. Modify the attributes.

   The General Advanced Properties are defined in the Core authentication module and are configurable by realm. Those documented in this step are the ones less likely to be modified.

   User Profile

   This option determines the profile status of a successfully authenticated user.

   Dynamic

   Specifies that on successful authentication the Authentication Service will create a user profile if one does not already exist. The SSOToken will then be issued. The user profile is created in the realm's configured user data store.

   Dynamic With User Alias

   Specifies that on successful authentication the Authentication Service will create a user profile that contains the User Alias List attribute which defines one or more aliases that for mapping a user's multiple profiles.

   Ignore

   Specifies that a user profile is not required for the Authentication Service to issue an SSOToken after a successful authentication.

   Required

   Specifies that on successful authentication the user must have a user profile in the realm's configured user data store in order for the Authentication Service to issue an SSOToken.

   Administrator Authentication Configuration

   Defines the authentication chain used by administrators when the process needs to be different from the authentication chain defined for end users. The authentication chain must first be created before it is displayed as an option in the drop down list. For more information see To Create an Authentication Chain.

   User Profile Dynamic Creation Default Roles

   Specifies the DN of a role to be assigned to a new user whose profile is created when either of the Dynamic options is selected under the User Profile attribute. There are no default values. The role specified must be within the realm for which the authentication process is configured.

   ---

   Tip –

   This role can be either an OpenSSO Enterprise or LDAP role, but it cannot be a filtered role.

   ---

   Persistent Cookie Mode

   Determines whether users can return to their authenticated session after restarting the browser. When enabled, a user session will not expire until its persistent cookie expires (as specified by the value of the Persistent Cookie Maximum Time attribute), or the user explicitly logs out. By default, the Authentication Service uses only memory cookies (expires when the browser is closed).

   ---

   Tip –

   A persistent cookie must be explicitly requested by the client by appending the iPSPCookie=yes parameter to the login URL. For more information see iPSPCookie Parameter.

   ---

   Persistent Cookie Maximum Time

   Specifies the interval after which a persistent cookie expires. The interval begins when the user's session is successfully authenticated. The maximum value is 2147483647 (time in seconds). The field will accept any integer value less than the maximum.

   Alias Search Attribute Name

   After a user is successfully authenticated, the user's profile is retrieved. This field specifies a second LDAP attribute to use in a search for the profile if a search using the first LDAP attribute fails to locate a matching user profile. Primarily, this attribute will be used when the user identification returned from an authentication module is not the same as that specified in User Naming Attribute. For example, a RADIUS server might return abc1234 but the user name is abc. There is no default value for this attribute. The field takes any valid LDAP attribute.

   Default Authentication Locale

   Specifies the default language subtype to be used by the Authentication Service. The default value is en_US. See Supported Language Locales in Sun OpenSSO Enterprise 8.0 Administration Reference for a list of supported language subtypes. To use a different locale, authentication templates for that locale must first be created. A new directory must then be created for these templates. For more information see locale Parameter.

   Organization Authentication Configuration

   Defines the default authentication chain used by the realm's users. The authentication chain must first be created before it is displayed as an option in this attribute's drop down list. For more information see To Create an Authentication Chain.

   Account Lockout Attributes

   These attributes are relevant to account lockout in which a user will be locked out from authenticating after a defined number of log in attempts has failed. For more information on the account lockout options, see Enabling Account Lockout.

   Login Failure Lockout Mode

   Selecting this attribute enables a physical lockout. Physical lockout will inactivate an LDAP attribute (defined in the Lockout Attribute Name property) in the user's profile. This attribute works in conjunction with several other lockout and notification attributes.

   Login Failure Lockout Count

   Defines the number of attempts that a user has to authenticate, within the time interval defined in Login Failure Lockout Interval, before being locked out.

   Login Failure Lockout Interval

   Defines (in minutes) the time in which failed login attempts are counted. If one failed login attempt is followed by a second failed attempt, within this defined lockout interval time, the lockout count is begun and the user will be locked out if the number of attempts reaches the number defined in Login Failure Lockout Count. If an attempt within the defined lockout interval time proves successful before the number of attempts reaches the number defined in Login Failure Lockout Count, the lockout count is reset.

   Email Address to Send Lockout Notification

   Specify one (or more) email address(es) to which notification will be sent if a user lockout occurs. If sending:

   • To multiple addresses, separate each address with a space.

   • To non-English locales, format the address as email_address|locale|charset where locale is the language locale and charset is the character set.

   Warn User After N Failures

   Specifies the number of authentication failures that can occur before OpenSSO Enterprise displays a warning message that the user will be locked out.

   Login Failure Lockout Duration

   Defines (in minutes) how long a user must wait after a lockout before attempting to authenticate again. Entering a value greater than 0, enables memory lockout and disables physical lockout. Memory lockout is when the user's account is locked in memory for the number of minutes specified. The account is unlocked after the time period has passed.

   Lockout Duration Multiplier

   Defines a value with which to multiply the value of the Login Failure Lockout Duration for each successive lockout. For example, if Login Failure Lockout Duration is set to 3 minutes, and the Lockout Duration Multiplier is set to 2, the user will be locked out of the account for 6 minutes. Once the 6 minutes has elapsed, if the user again provides the wrong credentials, the lockout duration would then be 12 minutes. With the Lockout Duration Multiplier, the lockout duration is incrementally increased based on the number of times the user has been locked out.

   Lockout Attribute Name

   Defines the LDAP attribute to be marked as inactive for physical lockout. The default value is inetuserstatus (although the field in the OpenSSO Enterprise console is empty). The Lockout Attribute Value field must also contain an appropriate value.

   Lockout Attribute Value

   Specifies the action to take on the attribute defined in Lockout Attribute Name. The default value is inactive (although the field in the OpenSSO Enterprise console is empty). The Lockout Attribute Name field must also contain an appropriate value.

   Invalid Attempts Data Attribute Name

   Defines the attribute to which information regarding failed authentication attempts will be stored when the Store Invalid Attempts in Data Store attribute is enabled. The value of this attribute is used if the OpenSSO Enterprise schema is not loaded.

   ---

   Tip –

   The specified attribute needs to be defined in the LDAP User Attributes property of the data store configuration if the data store type is either Active Directory, Generic LDAPv3 or Sun DS with OpenSSO schema.

   ---

   Default Success Login URL

   Accepts a list of values that specifies where users are directed after successful authentication. The format of this attribute is client-type|URL although the only value you can specify at this time is a URL which assumes the type HTML. The default value is /opensso/console. Values that don't specify HTTP or HTTP(s) will be appended to the deployment URI.

   Default Failure Login URL

   Accepts a list of values that specifies where users are directed after an attempted authentication has failed. The format of this attribute is client-type|URL although the only value you can specify at this time is a URL which assumes the type HTML. Values that don't specify HTTP or HTTP(s) will be appended to the deployment URI.

   Authentication Post Processing Classes

   Specifies one or more Java classes used to customize post authentication processes for successful or unsuccessful logins. The Java class must implement the com.sun.identity.authentication.spi.AMPostAuthProcessInterface OpenSSO Enterprise interface. Additionally, add a JAR containing the post processing class to the classpath of the web container instance on which OpenSSO Enterprise is configured. If the web container on which OpenSSO Enterprise is configured explodes the WAR follow this procedure.

   1. Stop the web container instance.

   2. Change to the WEB-INF/lib directory in the exploded OpenSSO Enterprise WAR directory.

      For example, if using Sun Application Server, AS=Deploy=BaseAS=Domain-Dir/AS-Domain/applications/j2ee-modules/opensso/WEB-INF/lib.

   3. Copy the JAR that contains the post processing class to the lib directory.

   4. Restart the web container instance.

   Generate UserID Mode

   When enabled, the Membership module will generate a list of alternate user identifiers if the one entered by a user during the self-registration process is not valid or already exists. The user identifiers are generated by the class specified in the Pluggable User Name Generator Class property.

   Pluggable User Name Generator Class

   Specifies the name of the class used to generate alternate user identifiers when Generate UserID Mode is enabled. The default value is com.sun.identity.authentication.spi.DefaultUserIDGenerator.

   Identity Types

   Lists the type or types of identities for which OpenSSO Enterprise will search. Options include:

   • Agent

   • agentgroup

   • agentonly

   • Group

   • User

   Pluggable User Status Event Classes

   Specifies one or more Java classes used to provide a callback mechanism for user status changes during the authentication process. The Java class must implement the com.sun.identity.authentication.spi.AMAuthCallBack OpenSSO Enterprise interface. Account lockout and password changes are supported — the latter through the LDAP authentication module as the feature is only available for the module.

   Store Invalid Attempts in Data Store

   Enables the storage of information regarding failed authentication attempts to a user data store, allowing the information to be shared among multiple instances of OpenSSO Enterprise. (If this attribute is not enabled, the information would be local to the instance where the lockout occurred.) This function requires the use of a data store enabled with the OpenSSO Enterprise schema and its sunAMAuthInvalidAttemptsData attribute. You can remove the dependency on the OpenSSO Enterprise schema by defining a disparate attribute in which to store the information. To store data in an attribute not defined by the OpenSSO Enterprise schema, define a value for the Invalid Attempts Data Attribute Name attribute. This is enabled by default.

   Module-based Authentication

   Enables users to authenticate using module-based authentication. Otherwise, all attempts with the module=module_instance_name login parameter will result in failure. See Module Authentication for more information.

   User Attribute Mapping to Session Attribute

   Enables the authenticating user's identity attributes (stored in the identity repository) to be set as session properties in the user's SSOToken. The value takes the format User-Profile-Attribute|Session-Attribute-Name. If Session-Attribute-Name is not specified, the value of User-Profile-Attribute is used. All session attributes contain the am.protected prefix to ensure that they cannot be edited by the Client SDK.

   Default Authentication Level

   The authentication level value indicates how much to trust authentications. Once a user has authenticated, this value is stored in the user's SSOToken. When the SSOToken is presented to an application, the application can use the stored value to determine whether the level is sufficient to grant the user access. If the authentication level does not meet the minimum value required by the application, it can prompt the user to authenticate again in order to attain a higher authentication level. The authentication level should be set within a realm's specific authentication template. The Default Authentication Level value described here will apply only when no authentication level has been specified in the Authentication Level field for a specific realm's authentication template. The Default Authentication Level default value is 0. The value of this attribute is not used by OpenSSO Enterprise but by any external application that may chose to use it. See Authentication Level-based Authentication for more information.

7. Click Save.

8. Click Back to Service Configuration.

9. Logout of the OpenSSO Enterprise console.

Configuring the Authentication Process

As discussed in Understanding the Authentication Service the authentication process itself is configured (simply) by instantiating the desired authentication module or (with more complexity) by creating an authentication chain of modules. The following sections contain the procedures for configuring an authentication process. (If you are configuring a process that includes the RADIUS, SafeWord, or Windows-based authentication modules, see Before You Begin.)

• Before You Begin

• Configuring Authentication Modules

• Creating Authentication Chains

Before You Begin

The procedures in this section are relevant when using the RADIUS, SafeWord, or the Windows-based authentication modules.

• Setting Up for RADIUS and SafeWord Authentication

• Setting Up Windows Desktop SSO Authentication

• Installing a Samba Client for Windows NT Authentication

Setting Up for RADIUS and SafeWord Authentication

To Set Up RADIUS or SafeWord with Sun Java System Application Server should be performed before configuring an authentication process that uses the RADIUS or SafeWord authentication modules.

To Set Up RADIUS or SafeWord with Sun Java System Application Server

A Java Platform, Enterprise Edition SocketPermission class represents access to a network using sockets; it consists of a host location and a set of actions specifying ways to connect to that host. When the SafeWord client forms a socket connection to its server, only the connect action of the SocketPermission object is allowed in the Application Server’s server.policy file. In order for the SafeWord authentication module to work properly, permission needs to be granted to the accept, listen, and resolve actions manually.

1. Open the server.policy file in a text editor.

2. Add an entry for the appropriate actions into the Application Server server.policy file.

   For example, permission java.net.SocketPermission "localhost:1024-", "accept,connect,listen";

   If this permission is granted to some code, it allows that code to accept connections on, connect to, or listen to any port between 1024 and 65535 on the local host. The listen action is only meaningful when used with a local host. The resolve (resolve host/IP name service lookups) action is implied when any of the other actions are present. This second example (permission java.net.SocketPermission "machine1.example.com:1645", "connect,accept";) allows the code to connect to, and accept connections on, port 1645 on machine1.example.com.

   ---

   Note –

   Granting code permission to accept or make connections to remote hosts may cause problems, because malevolent code can then more easily transfer and share confidential data among parties who may not otherwise have access to the data. Make sure to give only appropriate permissions by specifying exact port number instead of allowing a range of port numbers

   ---

3. Save the server.policy file.

4. Restart Application Server.

See Also

For more information on SocketPermission, see the Java Platform, Enterprise Edition API Specification

Setting Up Windows Desktop SSO Authentication

In addition to configuring the Windows Desktop SSO authentication module using the OpenSSO Enterprise console, a user must be created in the Windows 2000 Domain Controller and Internet Explorer must be configured.

• To Create a User in the Windows Domain Controller

• To Reduce the Size of a Kerberos Ticket

• To Set Up Internet Explorer

To Create a User in the Windows Domain Controller

1. In the domain controller, create a user account for the OpenSSO Enterprise authentication module.

   1. From the Start menu, go to Programs>Administration Tools.

   2. Select Active Directory Users and Computers.

   3. Go to Computers > New > computer and add the client computer's name.

      If you are using Windows XP, this step is performed automatically during the domain controller account configuration.

   4. Go to Users > New > Users and create a new user with the OpenSSO Enterprise host name as the User ID (login name).

      The OpenSSO Enterprise host name should not include the domain name.

2. Associate the user account with a service provider name.

3. Install the ktpass utilities to the c:\program files\support tools directory.

   The ktpass utilities are not installed as part of the Windows 2000 server. You must install it from the installation CD.

4. Export the keytab files to the system in which OpenSSO Enterprise is installed by running the following commands.

   ktpass -princ host/hostname.domainname@DCDOMAIN -pass password -mapuser userName-out hostname.host.keytab ktpass -princ HTTP/hostname.domainname@DCDOMAIN -pass password -mapuser userName-out hostname.HTTP.keytab

   The ktpass command accepts the following parameters:

   hostname. The host name (without the domain name) on which OpenSSO Enterprise runs.

   domainname . The OpenSSO Enterprise domain name.

   DCDOMAIN. The domain name of the domain controller. This may be different from the OpenSSO Enterprise domain name.

   password . The password of the user account. Make sure that password is correct, as ktpass does not verify passwords.

   userName. The user account ID. This should be the same as hostname.

   ---

   Note –

   Make sure that both keytab files are kept secure.

   ---

   The service template values should be similar to the following example:

   Service Principal: HTTP/machine1.EXAMPLE.COM@ISQA.EXAMPLE.COM

   Keytab File Name: /tmp/machine1.HTTP.keytab

   Kerberos Realm: ISQA.EXAMPLE.COM

   Kerberos Server Name: machine2.EXAMPLE.com

   Return Principal with Domain Name: false

   Authentication Level: 22

   ---

   Note –

   If you are using Windows 2003 or Windows 2003 Service Packs,, use the following ktpass command syntax:

   ktpass /out filename /mapuser username /princ HTTP/hostname.domainname /crypto encryptiontype /rndpass /ptype principaltype /target domainname

   For example:

   ktpass /out demo.HTTP.keytab /mapuser http /princ HTTP/demo.identity.sun.com@IDENTITY.SUN.COM /crypto RC4-HMAC-NT /rndpass /ptype KRB5_NT_PRINCIPAL /target IDENTITY.SUN.COM

   For syntax definitions, see KTPASS Syntax.

   ---

5. Restart the server.

To Reduce the Size of a Kerberos Ticket

All Active Directory groups to which a user belongs are encoded within an issued Kerberos ticket, increasing the size of the HTTP header. Choose one of the following options to reduce the ticket's size.

1. Increase the default maximum header size of the web container being used.

   For example, when using Glassfish replace:

   <connection-pool max-pending-count="4096" 
   queue-size-in-bytes="4096" receive-buffer-size-in-bytes="4096" 
   send-buffer-size-in-bytes="8192"/>

   with

   <connection-pool max-pending-count="4096" 
   queue-size-in-bytes="65536" receive-buffer-size-in-bytes="65536" 
   send-buffer-size-in-bytes="65536"/>

2. Disable the PAC for the OpenSSO service account

   This is the Microsoft extension to Kerberos that contains the Active Directory groups. See http://support.microsoft.com/kb/832572.

To Set Up Internet Explorer

• These steps apply to Microsoft Internet Explorer™ 6 and later. If you are using an earlier version, make sure that OpenSSO Enterprise is in the browser’s internet zone and enable Native Windows Authentication.

• Internet Explorer (5.01 or later) running on Windows 2000 (or later) currently supports SPNEGO. In addition, Mozilla 1.4 on Solaris (9 and 10) has SPNEGO support, but the token returned is only a KERBEROS token because SPNEGO is not supported on Solaris.

1. In the Tool menu, go to Internet Options > Advanced/Security > Security.

2. Select the Integrated Windows Authentication option.

3. Go to Security > Local Internet.

   1. Select Custom Level. In the User Authentication/Logon panel, select the Automatic Logon Only in Intranet Zone option.

   2. Go to Sites and select all of the options.

   3. Click Advanced and add the OpenSSO Enterprise to the local zone (if it is not added already).

Troubleshooting

If you are using Microsoft Internet Explorer 6.x for Windows Desktop SSO authentication and the browser does not have access to a Kerberos/SPNEGO token for the user that matches the (KDC) realm defined in the Windows Desktop SSO module, the browser will behave incorrectly for other modules after Windows Desktop SSO authentication fails. The direct cause of the problem is that after Windows Desktop SSO fails, the browser becomes incapable of passing all authentication module callbacks to OpenSSO Enterprise until the browser is restarted. Therefore all the modules coming after Windows Desktop SSO will fail due to null user credentials. See http://support.microsoft.com/default.aspx?scid=kb;en-us;308074 for related information.

As of this release, this restriction has been fixed by Microsoft. For more information, see http://www.microsoft.com/technet/security/bulletin/ms06-042.mspx.

Installing a Samba Client for Windows NT Authentication

To activate the Windows NT authentication module, Samba Client 3.x must be downloaded and installed. Samba is a file and print server for blending Windows and UNIX machines without requiring a separate Windows NT/2003 Server. See To Install the Samba Client for more information.

Red Hat Linux ships with a Samba client located in the /usr/bin directory.

To Install the Samba Client

1. Download the Samba software from http://www.samba.org.

2. Install the software to the OpenSSO-Deploy-base/OpenSSO-deploy-uri/bin directory.

3. (Optional) When running OpenSSO Enterprise on AIX, follow this sub procedure.

   See the Samba README for the reasons this startup script might be necessary for your deployment.

   1. Create a smbclient wrapper script.

      For example:

      #!/bin/sh
      
      unset LIBPATH
      /usr/bin/smbclient $@

   2. Copy the wrapper script to the OpenSSO-Deploy-base/OpenSSO-deploy-uri//bin directory.

4. (Optional) Set multiple interfaces by configuration of the smb.conf file which is passed to the smbclient.

Configuring Authentication Modules

Before defining an authentication process, instances of the authentication modules to be used in the process must be added in the appropriate realm. Before adding an authentication module instance to a realm, default global values can be defined which will then be carried over to any instance created from the module. Once the module instance is added to the realm, you can modify the values specifically for that realm. See Authentication Modules for information about each authentication module.

• To Define Global Values for an Authentication Module

• To Add an Authentication Module Instance to a Realm or Sub Realm

To Define Global Values for an Authentication Module

1. Log in to the OpenSSO Enterprise console as the administrator.

   By default, amadmin.

2. Click the Configuration tab.

3. Under Authentication, select the module you want to modify.

4. Modify the values for the appropriate properties and click Save.

   The default values defined globally will be assigned per realm or sub realm when the authentication module is added. See To Add an Authentication Module Instance to a Realm or Sub Realm.

To Add an Authentication Module Instance to a Realm or Sub Realm

Authentication module instances can be expressly accessed for authentication (outside of an authentication chain) by using the module authentication type. See Module Authentication for more information.

1. Log in to the OpenSSO Enterprise console as the administrator.

   By default, amadmin.

2. Click the Access Control tab.

3. Click the name of the realm under which you are adding an authentication module instance.

4. Select the Authentication tab.

5. Click New under Module Instances.

6. Enter a Name for the module instance.

   The name must be unique.

7. Select the Type of authentication module.

8. Click OK.

9. Click the name of the new instance to edit the properties for this realm.

   See Authentication in Sun OpenSSO Enterprise 8.0 Administration Reference, or click Help for definitions of the properties.

10. Click Save.

    Repeat these steps to add multiple authentication module instances.

Creating Authentication Chains

An authentication chain is a configured authentication process in which a user must pass credentials to all module instances defined in it. Authentication chains are used to define the authentication process for all authentication types except Module. See Initiating the Authentication Type for more information.

Authentication chaining is achieved using the Java Authentication and Authorization Service (JAAS) framework integrated with the Authentication Service.

To Create an Authentication Chain

Before You Begin

Instances of all authentication modules to be used in the authentication chain must first be added to the realm under which you are creating the chain. See Configuring Authentication Modules for instructions.

1. Log in to the OpenSSO Enterprise console as the administrator.

   By default, amadmin.

2. Click the Access Control tab.

3. Click the name of the realm under which you are creating a new authentication chain.

4. Select the Authentication tab.

5. Click New under Authentication Chaining.

6. Enter a name for the authentication chain and click OK.

   The chain's properties page is displayed.

7. Click Add to include the desired authentication module instance(s).

   A drop down list of authentication modules instantiated in the realm is displayed.

8. Select the desired authentication module instance from the Instance list.

9. Select the appropriate criteria for the module instance from the Criteria list.

   These flags establish the enforcement criteria for the module instance within a chain. There is a hierarchy for enforcement: REQUIRED is the highest and OPTIONAL is the lowest. More information can be found in the javax.security.auth.login.Configuration class document.

   REQUIRED

   Successful authentication to this module instance is required for the authentication process to succeed. If authentication to any REQUIRED module instances defined in a chain fails, authentication will fail. The authentication process will continue through the authentication chain whether authentication to the REQUIRED module instance succeeds or fails.

   REQUISITE

   Successful authentication to this module instance is required to proceed through the authentication chain. If authentication is successful, the authentication process moves to the next module instance in the authentication chain. If authentication fails, the chain is broken, control returns to the Authentication Service, and the user is not authenticated.

   SUFFICIENT

   Successful authentication to this module is not required but, if authentication does succeed, the user is authenticated and the authentication process will not continue through the authentication chain. If authentication to a SUFFICIENT module instance fails, the authentication process continues through the module instances in the authentication chain.

   OPTIONAL

   Successful authentication to this module instance is not required but, whether it succeeds or fails, the authentication process continues through the module instances in the authentication chain.

10. Enter options for the chain.

    This enables additional options to be defined for the module as a key=value pair. For example, if the authentication module supports debugging, enter debug=true. Multiple options are separated by a space. More information can be found in the javax.security.auth.login.Configuration class document.

11. (Optional) Add values for the following attributes.

    Successful Login URL

    Specify a URL that the user will be redirected to upon successful authentication.

    Failed Login URL

    Specify a URL that the user will be redirected to upon failed authentication.

    Post Authentication Processing Class

    Specify the name of a Java class used to customize any post authentication processes (successful or failed).

12. Click Save.

Initiating the Authentication Type

Authentication Service User Interface and Authentication Types give high level views of the types of authentication available with OpenSSO Enterprise and how the authentication type is initiated: by appending an appropriate parameter to the login URL (or programmatically using the authentication API). The base of the login URL is:

http://OpenSSO-machine-name.domain:port/service_deploy_uri/UI/Login

During installation, the service_deploy_uri is configured as opensso. This default service deployment URI will be used throughout this section.

The following sections contain more information about the specific authentication types.

• Realm Authentication

• Service Authentication

• User Authentication

• Authentication Level-based Authentication

• Module Authentication

• Role Authentication (Legacy Mode)

More information on these authentication types and the URL parameters with which they work can be found in Accessing the Authentication Service User Interface with a Login URL. Information on initiating the authentication type using the programmatic interfaces is in the Sun OpenSSO Enterprise 8.0 Developer’s Guide.

Realm Authentication

Realm authentication is the default authentication type for OpenSSO Enterprise. It allows a member of a realm to authenticate using the authentication process configured for that particular realm (or sub realm). The following sections contain more information.

• Configuring Realm Authentication

• Initiating Realm Authentication with the Login URL

• Redirecting Users After Realm Authentication

Configuring Realm Authentication

The authentication process for a realm is defined by selecting the appropriate authentication chain in the realm or sub realm's configuration.

To Configure A Realms’s Authentication Process

1. Log in to the OpenSSO Enterprise console as the administrator.

   By default, amadmin.

2. Click the Access Control tab.

3. Click the name of the realm under which you configuring an authentication process.

4. Click the Authentication tab.

5. Select the appropriate authentication chain as a value for the Default Authentication Chain attribute.

   See Creating Authentication Chains for information.

6. (Optional) Select the appropriate authentication chain as a value for the Administrator Authentication Chain attribute.

   This authentication chain is used if the authentication process for administrators needs to be different from the process for end users.

7. Click Save.

Initiating Realm Authentication with the Login URL

To initiate authentication for a member of a particular realm, append the domain=realm-name parameter or the realm=realm-name parameter to the base login URL as in:

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

If there is no defined parameter, the realm will be determined from the server host and domain specified in the login URL. The base login URL will initiate authentication for the top level realm without the realm parameter.

The realm of a request for authentication is determined from the following, in order of precedence:

1. The domain parameter.

2. The realm parameter.

3. The value of the Realm/DNS Alias Names attribute.

   After calling the correct realm, the authentication module(s) to which the user will authenticate are retrieved from the Default Authentication Chain attribute or the Administrator Authentication Chain attribute.

If User1 is authenticated to realmA and then tries to access realmB, a warning page is displayed that asks the user to authenticate to realmB with the authentication process specified for realmB, or return to the existing authenticated session with realmA. If the user chooses to authenticate to realmB, only the values of the realm and module (if specified) parameters are passed and honored for determining the new authentication process.

Redirecting Users After Realm Authentication

Upon a successful or failed realm authentication, OpenSSO Enterprise looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

• Successful Realm Authentication Redirection URL Precedence

• Failed Realm Authentication Redirection URL Precedence

Successful Realm Authentication Redirection URL Precedence

The redirection URL for successful realm authentication is determined by checking the following places in order of precedence.

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Success URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Success URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Success Login URL attribute in the realm to which the user is a member specific to the client type from which the request was received.

6. The value of the Default Success Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Success URL attribute in the user's profile.

8. The value of the Success URL attribute in the role entry of the user's profile.

9. The value of the Success URL attribute in the realm to which the user is a member.

10. The value of the Default Success Login URL attribute in the top level realm.

Failed Realm Authentication Redirection URL Precedence

The redirection URL for failed realm authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a gotoOnFail login URL parameter.

3. The value of the Failure URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Failure URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Failure Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Failure Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Failure URL attribute in the user's profile.

8. The value of the Failure URL attribute in the role entry of the user's profile.

9. The value of the Default Failure Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Failure Login URL attribute in the top level realm.

Service Authentication

Service authentication allows a user to authenticate to a specified authentication chain configured in a realm or sub realm. For authentication to be successful, the user must authenticate to each module defined in the chain. The following sections contain more information.

• Configuring Service Authentication

• Initiating Service Authentication with the Login URL

• Redirecting Users After Service Authentication

Configuring Service Authentication

To authenticate using service authentication, simply create an authentication chain in the appropriate realm.

1. Add authentication module instances to the realm. (See To Add an Authentication Module Instance to a Realm or Sub Realm.)

2. Create an authentication chain in the realm. (See Creating Authentication Chains.)

3. Create a login URL. (See Initiating Service Authentication with the Login URL.)

Initiating Service Authentication with the Login URL

To initiate the authentication process defined for a particular service, append the service=auth-chain-name parameter to the base login URL as in:

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

Additionally, you can append the realm=realm-name parameter to the base login URL as in:

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

If there is no defined realm parameter, the realm will be determined from the server host and domain specified in the login URL.

Redirecting Users After Service Authentication

Upon a successful or failed service authentication, OpenSSO Enterprise looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

• Successful Service Authentication Redirection URL Precedence

• Failed Service Authentication Redirection URL Precedence

Successful Service Authentication Redirection URL Precedence

The redirection URL for successful service authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Success URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Success URL attribute in the service to which the user is authenticated specific to the client type from which the request was received.

5. The value of the Success URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Success Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

7. The value of the Default Success Login URL attribute of the top level realm specific to the client type from which the request was received.

8. The value of the Success URL attribute in the user's profile.

9. The value of the Success URL attribute in the service to which the user is authenticated.

10. The value of the Success URL attribute in the role entry of the user's profile.

11. The value of the Default Success Login URL attribute in the realm entry of the user's profile.

12. The value of the Default Success Login URL attribute of the top level realm.

Failed Service Authentication Redirection URL Precedence

The redirection URL for failed service authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Failure URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Failure URL attribute of the service to which the user has authenticated specific to the client type from which the request was received.

5. The value of the Failure URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Failure Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

7. The value of the Default Failure Login URL attribute in the top level realm specific to the client type from which the request was received.

8. The value of the Failure URL attribute in the user's profile.

9. The value of the Failure URL attribute of the service to which the user has authenticated.

10. The value of the Failure URL attribute in the role entry of the user's profile.

11. The value of the Default Failure Login URL attribute in the realm entry of the user's profile

12. The value of the Default Failure Login URL attribute in the top level realm.

User Authentication

User authentication allows a user to authenticate using an authentication chain specifically defined as a value of the User Authentication Configuration attribute in the user’s profile. For authentication to be successful, the user must authenticate to each module defined in the chain. The following sections contain more information.

• Configuring User Authentication

• Initiating User Authentication with the Login URL

• Redirecting Users After User Authentication

Configuring User Authentication

To authenticate using user authentication, simply create an authentication chain in the appropriate realm and select it in the user's profile.

1. Add authentication module instances to the realm. (See To Add an Authentication Module Instance to a Realm or Sub Realm.)

2. Create an authentication chain in the realm. (See Creating Authentication Chains.)

3. Select the authentication chain as the value for the User Authentication Configuration attribute in the user's profile. (See To Configure A User Authentication Process.)

4. Create a login URL. (See Initiating Service Authentication with the Login URL.)

To Configure A User Authentication Process

1. Log in to the OpenSSO Enterprise console as the administrator.

   By default, amadmin.

2. Click the Access Control tab.

3. Click the name of the realm that contains the user for whom you are configuring an authentication process.

4. Click the Subjects tab.

5. Under the User tab, click the user's Name.

6. Select the appropriate authentication chain as a value for the User Authentication Configuration attribute.

7. Click Save.

Initiating User Authentication with the Login URL

To initiate the authentication process defined for a particular user, append the user=Universal-ID parameter to the base login URL as in:

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

Additionally, you can append the realm=realm-name parameter to the base login URL as in:

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

If there is no defined realm parameter, the realm will be determined from the server host and domain specified in the login URL.

The User Alias List attribute in the User profile is where the disparate Universal IDs defined for one user are mapped. On receiving a request for user authentication, the Authentication Service first verifies that the Universal ID passed with the login URL maps to a valid user. It then retrieves the specified Authentication Configuration data from the user's profile. In the case, for example, where there is more than one module in the authentication chain and a different Universal ID is defined for the user, all user profiles must map to the Universal ID specified in the URL or the user will be denied a validated SSOToken. An exception would be if one of the Universal IDs belongs to a top level administrator whereby the user mapping validation is not done and the user is given top level administrator rights.

Redirecting Users After User Authentication

Upon a successful or failed user authentication, OpenSSO Enterprise looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

• Successful User Authentication Redirection URL Precedence

• Failed User Authentication Redirection URL Precedence

Successful User Authentication Redirection URL Precedence

The redirection URL for successful user authentication is determined by checking the following places in order of precedence:

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Success URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Success URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Success Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Success Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Success URL attribute in the user's profile.

8. The value of the Success URL attribute in the role entry of the user's profile.

9. The value of the Default Success Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Success Login URL attribute in the top-level realm.

Failed User Authentication Redirection URL Precedence

The redirection URL for failed user authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a gotoOnFail login URL parameter.

3. The value of the Failure URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Failure URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Failure Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Failure Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Failure URL attribute in the user's profile.

8. The value of the Failure URL attribute in the role entry of the user's profile.

9. The value of the Failure URL attribute in the realm entry of the user's profile.

10. The value of the Default Failure Login URL attribute in the top-level realm.

Authentication Level-based Authentication

Authentication Level—based authentication allows an administrator to specify the security level of the authentication modules used in a particular authentication process. Each authentication module can be assigned an authentication level — an integer defined as the value of the module's Authentication Level attribute. A user that has successfully authenticated to an authentication module with a higher authentication level is deemed to have a higher level of trust. If successfully authenticate, the authentication level of the module will be set in the user’s SSOToken. (If the user has successfully authenticated to multiple authentication modules, the highest authentication level will be set in the user’s SSOToken.) Now when the user attempts to access a service which demands authentication trust at a particular level, the service can use the authentication level to determine if the user is meets the criteria. If not, the user is redirected to authenticate to an authentication module with the appropriate authentication level. The following sections contain more information.

• Configuring Authentication Levels

• Initiating Authentication Level-based Authentication with the Login URL

• Redirecting Users After Authentication Level-based Authentication

Configuring Authentication Levels

To set an authentication level for an authentication module, simply define an integer in the Authentication Level attribute of the desired authentication module.

• To set a global authentication level for a module, see To Define Global Values for an Authentication Module.

• To set the authentication level for an authentication module instance within a realm, see To Add an Authentication Module Instance to a Realm or Sub Realm.

Initiating Authentication Level-based Authentication with the Login URL

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 login URL's parameter. Users can select a module from the presented list. Once the user selects a module, the remaining process is based on Module Authentication. (See Module Authentication.)

To initiate Authentication Level-based authentication, append the authlevel=auth-level-value parameter to the base login URL as in:

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

Additionally, you can append the realm=realm-name parameter to the base login URL as in:

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

If there is no defined realm parameter, the realm will be determined from the server host and domain specified in the login URL.

All modules whose authentication level is larger or equal to auth-level-value will be displayed in an authentication menu. After the authentication menu with the relevant list of modules is displayed, the user must choose one with which to authenticate. If only one matching module is found, then the login page for that authentication module will be directly displayed.

Redirecting Users After Authentication Level-based Authentication

Upon a successful or failed authentication level-based authentication, OpenSSO Enterprise looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

• Successful Authentication Level-based Authentication Redirection URL Precedence

• Failed Authentication Level-based Authentication Redirection URL Precedence

Successful Authentication Level-based Authentication Redirection URL Precedence

The redirection URL for successful authentication level-based authentication is determined by checking the following places in order of precedence:

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Success URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Success URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Success Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Success Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Success URL attribute in the user's profile.

8. The value of the Success URL attribute in the role entry of the user's profile.

9. The value of the Default Success Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Success Login URL attribute in the top level realm.

Failed Authentication Level-based Authentication Redirection URL Precedence

The redirection URL for failed authentication level-based authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a gotoOnFail login URL parameter.

3. The value of the Failure URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Failure URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Failure Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Failure Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Failure URL attribute in the user's profile.

8. The value of the Failure URL attribute in the role entry of the user's profile.

9. The value of the Default Failure Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Failure Login URL attribute in the top level realm.

Module Authentication

Module authentication allows a user to specify the authentication module with which they will authenticate. The specified module must be added as a module instance in the realm or sub realm that the user is accessing. On receiving a request for module authentication, the Authentication Service verifies that the module is correctly configured as noted; if the module is not defined, the user is denied access. The following sections contain more information.

• Configuring Module Authentication

• Initiating Module Authentication with the Login URL

• Redirecting Users After Module Authentication

Configuring Module Authentication

To use module authentication, simply create an instance of the authentication module in the appropriate realm. See To Add an Authentication Module Instance to a Realm or Sub Realm.

Initiating Module Authentication with the Login URL

To initiate the authentication using a particular authentication module, append the module=auth-module-name parameter to the base login URL as in:

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

Additionally, you can append the realm=realm-name parameter to the base login URL as in:

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

If there is no defined realm parameter, the realm will be determined from the server host and domain specified in the login URL.

Redirecting Users After Module Authentication

Upon a successful or failed module authentication, OpenSSO Enterprise looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

• Successful Module Authentication Redirection URL Precedence

• Failed Module Authentication Redirection URL Precedence

Successful Module Authentication Redirection URL Precedence

The redirection URL for successful module authentication is determined by checking the following places in order of precedence:

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Success URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Success URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Success Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Success Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Success URL attribute in the user's profile.

8. The value of the Success URL attribute in the role entry of the user's profile.

9. The value of the Default Success Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Success Login URL attribute in the top level realm.

Failed Module Authentication Redirection URL Precedence

The redirection URL for failed module authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a gotoOnFail login URL parameter.

3. The value of the Failure URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Failure URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Failure Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Failure Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Failure URL attribute in the user's profile.

8. The value of the Failure URL attribute in the role entry of the user's profile.

9. The value of the Default Failure Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Failure Login URL attribute in the top level realm.

Role Authentication (Legacy Mode)

Role authentication allows a user to authenticate as a member of a specified role (either static or filtered) configured within a realm or sub realm. Role authentication is only available when the Access Manager SDK (AMSDK) Identity Repository Plug-in is enabled. See Chapter 15, Enabling the Access Manager SDK (AMSDK) Identity Repository Plug-in, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide for requirements and procedures to enable this legacy feature.

For role authentication to be initiated, the user must belong to the role and authenticate to each module defined in the authentication chain specified for that role. The following sections contain more information.

• Configuring Role Authentication

• Initiating Role Authentication with the Login URL

• Redirecting Users After Role Authentication

Configuring Role Authentication

The authentication method for a role is set by adding the legacy Authentication Configuration Service to the role and choosing the appropriate authentication chain from the displayed choices.

To Configure An Authentication Process for a Role

1. Log in to the OpenSSO Enterprise console as the administrator.

   By default, amadmin.

2. Click the Access Control tab.

3. Click the name of the realm that contains the role for which you are configuring an authentication process.

4. Click the Subjects tab.

5. Click the Roles tab.

6. Click the name of the role you are configuring.

7. Click the Services tab.

8. Click Add.

9. Select Authentication Configuration and click Next.

10. Select the appropriate authentication chain from those displayed.

    See Creating Authentication Chains.

11. Click Finish.

Initiating Role Authentication with the Login URL

To initiate the authentication process defined for a particular role, append the role=role-name parameter to the base login URL as in:

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

A user who is not a member of the specified role will receive an error message when they attempt to authenticate using this parameter.

Redirecting Users After Role Authentication

Upon a successful or failed role authentication, OpenSSO Enterprise looks for information on where to redirect the user. Following is the order of precedence in which the application will look for this information.

• Successful Module Authentication Redirection URL Precedence

• Failed Module Authentication Redirection URL Precedence

Successful Role Authentication Redirection URL Precedence

The redirection URL for successful role authentication is determined by checking the following places in order of precedence:

1. A URL set by the authentication module.

2. A URL set by a goto login URL parameter.

3. The value of the Success URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Success URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Success URL attribute in another role entry of the user's profile specific to the client type from which the request was received. (This option is a fallback if the previous redirection URL fails.)

6. The value of the Default Success Login URL attribute in the realm to which the user is a member specific to the client type from which the request was received.

7. The value of the Default Success Login URL attribute in the top level realm specific to the client type from which the request was received.

8. The value of the Success URL attribute in the user's profile.

9. The value of the Success URL attribute in the role entry of the user's profile.

10. The value of the Success URL attribute in another role entry of the user's profile. (This option is a fallback if the previous redirection URL fails.)

11. The value of the Default Success Login URL attribute in the realm to which the user is a member.

12. The value of the Default Success Login URL attribute in the top level realm.

Failed Role Authentication Redirection URL Precedence

The redirection URL for failed role authentication is determined by checking the following places in the following order:

1. A URL set by the authentication module.

2. A URL set by a gotoOnFail login URL parameter.

3. The value of the Failure URL attribute in the user's profile specific to the client type from which the request was received.

4. The value of the Failure URL attribute in the role entry of the user's profile specific to the client type from which the request was received.

5. The value of the Default Failure Login URL attribute in the realm entry of the user's profile specific to the client type from which the request was received.

6. The value of the Default Failure Login URL attribute in the top level realm specific to the client type from which the request was received.

7. The value of the Failure URL attribute in the user's profile.

8. The value of the Failure URL attribute in the role entry of the user's profile.

9. The value of the Default Failure Login URL attribute in the realm entry of the user's profile.

10. The value of the Default Failure Login URL attribute in the top level realm.

11. The value of the Success URL attribute in the role entry of the user's profile.

12. The value of the Success URL attribute in another role entry of the user's profile. (This option is a fallback if the previous redirection URL fails.)

Accessing the Authentication Service User Interface with a Login URL

The Authentication Service user interface is accessed by entering a login URL into the Location Bar of a web browser. Authentication Service User Interface and Authentication Types give views of this login URL and how the authentication type is initiated by appending the appropriate parameter to the login URL. 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

During installation, the service_deploy_uri is configured as opensso. This default service deployment URI will be used throughout this section.

In addition to the parameters documented in Authentication Types, there are others 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.

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

• goto Parameter

• gotoOnFail Parameter

• realm Parameter

• user Parameter

• locale Parameter

• module Parameter

• service Parameter

• arg Parameter

• authlevel Parameter

• forceAuth Parameter

• IDTokenN Parameters

• iPSPCookie Parameter

• PersistAMCookie Parameter

• role Parameter (Legacy Mode)

• org Parameter (Legacy Mode)

• domain Parameter (Legacy Mode)

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

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=A 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/Login?
goto=A 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 the Authentication 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?
goto=A 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 the Authentication 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 To Modify Core Authentication Properties By Realm.

• 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 Sun OpenSSO Enterprise 8.0 Administration Reference for a list of supported language subtypes.

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.

5. Locale defined in Platform Service

   This is the value of the Platform Locale attribute in the 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.

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

The authentication module names are case-sensitive when used in a URL parameter.

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 is 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. (forceAuth=false is the default but is not explicitly appended to the URL.) forceAuth 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. If authentication is successful, the existing session token is updated accordingly. If authentication fails, the existing session token is still valid but it is not updated.

• 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 (forceAuth=true is not appended to the URL), the user is prompted to authenticate again using the Data Store authentication module. After successfully authenticating to the second module, OpenSSO Enterprise creates a new session token, 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 (forceAuth=true is appended to the URL), the user is prompted to authenticate again but, after successfully authenticating using Data Store, the existing session token is updated.

See Upgrading Sessions for more information.

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 the 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. For example:

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 the Core Authentication Service.

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

Customizing Authentication

The following sections contain information on several features of the Authentication Service and the procedures used to enable them.

• Enabling Account Lockout

• Authentication Service Failover

• Mapping Fully Qualified Domain Names

• Using Persistent Cookies

• Upgrading Sessions

• Sharing User Credentials Among Authentication Modules (Shared State)

• Redirecting Users After Authentication

• Configuring Multiple LDAP Authentication Modules (Legacy Mode)

Enabling Account Lockout

The Authentication Service provides a feature where a user will be locked out from authenticating after a defined number of log in attempts has failed. By default, account lockout is disabled. When enabled, email notifications are sent to administrators regarding any account lockouts as well as recorded by the Logging Service. Only authentication modules that throw an Invalid Password Exception can leverage the Account Locking feature. These include Active Directory, Data Store, HTTP Basic, JDBC, LDAP, RADIUS, SafeWord, SecurID, and Unix. OpenSSO Enterprise supports two types of account lockout.

Physical Lockout

This is the default lockout behavior, initiated by changing the status of a specified LDAP attribute in the user’s profile to inactive. (The specified LDAP attribute is defined as the value of the Lockout Attribute Name attribute in the Core authentication module.) When physical account lockout is enabled an attribute in the user data store is used to hold information regarding the authentication attempts. This information includes:

• Invalid attempts count

• Last failed time

• Lockout time

• Lockout duration

---

Note –

An aliased user is one that is mapped to an existing LDAP user profile through configuration of the User Alias List Attribute in the user profile. If an aliased user is locked out, the actual LDAP profile to which the user is aliased will be locked. This pertains only to physical lockout with authentication modules other than LDAP and Membership.

---

Memory Lockout

Memory lockout is enabled by changing the value of the Login Failure Lockout Duration attribute (which defines how long a user must wait after a lockout before attempting to authenticate again) to a value greater then 0. The user's account is then locked in memory for the number of minutes specified. The account is unlocked after the time period has passed. There are special considerations when using the memory locking feature.

• If OpenSSO Enterprise is restarted, all accounts locked in memory are unlocked.

• If a user’s account is locked in memory and the administrator resets the account lockout mechanism to physical lockout (by changing the value of the Login Failure Lockout Duration to 0), the user’s account will be unlocked in memory and the lock count reset.

• During a memory lockout, if the user attempts to authenticate with the correct password (using authentication modules other than LDAP and Membership), a User does not have profile in this realm error. message is returned rather than a User is not active. error.

• If the Failure URL attribute in the user’s profile is defined, neither the lockout warning message nor the message indicating that the account has been locked will be displayed; the user will be redirected to the defined URL.

For information on the account lockout attributes, see Configuring the Core Authentication Service.

Authentication Service Failover

The Authentication Service will automatically redirect an authentication request to a second server if the primary server becomes unavailable because of a hardware or software problem, or if the server is temporarily shut down. The Authentication Service URL is first passed to an instance of the com.sun.identity.authentication.AuthContext class. If this URL is unavailable, locations defined in the Servers attribute of the primary OpenSSO Enterprise instance's configuration will be checked and, if one is available, an authentication context will be created for this second instance of OpenSSO Enterprise through the authentication failover mechanism. (For more information, see Servers and Sites in Sun OpenSSO Enterprise 8.0 Administration Reference.)

Failing the Servers and Sites check, the authentication context queries the Platform list from a server where the Naming service is available This platform list is automatically created when multiple instances of OpenSSO Enterprise are installed (generally, for failover purposes) sharing a one instance of the configuration data store.

For example, if the platform list contains URLs for Server1, Server2 and Server3, then the authentication context will loop through Server1 , Server2 and Server3 until authentication succeeds on one of them.

The platform list may not always be obtained from the same server, as it depends on the availability of the Naming service. Furthermore, Naming service failover may occur first. Multiple Naming service URLs are specified in the Naming Service. The first available Naming service URL will be used to identify the server, which will contain the list of servers (in its platform server list) on which authentication failover will occur.

Mapping Fully Qualified Domain Names

Fully Qualified Domain Name (FQDN) mapping enables the Authentication Service to take corrective action in the case where a user may have typed in an incorrect URL (such as specifying a partial host name or IP address to access protected resources). FQDN mapping is enabled by modifying the com.sun.identity.server.fqdnMap attribute in the in the Advance Properties for Servers and Sites. For more information, see Advanced in Sun OpenSSO Enterprise 8.0 Administration Reference. The format for specifying this property is:

com.sun.identity.server.fqdnMap[invalid-name ]=valid-name

The value invalid-name would be a possible invalid FQDN host name that may be typed by the user, and valid-name would be the actual host name to which the filter will redirect the user. Any number of mappings can be specified as long as they conform to the stated requirements. If this property is not set, the user would be sent to the default server name configured in the server_name property.

Possible Uses For FQDN Mapping

This property can be used for creating a mapping for more than one host name which may be the case if applications hosted on a server are accessible by more than one host name. This property can also be used to configure OpenSSO Enterprise to not take corrective action for certain URLs. For example, if no redirect is required for users who access applications by using an IP address, this feature can be implemented by specifying a map entry such as:

com.sun.identity.server.fqdnMap[IP address ]=IP address.

If more than one mapping is defined, ensure that there are no overlapping values in the invalid FQDN name. Failing to do so may result in the application becoming inaccessible.

Using Persistent Cookies

A persistent cookie is one that continues to exist after the web browser is closed, allowing a user to login with a new browser session without having to re-authenticate. The cookie value is a 3DES-encrypted string containing the userDN, realm name, authentication module name, maximum session time, idle time, and cache time. To Use Persistent Cookies contains the procedure to enable this function.

Persistent cookies do not work with the Distributed Authentication User Interface or when using Cross Domain Single Sign-on. If enabled and using either of these options, a regular cookie will be created.

To Use Persistent Cookies

Programmatically, Persistent Cookie mode can be enabled by using the setPersistentCookieOn() method of the com.sun.identity.authentication.spi.AMLoginModule class. See Chapter 1, Using the Authentication Service API and SPI, in Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information.

1. Configure the Authentication Service to use persistent cookies in the Core authentication module.

   Enable the Persistent Cookie Mode attribute and modify, if necessary, the value of the Persistent Cookie Maximum Time attribute. See To Modify Core Authentication Properties By Realm for the procedure.

2. (Optional) Modify the persistent cookie name using this sub procedure.

   1. Click Servers and Sites under the Configuration tab.

   2. Click Default Server Settings.

   3. Click Advanced.

   4. Change the value of the com.iplanet.am.pcookie.name property.

      The default value is DProPCookie.

   5. Click Save.

3. Append the iPSPCookie=yes parameter to the User Interface Login URL.

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

   Once the user authenticates using this URL, if the browser is closed, the user can open a new browser window and will be redirected to the console without re-authenticating. This will work until the time defined as the value of Persistent Cookie Maximum Time elapses.

Upgrading Sessions

The Authentication Service enables you to upgrade a valid session token based on a second, successful authentication performed by the same user to the same realm. If a user with a valid session token attempts to authenticate to a resource secured by his current realm and this second authentication request is successful, the session is updated with the properties based on the new authentication. If the authentication fails, the user’s current session is returned without an upgrade. If the user with a valid session attempts to authenticate to a resource secured by a different realm, the user will receive a message asking whether they would like to authenticate to the new realm. The user can, at this point, maintain the current session or attempt to authenticate to the new realm. Successful authentication to the new realm will result in the old session being destroyed and a new one being created.

During session upgrade, if a login page times out, redirection to the original success URL will occur. Timeout values are determined based on:

• The value of the timeout attribute of the Callback property of the page in each authentication module's specific XML file. The default value is 1 minute. This value can not be set using the OpenSSO Enterprise console.

• The value of the Invalidate Session Max Time property is the duration (in minutes) after which an invalid session will be removed from the session table after it is created but before the user logs in.

  1. Click Servers and Sites under the Configuration tab.

  2. Click Default Server Settings.

  3. Click the Session tab to modify Invalidate Session Max Time.

• The value of the Maximum Session Time attribute; by default, 120 minutes.

  1. Click Global under the Configuration tab.

  2. Click Session in the Service Name list.

  3. Modify Maximum Session Time.

The values of Invalidate Session Max Time and Maximum Session Time should be greater than the value of the timeout attribute; otherwise, the valid session information during session upgrade will be lost and URL redirection to the previous successful URL will fail.

Sharing User Credentials Among Authentication Modules (Shared State)

The Java Authentication and Authorization Service (on which the Authentication Service is built) has an option to enable shared state which allows for sharing of both the user ID and password between authentication modules. For example, assume an authentication chain is configured as follows:

• LDAP authentication is REQUIRED and shared state is enabled.

• Data Store authentication is REQUIRED and shared state is enabled. Additionally, the shared state behavior is configured to use the first pass.

For this authentication process, the user would be presented with an LDAP login page to enter a user ID and password. Assuming successful LDAP authentication, these credentials would then be passed to the Data Store module on the backend; the user would not see a Data Store login page. If Data Store authentication is successful, the user would be redirected to the appropriate page.

The shared state is enabled by entering the appropriate options to the authentication module as you configure an authentication chain. The options are:

iplanet-am-auth-shared-state-enabled

This option enables the use of a shared state map.

iplanet-am-auth-store-shared-state-enabled

This option enables the storage of credentials to a shared state map.

iplanet-am-auth-shared-state-behavior-pattern

To prevent a user from having to enter the user ID and password twice for authentication, set this option to useFirstPass for all modules in the chain (except the first). tryFirstPass (the default value) would prompt for new credentials if the shared state credentials failed

After a commit, an abort or a logout, the shared state will be cleared. To add shared state options to an authentication module in an authentication chain, see Creating Authentication Chains.

Redirecting Users After Authentication

Redirecting users to a particular URL upon successful or failed authentication can be configured in a number of ways.

• To set the redirection URL globally or per realm, see Configuring the Core Authentication Service.

• To set the redirection URL as a login URL parameter, see Accessing the Authentication Service User Interface with a Login URL.

• To set the redirection URL for a specific user, see Chapter 5, Creating Subjects.

Information on how the precedence of redirection URLs is determined is in Initiating the Authentication Type.

Configuring Multiple LDAP Authentication Modules (Legacy Mode)

As a form of failover or to configure multiple values for an attribute when the OpenSSO Enterprise console only provides one value field, an administrator can define multiple LDAP authentication module configurations under one realm. Although these additional configurations are not visible from the console, they work in conjunction with the primary configuration if an initial search for the requesting user’s authorization is not found. For example, one realm can define a search through LDAP servers for authentication in two different domains or it can configure multiple user naming attributes in one domain. For the latter, which has only one text field in the console, if a user is not found using the primary search criteria, the LDAP module will then search using the second scope. Following are the steps to configure additional LDAP configurations.

To Configure Multiple LDAP Authentication Modules

Any additional LDAP authentication module configurations created using this procedure can not be seen or modified using the OpenSSO Enterprise console.

1. Write an XML file including the complete set of attributes and new values needed for a second (or third) LDAP authentication configuration.

   The available LDAP authentication module attributes are in the amAuthLDAP.xml file. Any or all of these attributes can be used for the additional LDAP configurations defined in this step. Following is an example of a sub-configuration file that includes values for all attributes available to the LDAP authentication configuration.

   > <!-- Before adding subConfiguration load the schema with GlobalConfiguration defined and replace corresponding serviceName and subConfigID in this sample file OR load serviceConfigurationRequests.xml before loading this sample --> <Requests> <realmRequests DN="dc=iplanet,dc=com"> <AddSubConfiguration subConfigName = "ssc" subConfigId = "serverconfig" priority = "0" serviceName="iPlanetAMAuthLDAPService"> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-server"/> <Value>vbrao.red.iplanet.com:389</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-base-dn"/> <Value>dc=iplanet,dc=com</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="planet-am-auth-ldap-bind-dn"/> <Value>cn=amldapuser,ou=DSAME Users,dc=iplanet,dc=com</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-bind-passwd"/> <Value>plain text password</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-user-naming-attribute"/> <Value>uid</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-user-search-attributes"/> <Value>uid</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-search-scope"/> <Value>SUBTREE</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-ssl-enabled"/> <Value>false</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-return-user-dn"/> <Value>true</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-auth-level"/> <Value>0</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="iplanet-am-auth-ldap-server-check"/> <Value>15</Value> </AttributeValuePair> </AddSubConfiguration> </realmRequests> </Requests>

2. Load the XML file using the ssoadm command line tool.