Sun OpenSSO Enterprise 8.0 Administration Guide

Part I Access Control

This is part one of the Sun OpenSSO Enterprise 8.0 Administration Guide. The Access Control interface provides a way to create and manage authentication and authorization services to protect and regulate realm-based resources. When an enterprise user requests information, OpenSSO Enterprise verifies the user's identity and authorizes the user to access the specific resource that the user has requested. The part contains the following chapters:

Chapter 1 Logging In To The Console

The OpenSSO Enterprise console is a web interface that allows both administrators and users without administrative privileges to log in and manage their respective entitlements. Depending on the level of access defined, an administrator can create realms, modify user membership in the realms, configure authentication chains, define data stores, and establish enforcement policies to protect and limit access to the realm's resources. In addition, administrators can view and terminate current user sessions and manage their federation configurations (create, delete and modify authentication domains and entity providers). Users without administrative privileges, on the other hand, can manage personal information (name, email address, password, telephone number, and so forth), subscribe and unsubscribe to groups, and view their roles. The following sections describe the different console views this functionality offers.

Administrator Interface

When a user with an administrative role authenticates to OpenSSO Enterprise, the administrator view is displayed, by default. Using this interface, the administrator can accomplish most administrative tasks related to OpenSSO Enterprise. This includes realm-based access control, global service configuration, and web services and federation management. To access the Administrator Interface login screen, use protocol://machine-name:port/uri/UI/Login as the URL syntax where protocol is either http or https depending upon your deployment.

User Interface

When a user who has not been assigned an administrative role authenticates to OpenSSO Enterprise, the user's own profile is displayed. Using this interface, a user can modify the values of the personal profile attributes. This can include, but is not limited to, name, home address and password. To access the User Profile Interface login screen, use protocol://machine-name:port/uri/UI/Login as the URL syntax where protocol is either http or https depending upon your deployment. Although the URL for both the Administrator and Personal Profile interfaces is the same, entering the username and password of a user who has not been assigned an administrative role will direct the user to the User Profile interface.


Tip –

The User Profile interface is based on information defined in the amUser.xml service file.


Legacy Support

Legacy support in OpenSSO Enterprise is based on the Sun Java System Access Manager 6.3 architecture. When OpenSSO Enterprise is deployed in legacy mode, the console is different from when it is installed in the default realm mode. In OpenSSO Enterprise 8.0 legacy mode is supported through upgrade only; if you have Access Manager 7.0 or 7.1 installed in legacy mode, you can upgrade to OpenSSO Enterprise 8.0 and keep legacy mode. For more information, see the Sun OpenSSO Enterprise 8.0 Upgrade Guide.


Caution – Caution –

Legacy support is deprecated and will be removed in a future release. It is strongly recommended not to use this option.


Chapter 2 Organizing Data within Realms

A realm is the unit that OpenSSO Enterprise uses to manage resources. The following sections describe how to manage OpenSSO Enterprise using the realm mode.

After OpenSSO Enterprise is deployed and configured, the default / (Top Level Realm) is created. The top-level realm is the root realm of the OpenSSO Enterprise instance; it cannot be changed after it is created. In general, you should use the top-level realm to configure identity data stores, and manage policies and authentication chains.

For more information on realms, see Realms in Sun OpenSSO Enterprise 8.0 Technical Overview.

Understanding Realms

A realm is the administrative unit for OpenSSO Enterprise. After OpenSSO Enterprise is deployed and configured, the default / (Top Level Realm) is created. The top-level realm is the root realm that, with the exception of bootstrapping information configured during installation, contains the configuration data for the OpenSSO Enterprise instance. The top-level realm can contain sub realms. Sub realms under the top-level realm can also contain sub realms. Information that can be defined in the top-level or a sub realm includes:

The hierarchy of a top-level and sub realms can be used to identify users and groups with different authentication and authorization requirements. For example, users in the Human Resources department have access to more sensitive data than other users in an organization. By creating a sub realm for Human Resources personnel, you can enforce an authentication chain that might include entering an LDAP user identifier and password followed by a token generated using a SafeWord card. On the other hand, users not defined in this sub realm might need only enter an LDAP user identifier and password to access their own personal profile. The use of sub realms should be restricted to either of the following scenarios:

Creating and Modifying Realms

This section describes how to create a realm and modify its General properties post creation.

ProcedureTo Create a New Realm

Before You Begin

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

  1. Select New from the Realms list under the Access Control tab.

  2. Define the following General attributes:

    Name

    Enter a name for the realm.

    Parent

    Select the parent realm under which the new realm will exist.

  3. Define the following Realm attributes:

    Realm Status

    Select Active or Inactive. The default is Active. This can be changed at any time during the life of the realm by selecting the Properties icon. Selecting Inactive disables user access when logging in.

    Realm/DNS Aliases

    Allows you to configure a DNS-type alias for the realm. This attribute only accepts “real” domain aliases (as in .sun.com). Random strings are not allowed.

  4. Click OK to save the realm.

ProcedureTo Modify a Realm's General Properties

Before You Begin

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

  1. Click the Access Control tab.

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

  3. Edit the appropriate values.

  4. Click OK to save the realm.

Managing Configuration Data Within Realms

To manage configuration data stored within a realm, click the Realm Name under the Access Control tab in the OpenSSO Enterprise console. The following sections contain more information (or links to more information) regarding the configuration data.

Managing Authentication

Authentication properties and processes may be customized by realm. Default values for authentication are defined in the Core authentication module under the Configuration tab in the OpenSSO Enterprise console. These values will be inherited when a new realm is created but, you can modify a particular value per realm. For more information on configuring for authentication and managing authentication processes, see Chapter 3, Configuring Authentication.

Adding Services

A number of services can be added to a realm for more fine-grained configuration. These services may contain Global attributes (which are common to the OpenSSO Enterprise instance and inherited by all configured realms), Realm attributes (which can be customized per realm after the service has been added to it) and Dynamic attributes (which are inherited by users that belong to the realm in which the value is defined). Default values for all attributes in these services can be defined under the Configuration tab in the OpenSSO Enterprise console. The services that can be added to a realm include:

Administration

The Administration service is used to customize tasks performed by the OpenSSO Enterprise console. Default values for the Administration service are defined for the console under the Configuration tab in the OpenSSO Enterprise console. By adding the Administration service to a realm, the realm's administrator can customize these values per realm.

Discovery Service

An identity service is a web service that supports the query and modification of data regarding a principal. An identity service might host, for example, a principal's profile, such as name, address and phone number, or it might hold more sensitive information like a credit card number. The initial step in accessing the identity data a client is requesting is to determine in which identity service it is hosted. A resource offering defines the association between a piece of identity data and the identity service that provides access to it. A discovery service is a registry of resource offerings. By adding the Discovery Service to a realm, the realm's administrator can add resource offerings at the realm level as opposed to the user level.


Note –

This functionality is designed for business to business use cases.


Globalization Settings

The Globalization Settings service contains attributes to customize OpenSSO Enterprise for different locales and character sets. Default values for the Globalization Settings service are defined for the console under the Configuration tab in the OpenSSO Enterprise console. By adding the Globalization Settings service to a realm, the realm's administrator can customize these values per realm.

Password Reset

The Password Reset service allows users to reset their configured password or to receive an email message containing a new password. The Password Reset service does not need to be added to the realm in which a user resides to work. If the Password Reset service is not added to the realm in which the user resides, it will inherit the attribute values defined globally for the service under the Configuration tab in the OpenSSO Enterprise console. By adding the Password Reset service to a realm, the realm's administrator can customize these values per realm.

Policy Configuration

The Policy Configuration service is added to a realm, by default, when the realm is created. Default values for the Policy Configuration service are defined globally under the Configuration tab in the OpenSSO Enterprise console but the realm's administrator can customize them as needed. The service contains properties related to the Policy Service itself.

Session

The Session service defines values for properties that pertain to an authenticated user's session. This includes information such as maximum session time and maximum idle time. Default values for the Session service are defined globally under the Configuration tab in the OpenSSO Enterprise console. By adding the Session service to a realm, the realm's administrator can customize certain properties per realm.

User

Default user preferences for properties like time zone and locale are defined with the User service. Default values for the User service are defined globally under the Configuration tab in the OpenSSO Enterprise console. By adding the User service to a realm, the realm's administrator can customize certain properties per realm.

The following procedures pertain to adding and managing a realm's services.

ProcedureTo Add a Service to a Realm

Before You Begin

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

  1. Click the Access Control tab.

  2. Click the name of the realm to which the service will be added.

  3. Click the Services tab.

  4. Click Add in the Services list.

  5. Select the service you want to add.

  6. Click Next.

  7. Configure the service by defining values for the appropriate attributes.

  8. Click Finish.

    The service will be listed under Services.

ProcedureTo Modify the Attributes of a Realm's Added Services

Before You Begin

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

  1. Click the Access Control tab.

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

  3. Click the Services tab.

  4. Click the name of the service you are modifying.

  5. Edit the appropriate values.

  6. Click Save to save the new values.

Plugging in Data Stores

A data store is a database where you can store user attributes and user configuration data. OpenSSO Enterprise provides identity repository plug-ins that connect to an LDAPv3 identity repository framework. These plug-ins enable you to view and retrieve OpenSSO Enterprise user information without having to make changes in your existing user database. The OpenSSO Enterprise framework integrates data from the identity repository plug-in with data from other OpenSSO Enterprise plug-ins to form a virtual identity for each user. OpenSSO Enterprise can then use the universal identity in authentication and authorization processes among more than one identity repository. The virtual user identity is destroyed when the user's session ends.

An identity repository is a data store where information about users is stored. The data store might contain, for example, a user identifier and password, email address, application preferences and other forms of identity data. OpenSSO Enterprise provides an interface that enables a realm administrator to plug one or more identity data stores in to a realm. These plug-ins enable you to view and retrieve OpenSSO Enterprise user information without having to make changes in your existing user database. The OpenSSO Enterprise framework integrates data from the identity repository plug-in with data from other OpenSSO Enterprise plug-ins to form a virtual identity for each user. Because the plug-ins allow more than one identity data store to be configured per realm, OpenSSO Enterprise can access the many profiles of one identity across multiple identity repositories. This allows for the virtual identity for each user to be accessed for purposes of authentication and authorization. You can create a new data store instance using the following data store types:

Active Directory

This data store type uses the LDAP version 3 specification to write identity data to an instance of Microsoft Active Directory.

Generic LDAPv3

This data store type allows identity data to be written to any LDAPv3–compliant database.


Note –

If the LDAPv3 database you are using does not support Persistent Search, then you can not use the caching feature.


Sun Directory Server With OpenSSO Schema

This data store type resides in a Sun Directory Server instance and holds the OpenSSO Enterprise information tree. It differs from the OpenSSO Enterprise Repository Plug-in, in that more configuration attributes allow you to better customize the data store.

The following procedure documents how to configure a new data store.

ProcedureTo Create a New Data Store

Before You Begin

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

  1. Click the Access Control tab.

  2. Click the name of the realm in which you want to add a new data store.

  3. Click the Data Stores tab.

  4. Click New from the Data Stores list.

  5. Enter a name for the data store.

  6. Select the type of data store you wish to create.

  7. Click Next.

  8. Configure the data store by entering the appropriate attribute values.

    See the Sun OpenSSO Enterprise 8.0 Administration Reference for attribute definitions.

  9. Click Finish.

Delegating Administrator Privileges

OpenSSO Enterprise administrators are delegated responsibilities based on privileges assigned to groups. A privilege is an action that can be performed on a resource; for example, a READ operation on a log. Privileges can be dynamically assigned to users deemed administrators by creating a group, assigning to it the appropriate privilege, and adding the appropriate user as a member of the group.


Note –

For more information on groups, see Chapter 5, Creating Subjects.


Once a group is created, it appears under the realm's Privileges tab. To add privileges, click the group name and assign the appropriate operation. Members belonging to the group would then be able to perform the assigned operation(s). The following privileges can be delegated.


Note –

If you have upgraded Access Manager from version 7.0 to OpenSSO Enterprise, the privilege configuration differs from that of a fresh installation. To assign or modify privileges, click the name of the role or group you wish to edit and select from the following:


Configuring Policy

A policy defines rules that specify who is authorized to access an organization's resources, including applications and services. Policies control this access by defining who can do what to which resource, and when and how it can be done. In OpenSSO Enterprise resources are defined and policies are created at the realm (or sub realm) level. The Policy Service enables the top-level administrator or policy administrator to create, delete, modify and view policies for a specific resource within the realm. For more information on configuring policies, see Chapter 4, Managing Policies.

Defining Subjects

OpenSSO Enterprise offers a basic identity management functionality. Subjects can be defined within a realm: a user represents an individual identity and a group represents a collection of users with a common function, feature or interest. A subject can be used in the definition for a policy. For more information on defining subjects, see Chapter 5, Creating Subjects.


Note –

OpenSSO Enterprise is not a user provisioning product. This basic identity management functionality should only be used for demonstrations and proof of concepts. The user provisioning solution provided by Sun Identity Manager should be used in real deployments. For more information see Sun Identity Manager.


Creating Agent Profiles

Policy agents and web services security agents function based on properties. The configuration of these properties is centralized and managed using the OpenSSO Enterprise console or command line interface; the defined values are stored in the embedded configuration data store. Agent profiles are added to a realm and managed by the realm administrator. For more information on adding agent profiles, see Chapter 6, Storing Policy Agent and Web Services Security Agent Profiles.

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

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.

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

Note –

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

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.


Note –

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.

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.


Note –

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.


Note –

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.


Note –

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:

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.

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

ProcedureTo 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

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

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.

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

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

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

ProcedureTo Set Up Internet Explorer

  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.


Note –

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.


Tip –

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


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

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

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


Note –

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


ProcedureTo 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

Note –

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.

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

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

ProcedureTo 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

Note –

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.


Caution – Caution –

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

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

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

Note –

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

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

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

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


Tip –

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

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

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

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

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

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

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

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.

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

Note –

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.

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


Tip –

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:

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

Note –

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:

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

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.


Note –

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.


Note –

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.


ProcedureTo 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:


Caution – Caution –

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:

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.

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.

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

Chapter 4 Managing Policies

The OpenSSO Enterprise Policy Service enables the top level administrator or top level policy administrator to view, create, delete, modify, and delegate policies to define access to an organization's protected resources. This chapter describes how to configure and manage policies using the OpenSSO Enterprise console. It contains the following sections.

Understanding the Authorization Process

Businesses have applications and services that they need to protect. A policy defines rules that specify who or what can access these protected resources. The rules are, in effect, permissions describing when and how a principal can perform an action on a given protected resource. (A principal can be an individual, a corporation, a role, or a group.) In general, the permissions define what a principal can do to which resource and under what conditions. Towards this end, OpenSSO Enterprise provides the Policy Configuration Service to define global and realm preferences that effect the Policy Service which is used to create and manage the policies. (For more on the Policy Configuration Service, see Policy Configuration in Sun OpenSSO Enterprise 8.0 Administration Reference.)

The Policy Service allows administrators to define, modify, grant, revoke and delete the policies that protect resources within the OpenSSO Enterprise deployment. Typically, a policy service includes a repository to store policies, interfaces that allow for the creation, administration and evaluation of policies, and a policy agent to enforce the policies. By default, OpenSSO Enterprise uses the configuration data store for policy storage, and the OpenSSO Enterprise console for policy management. Policy agents specifically developed for OpenSSO Enterprise act as the policy enforcement point (PEP). (OpenSSO Enterprise also provides Java and C interfaces for policy creation, policy evaluation, policy agent development, and Policy Service customization. See the Sun OpenSSO Enterprise 8.0 Developer’s Guide and the Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers for more information.)

The policy agent is installed remotely from OpenSSO Enterprise and serves as an authorization step (following user authentication) when a user requests access to a protected resource. For example, a Human Resources server that is protected by a remote instance of OpenSSO Enterprise has an agent installed on it to act as a PEP. This agent would prevent personnel without the proper permission from viewing confidential salary information or other sensitive data. (More information on installing and administrating the policy agents can be found in the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents and the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents. Most policy agents can be downloaded from the Sun Microsystems Download Center.)

The authorization process begins when a web browser requests a URL that resides on a server protected by the policy agent. The policy agent installed on the server intercepts the request and checks for an existing OpenSSO Enterprise session token (SSOToken) for authentication credentials. If the session token is valid, the user is allowed or denied access based on the applicable configured policy. If the token is invalid or there is no existing session token, the user is redirected to the Authentication Service and the following occurs.

  1. The policy agent redirects the user to the Authentication Service login page.

  2. The user submits credentials for authentication.

  3. Assuming successful authentication, the agent issues a request to the OpenSSO Enterprise Naming Service.

  4. The Naming Service returns locators for the Policy Service, the Session Service, and the Logging Service.

  5. The policy agent sends a request to the Policy Service for the policy applicable to the requesting user and resource.

  6. Based on the returned policy, a decision is reached and the user is allowed or denied access.

    The policy agent may redirect the request back to the Authentication Service if the policy decision indicates a different authentication level or authentication mechanism is needed.


Note –

In addition, the Resource Comparator attribute in the Policy Configuration Service would also need to be changed from its default configuration to:

serviceType=Name_of_LDAPService |class=com.sun.identity.policy.plugins.SuffixResourceName|wildcard=*

|delimiter=,|caseSensitive=false

Alternately, providing an implementation such as LDAPResourceName to implement com.sun.identity.policy.interfaces.ResourceName and configuring the Resource Comparator appropriately would also work.


Defining a Policy and a Referral

There are two configurations that can be created using the OpenSSO Enterprise Policy Service: a policy controls access to a protected resource and consists of rules, subjects, conditions, and response providers values, and a referral that delegates policy creation and evaluation to a particular entity and consists of one or more rules and one or more referrals. The following sections have more information.

Policy

In OpenSSO Enterprise, a policy (referred to as a normal policy in previous releases) consists of rules, subjects, conditions, and response providers. A policy can be defined with either binary or non-binary decisions. A binary decision is yes/no, true/false or allow/deny. A non-binary decision represents the value of an attribute. For example, a mail service might include a mailboxQuota attribute with a maximum storage value set for each user. The following sections have more information on the components of a policy.

Rules

A rule contains a service type and one or more actions with an appropriate value that, in effect, defines the intent of the policy. The service type defines the policy-enabled resource that is being protected. An action is the operation that can be performed on the resource; examples of web server actions are POST or GET. A value defines the permission for the action, for example, Allow or Deny. An example of an allowable action for a human resources service might be to change a home telephone number.


Note –

For some services, it is acceptable to define an action without resources.


By default, there are three OpenSSO Enterprise services enabled for policy protection. The following sections explain these policy-enabled service types and the actions that can be applied to each.


Tip –

When assessing policy, deny rules always take precedence over allow rules. For example, if you have two policies for a given resource, one with a rule denying access and the other with a rule allowing access the result, provided that the conditions for both policies are met, is deny. Thus, it is recommended that deny policies be used with extreme caution as they may potentially lead to conflicts. For example, if explicit deny rules are used, policies that are assigned to a given user through different subject types (such as a role or group membership) may result in denied access to a resource. This is illustrated if there is a deny policy for a resource applicable to an Employee role and an allow policy for the same resource applicable to Manager role; policy decisions for users assigned both Employee and Manager roles would be denied. Typically, the policy should use allow unless there are no policies to accomplish the deny case.

One way to resolve this issue is to design policies using Condition plug-ins. In the example, a role condition that applies the deny policy to users authenticated to the Employee role and applies the allow policy to users authenticated to the Manager role helps to differentiate subjects. Another option is to use the Authentication Level condition stipulating that subjects with the Manager role authenticate at a higher authentication level.


Discovery Service (with resource name)

Discovery Service (with resource name) allows administrators to create and manage policies corresponding to the LOOKUP and UPDATE actions that can be performed on the Discovery Service.

Liberty Personal Profile Service (with resource name)

Liberty Personal Profile Service (with resource name) allows administrators to create and manage policies corresponding to the MODIFY and QUERY actions that can be performed on the Liberty Personal Profile Service.

URL Policy Agent (with resource name)

URL Policy Agent (with resource name) allows administrators to create and manage policies for policy agents that enforce decisions on http/http(s) URLs.

Subjects

A subject defines the user or collection of users (for instance, a group or those who possess a specific role) that the policy affects. The general rule for subjects is that the policy would apply only if the user is a member of at least one subject in the policy. The default subjects are:

Authenticated Users

This subject type implies that any user with a valid SSOToken is a member. Thus, all authenticated users are member of this Subject even if they have authenticated to a realm that is different from the one in which the policy is defined. This is useful if the resource owner would like to offer access to resources managed for users from other organizations. To restrict access to protected resources belonging to a specific organization, use the Organization subject.

OpenSSO Identity Subject

This subject type implies that the identities defined under the Subjects tab of a particular realm can be added as a member.

Web Services Clients

This subject type implies that a web services client (WSC) identified by a valid SSOToken is a member IF the Distinguished Name (DN) of any principal contained in the SSOToken matches any value of this subject. Valid values are the DNs of trusted certificates in a local Java keystore that correspond to the certificates of trusted WSCs. This subject type has dependency on the Liberty Alliance Project Web Services Framework and should be used to authorize WSCs only by service providers that implement it. Also, be sure to create the keystore before you add this Subject to a policy.

The following additional subjects are available by selecting them in the Policy Configuration Service of the realm. If you enable any of them, you should also change the values of the LDAP Bind DN and LDAP Bind Password attributes in the Policy Configuration Service of the realm to reflect valid credentials for the LDAP directory. Please note that cn=amldapuser,ou=DSAME Users and the top level suffix is not created in the default configuration directory.

LDAP Groups

This subject type implies that any member of an LDAP group is member of this subject.

LDAP Roles

This subject type implies that any member of an LDAP role is a member of this subject. An LDAP Role is any role definition that uses the Directory Server role capability. These roles have object classes mandated by Directory Server role definition. The LDAP Role Search filter can be modified in the Policy Configuration Service to narrow the scope and improve performance.


Note –

Nested roles can be evaluated correctly as LDAP Roles in the subject of a policy definition.


LDAP Users

This subject type implies that any LDAP user is a member of this subject.

OpenSSO Roles (Legacy Mode)

This subject type implies that any member of an OpenSSO Enterprise role is a member of this subject. An OpenSSO Enterprise role is created using OpenSSO Enterprise running in legacy mode with the AMSDK datastore and has object classes mandated by OpenSSO Enterprise. OpenSSO Roles can only be accessed through the hosting OpenSSO Enterprise Policy Service.

Organization

This subject type implies that any member of a realm is a member of this subject


Note –

All OpenSSO Roles can be used as Directory Server roles. However, all LDAP roles are not necessarily OpenSSO Enterprise roles. LDAP roles can be leveraged from an existing directory by configuring the Policy Configuration Service. OpenSSO Enterprise roles can only be accessed through the hosting OpenSSO Enterprise Policy Service. The LDAP Role Search filter can be modified in the Policy Configuration Service to narrow the scope and improve performance.


Conditions

A condition allows you to define constraints on the policy. For example, if you want to limit access to a paycheck application, you can define a condition specifying the hours; or, you may wish to define a condition that only grants access if the request originates from a given set of IP addresses or from a company intranet. For example, to configure http://org.example.com/hr/*.jsp so that it can only be accessed by users from org.example.com between 9 a.m. to 5 p.m., use an IP Condition along with a Time Condition. By specifying the rule resource as http://org.example.com/hr/*.jsp, the policy would apply to all the JSPs under http://org.example.com/hr including those in the sub directories. The default conditions are:

Active Session Time

Sets the condition based on user session data.

Max Session Time

Specifies the maximum duration to which the policy is applicable starting from when the session was initiated.

Terminate Session

If selected, the user session will be terminated if the session time exceeds the maximum allowed as defined in the Max Session Time field.

Authentication by Module Chain

The policy applies if the user has successfully authenticated to the authentication chain in the specified realm. If no realm is specified, authentication to any realm at the authentication chain will satisfy the condition.

Authentication by Module Instance

The policy applies if the user has successfully authenticated to the instantiated authentication module in the specified realm. If no realm is specified, authentication to any realm at the authentication module will satisfy the condition.

Authentication Level (greater than or equal to)

The policy applies if the user’s authentication level is greater than or equal to the Authentication Level set in the condition. This attribute indicates the level of trust for authentication within the specified realm.

Authentication Level (less than or equal to)

The policy applies if the user’s authentication level is less than or equal to the Authentication Level set in the condition. This attribute indicates the level of trust for authentication within the specified realm.

Current Session Properties

Decides whether a policy is applicable to the request based on values set in the user's OpenSSO Enterprise session. During policy evaluation, the condition returns true only if the user's session has every property value defined in the condition. For properties defined in the condition with multiple values, it is sufficient if the token has at least one value for the property.


Note –

Session properties set by OpenSSO are prefixed with am.protected to ensure that they cannot be edited by the Client SDK.


Identity Membership

Checks if the invocator uuid specified in the environment is a member of at least one AMIdentity object specified in the Condition. The uuid invocator is specified as the key value of Condition. INVOCATOR_PRINCIPAL_UUID in the environment parameter of the evaluation request. This is primarily used to apply authorization rules for WSC (Web Service Client). The identity of the WSC is passed as the value of uuid invocator.

IP Address/DNS Name

Sets the condition based on a range of IP Addresses. The fields you can define are:

IP Address From/To

Specifies the range of the IP address.

DNS Name

Specifies the DNS name. This field can be a fully qualified hostname or a string in one of the following formats:

domainname

*.domainname

LDAP Filter Condition

The policy is applicable when the defined LDAP filter locates the user entry in the LDAP directory that was specified in the Policy Configuration service. This is only applicable within the realm that the policy is defined.

Time (day, date, time, and timezone)

Sets the condition based on time constraints. The fields are:

Date From/To

Specifies the range of the date.

Time

Specifies the range of time within a day.

Day

Specifies a range of days.

Timezone

Specifies a timezone, either standard or custom. Custom timezones can only be a timezone ID recognized by Java (for example, PST). If no value is specified, the default value is the Timezone set in the OpenSSO Enterprise JVM.

If a request for access is negated as determined by the condition, an advice message can be produced to indicate why. Advice messages are propagated in the policy decision and sent to the policy agent which retrieves the advice and takes appropriate action — for example, redirecting the user to the Authentication Service to authenticate to a higher level. If, in this example, the user successfully authenticates to a higher level the policy might then become applicable. See com.sun.identity.policy in the Sun OpenSSO Enterprise 8.0 Java API Reference for more information.


Tip –

Custom conditions can also produce advices. However, the policy agents respond only for Auth Level Advice and Auth Scheme Advice. Custom agents can be written to respond to more advices and existing OpenSSO Enterprise policy agents can be extended to do the same. See the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents for more information.


Response Providers

Response providers are plug-ins that provide values, in the final policy decision, for particular attributes in the authorized user's profile. The attributes are sent with the policy decision to the policy agent which, in turn, passes them in headers to an application. The application typically uses these attributes for customizing pages such as a portal page. OpenSSO Enterprise includes one implementation of the com.sun.identity.policy.interfaces.ResponseProvider interface, the IDResponseProvider. Custom response providers can be implemented.

Referral

A referral (referred to as a referral policy in previous releases) controls the delegation of both policy creation and evaluation. It consists of one or more rules and one or more referrals. Using a referral policy allows an administrator to delegate the administration of a realm's policy definitions and decisions to a sub or peer realm. Alternatively, policy decisions for a resource can be delegated to other policy products.


Note –

The Policy Configuration service contains a global attribute called Realm Alias Referrals. This attribute allows you to create policies in sub-realms without having to create referral policies from the top-level or parent realm. You can only create policies to protect HTTP or HTTPS resources whose fully qualified hostname matches the realm/DNS Alias of the realm. By default, this attribute is defined as No.


The following sections have more information on the components of a referral.

Rules

A referral rule defines the resource whose policy definition and evaluation is being referred. By default, there are three OpenSSO Enterprise services enabled for policy referral.

Referrals

The referral defines the realm to which policy definition and evaluation is being referred. The referral can delegate to a peer realm (on the same level) or a sub realm (on a subordinate level). The realm to which policy definition or evaluation is referred can define and evaluate access only for those protected resources (or sub-resources) that have been referred to it. (This restriction does not apply to the top-level realm.) For more information, see To Create a Referral Using the OpenSSO Enterprise Console.

Creating Policies and Referrals

Policies are generally configured by creating an XML file and importing the data to OpenSSO Enterprise using the ssoadm command line utility but, they can also be created using the OpenSSO Enterprise console. (You can also create, modify and delete policies using the Policy API. See the Sun OpenSSO Enterprise 8.0 Developer’s Guide for more information.) The following sections contain procedures for creating policies or referrals using the ssoadm command line utility and the OpenSSO Enterprise console. In general, policy is created at the realm (or sub realm) level for use throughout the particular realm’s tree.


Tip –

Wildcards are supported in policy definitions. For information see Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.


ProcedureTo Add Multiple Policies Using the ssoadm Command Line Utility

Before You Begin

Before adding policies to OpenSSO Enterprise using ssoadm ensure that:

  1. Create an XML file with policy definitions.

    To add multiple policies simultaneously, place all policy definitions in one XML file (as opposed to having one policy per XML file). This will help to avoid issues with the policy index. Following is an example of an XML file with policy definitions.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE Policies
    PUBLIC "-//Sun Java System Access Manager 7.1 2006Q3 Admin CLI DTD//EN"
    "jar://com/sun/identity/policy/policyAdmin.dtd">
    
    <Policies>
    <Policy name="bigpolicy" referralPolicy="false" active="true" >
    <Rule name="rule1">
    <ServiceName name="iPlanetAMWebAgentService" />
    <ResourceName name="http://thehost.thedomain.com:80/*.html" />
    <AttributeValuePair>
    <Attribute name="POST" />
    <Value>allow</Value>
    </AttributeValuePair>
    <AttributeValuePair>
    <Attribute name="GET" />
    <Value>allow</Value>
    </AttributeValuePair>
    </Rule>
    <Subjects name="subjects" description="desccription">
    <Subject name="webservicescleint" type="WebServicesClients" includeType="inclusive">
    <AttributeValuePair><Attribute name="Values"/><Value>CN=sun-unix, 
    OU=SUN  OpenSSO Enterprise, O=Sun, C=US</Value>
    </AttributeValuePair>
    </Subject>
    <Subject name="au" type="AuthenticatedUsers" includeType="inclusive">
    </Subject>
    <Subject name="ldaporganization" type="Organization" includeType="inclusive">
    <AttributeValuePair><Attribute name="Values"/>
    <Value>dc=red,dc=iplanet,dc=com</Value>
    </AttributeValuePair>
    </Subject>
    <Subject name="ldapuser" type="LDAPUsers" includeType="inclusive">
    <AttributeValuePair><Attribute name="Values"/>
    <Value>uid=amAdmin,ou=People,dc=red,dc=iplanet,dc=com</Value>
    </AttributeValuePair>
    </Subject>
    <Subject name="ldaprole" type="LDAPRoles" includeType="inclusive">
    <AttributeValuePair><Attribute name="Values"/>
    <Value>cn=Organization Admin Role,o=realm1,dc=red,dc=iplanet,dc=com</Value>
    </AttributeValuePair>
    </Subject>
    <Subject name="ldapgroup" type="LDAPGroups" includeType="inclusive">
    <AttributeValuePair><Attribute name="Values"/>
    <Value>cn=g1,ou=Groups,dc=red,dc=iplanet,dc=com</Value>
    </AttributeValuePair>
    </Subject>
    <Subject name="amidentitysubject" type="AMIdentitySubject" includeType="inclusive">
    <AttributeValuePair><Attribute name="Values"/>
    <Value>id=amAdmin,ou=user,dc=red,dc=iplanet,dc=com</Value>
    </AttributeValuePair>
    </Subject>
    </Subjects>
    <Conditions name="conditions" description="description">
    <Condition name="ldapfilter" type="LDAPFilterCondition">
    <AttributeValuePair><Attribute name="ldapFilter"/>
    <Value>dept=finance</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="authlevelge-nonrealmqualified" type="AuthLevelCondition">
    <AttributeValuePair><Attribute name="AuthLevel"/>
    <Value>1</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="authlevelle-realmqaulfied" type="LEAuthLevelCondition">
    <AttributeValuePair><Attribute name="AuthLevel"/>
    <Value>/:2</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="sessionproperties" type="SessionPropertyCondition">
    <AttributeValuePair><Attribute name="valueCaseInsensitive"/>
    <Value>true</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="a"/><Value>10</Value>
    <Value>20</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="b"/><Value>15</Value>
    <Value>25</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="activesessiontime" type="SessionCondition">
    <AttributeValuePair><Attribute name="TerminateSession"/>
    <Value>session_condition_false_value</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="MaxSessionTime"/>
    <Value>30</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="authelevelle-nonrealmqualfied" 
               type="LEAuthLevelCondition">
    <AttributeValuePair><Attribute name="AuthLevel"/>
    <Value>2</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="ipcondition" type="IPCondition">
    <AttributeValuePair><Attribute name="DnsName"/>
    <Value>*.iplanet.com</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="EndIp"/>
    <Value>145.15.15.15</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="StartIp"/>
    <Value>120.10.10.10</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="authchain-realmqualfied"
              type="AuthenticateToServiceCondition">
    <AttributeValuePair><Attribute name="AuthenticateToService"/>
    <Value>/:ldapService</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="auth to realm" 
          type="AuthenticateToRealmCondition">
    <AttributeValuePair><Attribute name="AuthenticateToRealm"/>
    <Value>/</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="authlevelge-realmqualified"
          type="AuthLevelCondition">
    <AttributeValuePair><Attribute name="AuthLevel"/>
    <Value>/:2</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="authchain-nonrealmqualfied" 
         type="AuthenticateToServiceCondition">
    <AttributeValuePair><Attribute name="AuthenticateToService"/>
    <Value>ldapService</Value>
    </AttributeValuePair>
    </Condition>
    <Condition name="timecondition" type="SimpleTimeCondition">
    <AttributeValuePair><Attribute name="EndTime"/>
    <Value>17:00</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="StartTime"/>
    <Value>08:00</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="EndDate"/>
    <Value>2006:07:28</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="EnforcementTimeZone"/>
    <Value>America/Los_Angeles</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="StartDay"/>
    <Value>mon</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="StartDate"/>
    <Value>2006:01:02</Value>
    </AttributeValuePair>
    <AttributeValuePair><Attribute name="EndDay"/>
    <Value>fri</Value>
    </AttributeValuePair>
    </Condition>
    </Conditions>
    <ResponseProviders name="responseproviders"
           description="description">
    <ResponseProvider name="idresponseprovidere" 
         type="IDRepoResponseProvider">
    <AttributeValuePair>
    <Attribute name="DynamicAttribute"/>
    </AttributeValuePair>
    <AttributeValuePair>
    <Attribute name="StaticAttribute"/>
    <Value>m=10</Value>
    <Value>n=30</Value>
    </AttributeValuePair>
    </ResponseProvider>
    </ResponseProviders>
    </Policy>
    </Policies>

    Note –

    The Value element of the following subject attributes takes the full DN:

    • SubrealmReferral

    • PeerRealmReferral

    • Realm

    • IdentityServerRoles

    • LDAPGroups

    • LDAPRoles

    • LDAPUsers


  2. Add the defined policies to OpenSSO Enterprise using ssoadm with the XML file as input.


    ssoadm create-policies --realm realm-name --xmlfile 
    policy-xml-filename --adminid administrator-id 
    --password-file password-filename
    

    For more information, see Chapter 1, ssoadm Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference.

ProcedureTo Create a Policy Using the OpenSSO Enterprise Console

Before You Begin

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

  1. Under the Access Control tab, click the name of the realm for which you are creating policy.

  2. Click the Policies tab.

  3. Click New Policy.

  4. Enter a name for the policy.

  5. (Optional) Enter a description of the policy.

  6. (Optional) Select Yes to activate the policy.

    It is not necessary to define all of the policy's fields at this time. You may choose to add Rules, Subjects, Conditions, and Response Providers later. See Modifying Policies and Referrals for information on these component's attributes.

  7. Click OK.

ProcedureTo Create a Referral Using the OpenSSO Enterprise Console

In order to create policies for peer realms or sub realms, you must first create a referral in the parent (or peer) realm pointing to the appropriate peer or sub realm. The Rule definition in the referral must contain the location of the resource(s) that will be managed. Once the referral is created, policies can be created for the appropriate peer or sub realm.

Before You Begin

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

  1. Under the Access Control tab, click the name of the realm in which you are creating the referral.

    This might be the / Top Level Realm or a sub realm.

  2. Click the Policies tab.

  3. Click New Referral.

  4. Enter a name for the referral.

  5. (Optional) Enter a description of the referral.

  6. (Optional) Select Yes to activate the referral.

  7. Click New under Rules.

  8. Select the appropriate Service Type and click Next.

    This value can not be changed once the Rule has been created. The options are:

    • Discovery Service (with resource name) defines the authorization actions for Discovery Service query and modify protocol invocations by web services clients.

    • Liberty Personal Profile Service (with resource name) defines the authorization actions for Liberty Personal Profile Service query and modify protocol invocations by web services clients.

    • URL Policy Agent (with resource name) defines authorization actions for the URL Policy Agent service. This is used to define policies that protect HTTP and HTTPS URLs. This is the most common use case.

    You may see a larger list if more services are enabled for the policy. (See Enabling Policy in a Service.) For more information, see Rules.

  9. Add a Name for the Rule.

  10. Add a URL as the value for Resource Name and click Finish.

    In this procedure, o=example.com is the sub realm that manages access to http://www.example.com and its sub-resources.

  11. Click New under Referral.

  12. (Optional) Select the Referral Type and click Next.

    The choices are Peer Realm or Sub Realm. This page is displayed only when the realm in which you are creating the referral has both peer and sub realms. It will not be displayed, for example, when creating a referral in the / Top Level Realm because all realms are sub to the / Top Level Realm.

  13. Enter a name for the referral.

  14. Select the realm to which you are referring policy management from the drop down list and click Finish.

  15. Click Save to update.

  16. Navigate to the sub realm to create policy.

    Now that policy management for the resource is referred to the peer or sub realm, policies can be created to control access for http://www.example.com or any resource starting with http://www.example.com. See To Add Multiple Policies Using the ssoadm Command Line Utility or To Create a Policy Using the OpenSSO Enterprise Console.

Modifying Policies and Referrals

Once a policy or referral is created, you can modify its components using the OpenSSO Enterprise console. Policies cannot be modified directly with ssoadm; you must first delete the policy before adding a modified version of it back. The following sections contain procedures on how to modify policies or referrals.

Modifying Policies

You can modify a policy that has already been created. To Modify a Policy describes the procedure to change or delete a policy.

ProcedureTo Modify a Policy

Before You Begin

This procedure assumes:

  1. Under the Access Control tab, click the name of the realm in which the policy you are modifying was created.

  2. Click the Policies tab.

  3. Click the name of the policy you are modifying.

    The policy's component page is displayed.

  4. Under the Rules menu, click New.

    You can click the name of a Rule that has already been defined. The Rules attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Rule and delete it.

  5. Select a Service Type for the rule.

    This value can not be changed once the Rule has been created. The options are:

    • Discovery Service (with resource name) defines the authorization actions for Discovery Service query and modify protocol invocations by web services clients.

    • Liberty Personal Profile Service (with resource name) defines the authorization actions for Liberty Personal Profile Service query and modify protocol invocations by web services clients.

    • URL Policy Agent (with resource name) defines authorization actions for the URL Policy Agent service. This is used to define policies that protect HTTP and HTTPS URLs. This is the most common use case of OpenSSO Enterprise policies.

    You may see a larger list if more services are enabled for the policy. (See Enabling Policy in a Service.) For more information, see Rules.

  6. Click Next to display the New Rule page and modify the following components.

    1. Enter a Name for the Rule.

    2. Enter a Resource Name for the rule.

      Currently, policy agents only support http:// and https:// resources thus the value should be a URL. IP addresses are not supported. Wildcards are supported for protocol, host, port and resource name. For example:


      http*://*:*/*.html

      For the URL Policy Agent service type, the default port number is 80 for http:// and 443 for https:// if no port number is defined.

    3. Select the appropriate value for each Action.

      Actions displayed are dependent on the chosen Service Type. See Rules for an explanation of each Action.

    4. Click Finish to return to the policy's components page.

  7. Under the Subjects menu, click New.

    You can also click the name of a Subject that has already been defined. The Subject attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Subject and delete it.

  8. Select a Subject Type and click Next.

    This value can not be changed once Subjects has been created. The options are:

    • Authenticated Users implies that any user with a valid SSOToken is a member.

    • OpenSSO Identity Subject implies that the identities defined under the Subjects tab of a particular realm can be added as a member.

    • Web Services Clients implies that a WSC identified by a valid SSOToken is a member IF the Distinguished Name (DN) of any principal contained in the SSOToken matches any value of this subject.

    For more information, see Subjects.

  9. Enter a Name for the Subject.

  10. Select whether the Subject is Exclusive.

    If this field is not selected (default), the policy applies to the identity that is a member of the subject. If the field is selected, the policy applies to the identity that is not a member of the subject. If multiple subjects exist in the policy, the policy applies to the identity when at least one of the subjects implies that the policy applies to the identity.

  11. If applicable to the selected Subject Type, choose entries to add for the subject.

    1. Perform a search to display qualified entries.

      The default (*) search pattern will display all qualified entries. Select the individual identities you wish to add for the subject, or click Add All to add all of the identities at once. Click Add to move the identities to the Selected list.

    2. Select an individual entry and click Add to move it to the Selected list.

      Alternately, click Add All to add all of the entries at once.

  12. Click Finish to return to the policy's components page.

  13. Under the Conditions menu, click New.

    You can also click the name of a Condition that has already been defined. The Conditions attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Condition and delete it.

  14. Select a Condition Type and click Next.

  15. Enter values for the Condition Type's listed attributes.

    For more information, see Conditions.

  16. Click Finish to return to the policy's components page.

  17. Under the Response Provider menu, click New.

    You can also click the name of a Response Provider that has already been defined. The Response Provider attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Response Provider and delete it.

  18. Enter a Name for the Response Provider.

  19. Define the following values:

    Static Attribute

    These are static attributes defined in an instance of IDResponseProvider stored in the policy. The value takes the format attribute=value.

    Dynamic Attribute

    The response attributes chosen here need to first be defined in the Selected Dynamic Response Attributes field of the Policy Configuration Service for the corresponding realm. The attribute names defined should be a subset of those existing in the identity repository. To select specific or multiple attributes, hold the Control key and click the left mouse button. For details, see Policy Configuration in Sun OpenSSO Enterprise 8.0 Administration Reference.

  20. Click Finish.

  21. Click Save to update the policy.

Modifying Referrals

You can modify the components of a referral that has already been created. To Modify a Referral describes the procedure to change or delete a referral.

ProcedureTo Modify a Referral

Before You Begin

This procedure assumes:

  1. Under the Access Control tab, click the name of the realm in which the policy you are modifying was created.

  2. Click the Policies tab.

  3. Click the name of the referral you are modifying.

    The referral's component page is displayed.

  4. Under the Rules menu, click New to display the New Rule page and modify as follows.

    You can click the name of a Rule that has already been defined. The Rules attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Rule and delete it.

    1. Select the appropriate Service Type and click Next.

      This value can not be changed once the Rule has been created. The options are:

      • Discovery Service (with resource name) defines the authorization actions for Discovery Service query and modify protocol invocations by web services clients.

      • Liberty Personal Profile Service (with resource name) defines the authorization actions for Liberty Personal Profile Service query and modify protocol invocations by web services clients.

      • URL Policy Agent (with resource name) defines authorization actions for the URL Policy Agent service. This is used to define policies that protect HTTP and HTTPS URLs. This is the most common use case.

      You may see a larger list if more services are enabled for policy. (See Enabling Policy in a Service.) For more information, see Rules.

    2. Add a Name for the Rule.

    3. Add a URL as the value for Resource Name and click Finish to return to the referral's components page.

      Currently, policy agents only support http:// and https:// resources thus the value should be a URL. IP addresses are not supported. Wildcards are supported for protocol, host, port and resource name. For example:


      http*://*:*/*.html

      For the URL Policy Agent service type, the default port number is 80 for http:// and 443 for https:// if no port number is defined. In this example, o=example.com is the sub realm that manages access to http://www.example.com and its sub-resources.

  5. Under the Referrals menu, click New.

    You can click the name of a Referral that has already been defined. The Referrals attributes are the same whether you are defining them now or modifying definitions made in Creating Policies and Referrals. You can also select a defined Referral and delete it.

  6. Enter a Name for the Referral.

  7. Specify a filter and click Search.

    This action defines the realm names that will be displayed in the Value field. By default, it will display all realm names.

  8. Select the realm to which you are referring policy administration from the drop down list.

  9. Click Finish to return to the referral's components page.

  10. Click Save to update the referral.

Using Wild Cards in Policies

The Policy Service supports policy definitions using an asterisk (*) as the wild card. Only * is supported as a wild card and it can not be escaped as in \*. A * must:

The following wild card matching rules assume the wildcard character is * and the delimiter character is /.

Applying Policy Logic

All of the following should be satisfied for a policy to be applicable to a request.

Sometimes policies collide. When this happens, the following rules take effect.

Enabling Policy in a Service

You can protect services using the OpenSSO Enterprise Policy Service only if the service schema configures to the sms.dtd and contains values for the <Policy> schema and sub elements. If you want to create a custom policy agent or require more fine-grained enforcement than the OpenSSO Enterprise Policy Service offers, you can add the <Policy> schema to an OpenSSO Enterprise formatted service file, enabling it for interaction with your policy agent and the Policy Service. (For more information, see Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers.) Once enabled, the service will be displayed as a Service Type when creating policies and referrals. (See Rules.)


Tip –

By default, OpenSSO Enterprise policy agents protect only URL resources in tandem with the URL Policy Agent Service (for which a policy evaluator is created and used to get policy decisions). The most common scenario is to use the policy agents developed specifically for OpenSSO Enterprise and the URL Policy Agent Service. For more information, see Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents or Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.


To Add a New Policy Enabled Service contains more information.

ProcedureTo Add a New Policy Enabled Service

  1. Develop the new service in an XML file based on the sms.dtd.

    amWebAgent.xml is the XML service file for the URL Policy Agent service and can be used as a template to create a policy-enabled service file. It is located in the templates directory of the exploded opensso.zip. Here is another sample template.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    
    <!--
    Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved
    Use is subject to license terms.
    -->
    
    
    
    
    <!DOCTYPE ServicesConfiguration
      PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
      "jar://com/sun/identity/sm/sms.dtd">
    
    <ServicesConfiguration>
      <Service name="SampleWebService" version="1.0">
         <Schema 
            i18nFileName="SampleWebService" 
            i18nKey="SampleWebService">
    
      <Policy>
    	<AttributeSchema name="GET"
              type="single"
              syntax="boolean"
              uitype="radio"
              i18nKey="get">
                <IsResourceNameAllowed/>
                   <BooleanValues>
                     <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                     <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
                   </BooleanValues>
    	</AttributeSchema>
    
    	<AttributeSchema name="POST"
    	      type="single"
            syntax="boolean"
            uitype="radio"
    		    i18nKey="post">
    		      <IsResourceNameAllowed/>
                 <BooleanValues>
                    <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                    <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
                 </BooleanValues>
    	</AttributeSchema>
    
    	<AttributeSchema name="PUT"
    		    type="single"
            syntax="boolean"
            uitype="radio"
    		    i18nKey="put">
    		      <IsResourceNameAllowed/>
                 <BooleanValues>
                    <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                    <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
                 </BooleanValues>
    	</AttributeSchema>
    
    	<AttributeSchema name="DELETE"
    		    type="single"
            syntax="boolean"
            uitype="radio"
    		    i18nKey="delete">
    		      <IsResourceNameAllowed/>
                 <BooleanValues>
                    <BooleanTrueValue i18nKey="allow">allow</BooleanTrueValue>
                    <BooleanFalseValue i18nKey="deny">deny</BooleanFalseValue>
                 </BooleanValues>
    	</AttributeSchema>
    
        </Policy>
        </Schema>
      </Service>
    </ServicesConfiguration>
  2. Save the XML file to the /config/xml/ directory of the exploded opensso.zip.

    For example, /config/xml/newServiceWithPolicy.xml

  3. Load /config/xml/newServiceWithPolicy.xml using the ssoadm command line utility.

    See Chapter 1, ssoadm Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference for more information.

  4. Define policy to protect the resource as documented in Creating Policies and Referrals.

Authenticating Based on Resource

In a typical authentication scenario, if a user attempts access to a web resource without authentication credentials, the policy agent redirects the user to the default OpenSSO Enterprise authentication module login page even if the resource is protected by a different authentication module. Thus, the user must authenticate to both modules. The Gateway servlet provides resource authentication which allows the user to bypass the default authentication module and authenticate against the module protecting the resource only.

The Gateway servlet has the following limitations:

To use resource authentication, you must make ensure certain configurations on the web container installed on the resource server machine as well as make configurations to OpenSSO Enterprise and the policy agent.

ProcedureTo Configure Resource Authentication

Once both OpenSSO Enterprise and a policy agent have been installed and profile has been created for the policy agent, resource-based authentication can be configured. To do this, it is necessary to point OpenSSO Enterprise to the Gateway servlet.

Before You Begin

Ensure the following configurations on the web container installed on the resource's server machine. Check your container's documentation for more information.

  1. Log in to the OpenSSO Enterprise console as administrator; by default, amadmin.

  2. Under the Configuration tab, click Authentication.

  3. Click the Certificate Service Name.

  4. Enable Match Certificate in LDAP by checking the box.

  5. Select Subject UID as the value for Certificate Field Used to Access User Profile.

  6. Enter 54430 as a value for SSL Port Number.

    This port number must match the port number used for the web container's SSL client authentication listener port.

  7. Type 2 as the value for the Authentication Level attribute.

    The value used must be greater that the level defined for LDAP authentication.

  8. Click Save.

  9. Click Back to Service Configuration.

  10. Under the Access Control tab, click the name of the realm to which the policy agent belongs.

  11. Click the Policies tab and add policies as follows.

    • Policy 1 has a condition of LDAP authentication only for http://agent-machine.domain/banner.html.

    • Policy 2 has a condition of Certificate authentication only for http://agent-machine.domain/banner2.html

    • Policy 3 has a condition of LDAP authentication and a level of Certificate authentication for http://agent-machine.domain/banner3.html.

  12. Click the Agents tab.

  13. Click on the Web or J2EE tab depending on the agent being used.

  14. Click on the Agent Profile name of the policy agent.

  15. Under OpenSSO Services, enter the following URL as the value of the OpenSSO Login URL attribute:

    http://OpenSSO Enterprise_host.domain:port/opensso/gateway

  16. Add the following line to the file:

    com.sun.am.policy.am.loginURL = http://OpenSSO Enterprise_host.domain:port/opensso/gateway


    Note –

    The gateway servlet is developed using the Policy Evaluation APIs and can be used to write a custom mechanism to accomplish resource-based authentication. See the Sun OpenSSO Enterprise 8.0 Developer’s Guide.


Chapter 5 Creating Subjects

The Subjects interface enables basic identity management within a realm. Any identity created using this OpenSSO Enterprise console interface is created in the identity repository that was defined during the installation process. (If no external user data store is defined during installation, the user data store is the OpenSSO Enterprise embedded configuration data store; this configuration should be used for testing and demonstration purposes only.) The following sections contain more information on the entities you can create and modify:

Storing Subjects

Any subject created using the OpenSSO Enterprise console is stored in the identity repository that was defined during the installation process. If no external user data store is defined, the user data store is, in effect, the OpenSSO Enterprise embedded configuration data store, and Subjects will be stored in it. This deployment should be used for testing and demonstration purposes only. Defining an external data store during OpenSSO Enterprise configuration, or pointing a realm to an instance of an identity repository after configuration, allows you to store subjects for real deployments.

Creating Users

A user represents an individual’s identity. Users can be created and deleted, and can be added or removed from roles and/or groups. You can also assign services to the user. The following procedures contain more information.

ProcedureTo Create a User

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator; by default, amadmin.

  1. Under the Access Control tab, click the name of the realm in which you are creating the user.

  2. Click the Subjects tab.

  3. Click New.

  4. Enter data for the following fields:

    ID This field takes the identifier of the user purposes of logging into the OpenSSO Enterprise console. This property does not have to be a DN.

    First Name This field takes the first name of the user.

    Last Name This field takes the last name of the user.

    Full Name This field takes the full name of the user.

    Password. This field takes the password for the user.

    Password (Confirm) Confirm the password.

    User Status This option indicates whether the user is allowed to authenticate through OpenSSO Enterprise.

  5. Click OK.

    You can now modify the user profile by clicking the name of the user. For information on the user attributes, see the User attributes. Other modifications you can perform:

ProcedureTo Modify a User

To add a user to a group or role, assign a service to a user profile or add values to the additional user profile attributes, modify the user profile.

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator; by default, amadmin.

  1. Under the Access Control tab, click the name of the realm in which you are creating the user.

  2. Click the Subjects tab.

  3. Click the name of the user you want to modify.

    The Edit User page is displayed under the General tab.

  4. (Optional) Add values to the following user profile attributes.

    • Password can be used to change the user's defined password.


      Note –

      The top level administrator's username and password is created when you configure OpenSSO Enterprise. This password can be changed at any time through the console, or with the ampassword command line utility. This attribute is used to change the top level administrator password through the console. For more information on ampassword, see Chapter 3, The ampassword Command Line Tool, in Sun OpenSSO Enterprise 8.0 Administration Reference.


    • Email Address

    • Employee Number

    • Telephone Number

    • Home Address

    • Account Expiration Date

    • User Authentication Configuration defines the process to which the user must successfully authenticate.

    • User Alias List defines a list of aliases that may be applied to the user. In order to use any aliases configured in this attribute, the LDAP service has to be modified by adding the iplanet-am-user-alias-list attribute to the User Entry Search Attributes field in the LDAP service.

    • Success URL specifies the URL that the user will be redirected to upon successful authentication.

    • Failure URL specifies the URL that the user will be redirected to upon failed authentication.

    • Password Reset Options forces the user to change a defined password at the next login.

    • MSISDN Number defines the user's Mobile Station International Subscriber Directory Number if using MSISDN authentication.

  5. Click Save to save the values.

  6. Click the Services tab.

  7. Click Add.

  8. Select from the displayed services and click Next.

  9. Modify the service's attributes and click Finish.

  10. Click Finish.

  11. Click the Groups tab to add the user to a specific group.

  12. Add a group displayed in the Available list to the Selected list and click Save.

  13. Click Back to Subjects.

Creating Groups

A group represents a collection of users with a common function, feature or interest. Typically, a group has no privileges associated with it. Groups can exist at two levels; within a realm and within other managed groups. The following procedures have more information.

ProcedureTo Create a Group

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator; by default, amadmin.

  1. Under the Access Control tab, click the name of the realm in which you are creating the user.

  2. Click the Subjects tab.

  3. Click the Group tab.

  4. Click New under the Group list.

  5. Enter a name for the group in the ID field.

  6. Click OK.

    Once you have created the group, you can add users to it. See To Add Users to a Group.

ProcedureTo Add Users to a Group

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator; by default, amadmin.

  1. Under the Access Control tab, click the name of the realm in which you are creating the user.

  2. Click the Subjects tab.

  3. Click the Group tab.

  4. Click the name of the group in the Group list to which you want to add users.

  5. Click the User tab.

  6. Add any Available users to the Selected list.

  7. Click Save.

    Users can also be added to Groups by modifying the User profile. See To Modify a User.

Administrative Users and Default Subjects

A number of administrative (and other) users are created as subjects during installation of OpenSSO Enterprise. The following sections contain information about each.

amadmin

The OpenSSO administrative user is amadmin (uid=amAdmin,ou=People,dc=opensso,dc=java,dc=net in the embedded configuration data store). This top-level administrator has unlimited access to all entries managed by OpenSSO. During installation, you must provide a password for amadmin. The amadmin profile is a Subject under the top-level realm. You cannot change the default amadmin identifier.

ProcedureTo Change the amadmin Password

  1. Under the Access Control tab, click / (Top Level Realm).

  2. Click the Subjects tab.

  3. Click amadmin in the Users table.

  4. Under the General tab, click the Password attribute's Edit link.

  5. Type the old and new passwords as directed and click OK.

  6. Click Save on the Edit User page.

amldapuser

amldapuser (cn=amldapuser,ou=DSAME Users,dc=opensso,dc=java,dc=net in the embedded configuration data store) has read and search access to all embedded data store entries; it is used when the OpenSSO schema extends the embedded data store schema. amldapuser binds to the directory to retrieve data for the LDAP and Membership authentication modules and the Policy Configuration Service. The default password for amldapuser is changeit. You can change the password by modifying the value of the AMLDAPUSERPASSWD property in the OpenSSO-Deploy-base/opensso/WEB-INF/classes/serviceDefaultValues.properties file BEFORE running the OpenSSO configurator. Changing the amldapuser password after configuration is not supported.

UrlAccessAgent

UrlAccessAgent is the user that a web agent uses to login to OpenSSO. The password for UrlAccessAgent is defined during OpenSSO configuration.


Note –

amService-UrlAccessAgent (cn=amService-UrlAccessAgent,ou=DSAME Users,dc=opensso,dc=java,dc=net in the embedded configuration data store) is the same user as UrlAccessAgent. When entered as UrlAccessAgent on the server side, the Authentication Service prepends to it the string amService-. The Authentication Service then authenticates it is a special user with an entry in the data store.


Directory Manager

CN=Directory Manager,CN=Users,dc=opensso,dc=java,dc=net is the default top level administrator for the embedded configuration data store (OpenDS). Directory Manager has read and write access to all entries in the embedded configuration data store and would be used to bind to it if the OpenSSO schema is not installed.

Administrator

CN=Administrator,CN=Users,dc=opensso,dc=java,dc=net is the default top level administrator for Microsoft Active Directory. This is similar to Directory Manager.

demo

demo is the user used to demonstrate the federation-related features of OpenSSO. By default, its password is changeit. This user is displayed as a subject of the top-level realm in the OpenSSO console and its default password can be changed.

test

test user is used to execute some OpenSSO samples. These samples would create the test user and test will be displayed as a subject of the top-level realm in the OpenSSO console after executing them. The default password is test.

dsameuser

dsameuser (cn=dsameuser,ou=DSAME Users,dc=opensso,dc-java,dc=net) binds to the embedded configuration data store when the OpenSSO SDK performs operations on it that are not linked to a particular user (for example, retrieving service configuration information).

After installation, it is recommended that you change the password for dsameuser. Do not use the same password that was set for amadmin or amldapuser. To change the password, use the ampassword utility with the --admin (or -a) option. (This option does not change the amadmin password.) If OpenSSO is deployed on multiple host servers, change the password in the embedded configuration data store and the local serverconfig.xml file on the first server as documented using ampassword. For each additional server, encrypt the new password using ampassword with the --encrypt (or -e) option and swap the new encrypted password with the old in the serverconfig.xml file manually. Restart each OpenSSO web container after the modification.

puser

Proxy user (cn=puser,ou=DSAME Users,dc=opensso,dc=java,dc=net) is a proxy user that works behind the scenes for the legacy AMSDK. This user is created during installation and cannot be modified or found in the OpenSSO console.

anonymous

anonymous is the default anonymous user. If the Anonymous authentication module is enabled, an anonymous user can log into OpenSSO without providing a password. You can define a list of anonymous users by adding user identifiers to the anonymous profile using the OpenSSO console.

Chapter 6 Storing Policy Agent and Web Services Security Agent Profiles

OpenSSO Enterprise offers a centralized configuration interface for remote policy agent profiles and web services security related information. The profiles are stored in the embedded configuration data store and managed by an administrator using the OpenSSO Enterprise console. This chapter contains the following sections:

Centralizing Agent Profiles

OpenSSO Enterprise leverages its embedded configuration data store for centralizing the storage of remote policy agent profiles and web services security related information. By moving this configuration data to OpenSSO Enterprise, an administrator can use the console or the command line interface tools to manage the properties and values. Any configuration changes to the hot-swappable properties are conveyed immediately. The following sections have more infomration on the agent profiles that can be configured.

Attribute descriptions for the agent profiles are in Chapter 5, Centralized Agent Configuration Attributes, in Sun OpenSSO Enterprise 8.0 Administration Reference.

Web Policy Agent Profile

Values for the configuration properties of a web policy agent can be defined using OpenSSO Enterprise if, during the web policy agent profile creation, centralized configuration was chosen. If local configuration was selected, the properties related to this policy agent profile must be modified directly in the OpenSSOAgentConfiguration.properties file in the agent installation directory on the agent's host machine. For detailed information on web policy agents, see the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents

J2EE Policy Agent Profile

Values for the configuration properties of a J2EE policy agent can be defined using OpenSSO Enterprise if, during the J2EE policy agent profile creation, centralized configuration was chosen. If local configuration was selected, the properties related to this agent must be modified directly in the OpenSSOAgentConfiguration.properites file in the agent installation directory on the agent's host machine. For detailed information on J2EE policy agents, see the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

Web Service Provider Security Agent Profile

The Web Service Provider (WSP) security agent profile stores the configuration data related to validating a request from a web service client and securing the response returned by the WSP. The data includes the WSP's supported security mechanisms, keystore locations, SAML configurations and endpoints. The WSP agent profile also has a mechanism to authenticate against OpenSSO Enterprise to generate a session for the WSP. For more information, see Part IV, The Web Services Stack, Identity Services, and Web Services Security, in Sun OpenSSO Enterprise 8.0 Technical Overview.

Out of the box, wsp is the default WSP security agent profile. Additional profiles can be defined with the profile name dependant on the endpoint of the service defined in the web service provider's WSDL file. (The security agent searches based on the endpoint.) This allows multiple web service providers to use the same configuration data store. The name of the web service provider must be unique across all agents.


Caution – Caution –

The Group functionality is not supported with the Web Service Provider Security Agent Profile.


Web Service Client Security Agent Profile

The Web Service Client (WSC) security agent profile stores the configuration data related to securing a request from a WSC and validating the request when received by the WSP. The data includes the WSP's supported security mechanisms, keystore locations, SAML configurations, signing and encryption instructions, and endpoints. It also defines whether an end user token should be generated. For more information, see Part IV, The Web Services Stack, Identity Services, and Web Services Security, in Sun OpenSSO Enterprise 8.0 Technical Overview.

Out of the box, wsc is the default WSC security agent profile. Additional profiles can be defined with the profile name dependant on the service name defined in the web service client's WSDL file. (The security agent searches based on the service name.) This allows multiple web service clients to use the same configuration data store. The name of the web service client must be unique across all agents.


Caution – Caution –

The Group functionality is not supported with the Web Service Client Security Agent Profile.


STS Client Agent Profile

The Security Token Service (STS) Client agent profile stores the configuration data related to securing an outbound request to the OpenSSO Enterprise Security Token Service or Discovery Service to obtain a security token. The data includes the supported security mechanisms, keystore locations, signing and encryption instructions, and endpoints.

For more information, see Part IV, The Web Services Stack, Identity Services, and Web Services Security, in Sun OpenSSO Enterprise 8.0 Technical Overview.


Caution – Caution –

The Group functionality is not supported with the STS Client Agent Profile.


2.2 Agents

OpenSSO Enterprise is backward compatible with OpenSSO Enterprise web and J2EE Policy Agents 2.2. Policy Agents 2.2 must be configured local to the deployment container on which it is installed thus, from the OpenSSO Enterprise console, there are a limited number of options that can be configured. For more information, see Sun Java System Access Manager Policy Agent 2.2 User’s Guide.

Agent Authenticator

An agent authenticator is a type of agent that, once it is authenticated, can obtain the read-only data of agent profiles of any type (policy, security or token) for purposes of authenticating the agent. The agent profiles must be defined in the Agent Authenticator profile and exist in the same realm. Users that have the Agent Authenticator's username and password can read agent profile data, but do not have the create, update, or delete permissions of the Agent Administrator.

Creating New Agent Profiles and Groups

This section contains the following procedures.

ProcedureTo Create a New Agent Profile

You can create a new agent profile using the OpenSSO Enterprise console. Some of the individual steps documented do not apply to all agent profile types.

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator; by default, amadmin.

  1. Under the Access Control tab, click the name of the realm in which you are creating the agent profile.

  2. Click the Agents tab.

  3. Select the tab for the appropriate agent type.

    • Web Agents

    • J2EE Agents

    • Web Service Provider Agents

    • Web Service Client Agents

    • STS Client Agent

    • 2.2 Agents

    • Agent Authenticator

  4. In the Agent section, click New.

    The STS Client agent profile displays a pop-up from which you choose the token agent type: Discovery or STS. For more information, see STS Client in Sun OpenSSO Enterprise 8.0 Administration Reference.

  5. In the Name field, enter the name for the new agent profile.

  6. Enter and confirm the Password.


    Caution – Caution –

    For web policy agents only, this password must be the same password that you enter in the agent profile password file that you specify when you run the agentadmin program to install the agent.


    Steps 7–9 Apply to Web and J2EE policy agents only.

  7. For Web and J2EE policy agents only, configure using the following sub procedure.

    For other agent profile types, configure the attributes as documented in Chapter 5, Centralized Agent Configuration Attributes, in Sun OpenSSO Enterprise 8.0 Administration Reference.

    1. Select Local or Centralized configuration.

      When local configuration is selected, the properties related to this agent cannot be edited using the console. In such a scenario, the agent retrieves configuration data from the local (to the installed agent) OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties files in the agent installation directory. Property values for the locally configured agents are modified directly in the OpenSSOAgentConfiguration.properties file.

    2. In the Server URL field, enter the OpenSSO Enterprise server URL.

      For example:

      http://OpenSSO-Host.example.com:8080/OpenSSO
    3. In the Agent URL field, enter the URL for the agent application, agentapp.

      • For a web policy agent: http://Agent-Host.example.com:8090

      • For a J2EE policy agent: http://Agent-Host.example.com:8090/agentapp

  8. Click Create.

    The agent profile is created. To do additional configurations for the agent profile, click the profile name to display the Edit agent page. Agent attribute descriptions are listed and defined in Chapter 5, Centralized Agent Configuration Attributes, in Sun OpenSSO Enterprise 8.0 Administration Reference.

ProcedureTo Create a New Group

Agents can inherit properties from their group. For example, web policy agents can inherit properties from a web policy agent group.


Caution – Caution –

The Group functionality is not supported with the web services and STS Client Agent Profiles.


Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator; by default, amadmin.

  1. Under the Access Control tab, click the name of the realm to which the group will belong.

  2. Click the Agents tab.

  3. Select the tab for the appropriate agent type.

  4. In the Group section, click New.

  5. Enter a name for the new group.

  6. Enter the OpenSSO Enterprise Server URL (for Web and J2EE policy agents only).

    For example, http://OpenSSO-Host.example.com:8080/OpenSSO Enterprise. For other agent profile types, configure the attributes as documented in Chapter 5, Centralized Agent Configuration Attributes, in Sun OpenSSO Enterprise 8.0 Administration Reference.

  7. Click Create.

    The agent group is created. To do additional configurations for the agent group, click the group name to display the Edit Group page. Attribute descriptions are listed and defined in Chapter 5, Centralized Agent Configuration Attributes, in Sun OpenSSO Enterprise 8.0 Administration Reference. (The properties you can set for a group are almost the same as those for an individual agent; the Group, Password, and Password Confirm properties are not available at the group level.)


    Caution – Caution –

    Some group properties have variable values assigned that, in most cases, should not be changed. @AGENT_PROTO@://@AGENT_HOST@:@AGENT_PORT@/amagent is an example of such a value.


ProcedureTo Modify an Agent Profile to Inherit Properties From a Group

The Group functionality is not supported with the web services and STS Client Agent Profiles.

Before You Begin

This procedure assumes you are logged into the OpenSSO Enterprise console as the administrator (by default, amadmin) and the group has been created. See To Create a New Group.

  1. Under the Access Control tab, click the name of the realm to which the agent belongs.

  2. Click the Agents tab.

  3. Select the tab for the appropriate agent type.

  4. Click the name of the agent profile you want to modify.

  5. elect the name of the group from which you want the agent to inherit properties as a value for the Group attribute under the Global tab.

  6. Click Save.

    At the top of the page, the Inheritance Settings button becomes active.

  7. Click Inheritance Settings.

    A list of inheritance settings for the Global tab appears in alphabetical order.

  8. Select the properties that you want the agent to inherit from the group.

    At the top of the page, the Inheritance Settings button becomes active.

  9. Click Save.

Next Steps

This task just describes how to change the inheritance settings for properties listed in the Global tab. For the inheritance settings of properties listed in the other tabs (such as Application and SSO), click the desired tab and edit the inheritance settings in the same manner described in the preceding steps.