2.4 Setting Up Your Environment

After installing SSPR, you must set up and configure the back-end directory for making SSPR functional. SSPR supports the following directories:

This section includes:

2.4.1 Setting Up Directories

This section describes the following:

Setting Up NetIQ eDirectory

The SSPR package includes the edirectory-schema.ldif file and the edirectory-rights.ldif in the supplemental directory. You must modify edirectory-rights.ldif manually to match it with your environment. Use edirectory-schema.ldif to extend the SSPR schema. 

SSPR uses eDirectory attributes to store the following user data:

  • The last time when a user changed the password

  • The last time when SSPR sent an e-mail notification to the user about password expiry

  • Secret questions and answers

This section discusses:

Using edirectory-schema.ldif to Extend the Schema

You can import the edirectory-schema.ldif file through one of the following:

  • iManager

  • ICE command line

  • Standard ldapmodify tool

For example, run the following command in eDirectory through the ldapmodify tool:

ldapmodify -x -h <host ip address> -p 389 -D cn=admin,o=context -wpassword -f edirectory-schema.ldif

Running this command adds the following SSPR attributes to the directory schema:

  • pwmEventLog

  • pwmResponseSet

  • pwmLastPwdUpdate

  • pwmGUID

eDirectory Rights

SSPR requires permission to perform operations in eDirectory and uses the following two different eDirectory rights:

Proxy User Rights

Users with generic proxy user rights perform operations such as pre-authentication. Proxy users need the following rights to user containers:

  • Browse rights to [Entry Rights]

  • Read and Compare rights to the pwmResponseSet and Configured Naming (CN) attribute

  • Read, Compare, and Write rights to objectClass, passwordManagement, pwmEventLog, and pwmLastPwdUpdate

NOTE:Create rights to [Entry Rights] will be needed if the New User Registration module is enabled. This right is not added by edirectory-rights.ldif. Add it manually by using the Modify Trustees task of the Rights role in iManager.

Authenticated User Rights

Users with authenticated user rights perform operations based on the permissions associated with the user’s connection. Authenticated users need the following rights for their own user entry:

  • Browse rights to [Entry Rights]

  • Read, Compare, and Write rights to pwmResponseSet

After setting up eDirectory for SSPR, continue with Section 2.4.2, Configuring Directories.

Granting Rights to the pwmResponseSet Attribute

Users need access to write to the pwmResponseSet attribute. Perform the following steps in iManager:

  1. Enable [this] support in iManager.

    1. Log in to iManager.

    2. Click Configure.

    3. Select iManager > Configure iManager.

    4. Select Misc > Enable [this].

  2. Assign rights to users.

    1. Log in to iManager.

    2. Select View Objects.

    3. Select Browse.

    4. Browse to the top level container of all users in the directory.

    5. Click the container name and select Modify Trustees.

    6. Click Add Trustee.

    7. Select [This] and click OK.

    8. Click Assigned Rights for the [This] trustee.

    9. Click Add Property.

    10. Select Show all properties > pwmResponseSet, and click OK.

    11. Ensure that Write, Compare, Read, and Inherited options areselected.

    12. Click Done > OK.

Other Rights

Depending on the SSPR configuration, users may need other rights assigned as well. In most cases, SSPR interacts with the directory by using the user's LDAP connection. The user must have LDAP rights to execute operations. For example:

  • Update Profile Module: User must have all rights to read attributes that are part of the Update Profile module and write rights to any attributes they require to write to.

  • Helpdesk Module: Users must have read rights to search and display attributes of users whom they administer. Users must also have write rights to any attributes modified by the Helpdesk module through configured actions or password setting and unlocking accounts.

NOTE:For eDirectory 8.8 SP7, apply the latest patch to eDirectory 8.8.7. to avoid any issue in changing passwords. For more information, see TID7010386.

Setting Up Active Directory

You can configure Active Directory in any one of the following modes:

  • Database mode: Challenge-responses are stored in database. You do not need to extend schema if you are using this mode.

  • Schema mode: Challenge-responses are stored in Active Directory. You must extend the schema and assign user rights to store data in Active Directory.

  • RDBMS mode: Challenge-responses are stored in an external RDBMS.

Topics include:

Setting Up Active Directory in the Database Mode

In this mode, Active Directory uses Derby as the default database. You do not need to do any other configuration.

Setting Up Active Directory in the Schema Mode

SSPR leverages the directory to store and manage the SSPR data. To accomplish this, SSPR extends the directory schema to add SSPR schema attributes where the SSPR data is stored.

After you extend the directory schema, you must give permissions to access objects, including the group policy, organizational units, and containers. Assigning user rights includes authorizing read or write rights to SSPR directory schema attributes.

The Active Directory schema extension executable extends the schema on the server and enables you to assign user rights. You must determine containers and organizational units that need SSPR access. You must know their distinguished names (DN) so that you can assign rights to each container and organizational unit separately.

You can also extend the Active Directory schema to the root of the domain and assign rights to each container and organizational unit below the root.

Extending the Active Directory Schema

Log in as the domain administrator and run the schema extension file on an Active Directory domain controller or machine that is connected to the Active Directory domain.

  1. Log in to the server as an administrator.

  2. Click Schema Extension Tools > Active Directory Extension.

    or

    If you are installing from the SSPR installer package, locate the supplemental folder, then double-click ssprADSschema.exe.

  3. Select Extend Active Directory Schema.

  4. Click OK to add the following SSPR attributes are added to the directory schema:

    • pwmEventLog

    • pwmResponseSet

    • pwmLastPwdUpdate

  5. Click OK.

    After extending the directory schema, you must assign access rights to the relevant containers and organizational units. Continue with section Assigning User Rights.

Assigning User Rights

You must assign permission to objects in the directory to store the data against the new SSPR schema attributes. You assign rights to all the objects that access the SSPR data, including the user objects, containers, group policies, and organizational units.

When you assign rights to the containers and organizational units, rights filter all associated user objects. Do not assign rights at the user object level unless it is mandatory.

  1. Run ssprADSschema.exe from supplemental\Schema\AD.

    NOTE:This tool is multi-functional. If you select to extend the schema again, a message listing the existing schema appears. Ignore this message.

  2. Select Assign User Rights, then click OK.

    For example, if you assign rights to the Users container, the User container definition is:

    cn=users,dc=www,dc=training,dc=com

    To assign rights to an organizational unit, such as Marketing, in the www.company.com domain, the definition is:

    ou=marketing,dc=www,dc=company,dc=com

  3. Specify your container or organizational unit definition in Assign rights to this object.

  4. Click OK.

  5. Repeat Step 2 through Step 4 to assign rights to all required user objects, containers, and organizational units.

    If you see an error message indicating Error opening the specified object: - 2147016661, it means that the rights have already been assigned to the object.

    If you see an error message indicating Error opening the specified object: -214716656, it means that you have attempted to assign the rights to an object that does not exist in the directory.

    Check your punctuation, syntax, and spelling, then repeat the procedure.

  6. When all the required rights are successfully assigned, click OK.

  7. Click Cancel.

NOTE:You can extend rights to objects any time after extending the schema. If you add organizational units, you need to rerun the adschema.exe tool and assign rights to the new object to permit the SSPR data to write to the directory.

Refreshing the Directory Schema

  1. Run the Microsoft Management Console (MMC), then display the Active Directory Schema plug-in.

  2. Right-click Active Directory Schema, then select Reload the Schema.

In a multi-server environment, schema updates occur after server replication.

After setting up Active Directory for SSPR, continue with Section 2.4.2, Configuring Directories.

Setting Up Active Directory in the RDBMS Mode

If your back-end information directory is Active Directory, choose Active Directory - Store responses in a database, go to Settings > Database and configure the following:

  • Database Class: Name of the database class. Specify the Java JDBC full driver class name.

    The classpath must include the corresponding JDBC driver JAR or ZIP file, typically, in the WEB-INF/lib directory or the application server's lib directory. For example, in Tomcat, it is <TOMCAT_HOME>/webapps/<SSPR>/WEB-INF/lib or <TOMCAT_HOME>/lib. The default folder name under which the application is deployed is <SSPR>. If you have changed this name, use the appropriate path name accordingly.

  • Database Connection String: Specify the database connection string in the standard JDBC format.

  • Database Username: Specify the name of the user who can connect to the database.

  • Database password: Specify a password for the database user.

Sample Configuration

This example discusses steps for configuring SSPR with MicroSoft SQL Server 2008.

Download the Microsoft SQL Server jdbc driver sqljdbc.jar and add it to the server or application classpath and configure SSPR settings as follows:

Field

Description

Database Class

Specify com.microsoft.sqlserver.jdbc.SQLServerDriver

Database Connection String

The general form of the connection URL is: jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]

jdbc:sqlserver://: (Required) Sub-protocol. It is constant.

serverName: (Optional) Server address. Includes DNS, IP address, localhost, or 127.0.0.1 of the local computer. If not specified in the connection URL, the server name must be specified in the properties collection.

instanceName: (Optional) Instance to connect to serverName. If not specified, a connection to the default instance is made.

portNumber: (Optional) Port to connect to serverName. The default port number is 1433. If you are using the default, you do not require to specify the port in the URL.

The following are few examples of connection string in different scenarios:

In the examples below, Instance - LocalDB, server - DBHOST, port number- 1443

  • Connection string to connect LocalDB on DBHOST at port 1433 is jdbc:sqlserver://DBHOST\LocalDB:1433;

  • Connection string to connect LocalDB on DBHOST at port 1433 by using USER1 and password PWD is jdbc:sqlserver://DBHOST\LocalDB:1433;integratedSecurity=true;username=USER1;password=PWD;

    Set the integratedSecurity property to true to enable the SQL server to use Windows credentials during user authentications. If this setting is set to false, users must provide the username and password.

  • Connection string to connect LocalDB on DBHOST at port 1433 with Windows credentials is jdbc:sqlserver://DBHOST\LocalDB:1433;integratedSecurity=true;

    Copy the sqljdbc_auth.dll file to a directory on the Windows system path where the JDBC driver is installed. The sqljdbc_auth.dll files are installed in this location: <installation directory>\sqljdbc_<version>\<language>\auth\

NOTE:For a 32-bit Java Virtual Machine (JVM), use sqljdbc_auth.dll from the x86 folder, even if the operating system is x64 version. For a 64-bit JVM on a x64 processor, use sqljdbc_auth.dll from x64. For a 64-bit JVM on a IA-64 processor, use sqljdbc_auth.dll from IA64. You can set the java.libary.path system property to specify the directory of sqljdbc_auth.dll. For example, if the JDBC driver is installed in the default directory, you can specify the location of DLL by using this virtual machine argument when the Java application starts: Djava.library.path=C:\Microsoft SQL Server 2008 JDBC Driver\sqljdbc_<version>\enu\auth\x86" (This is environment specific)

Library Path

In Windows, set appropriate values for JAVA_OPTS in catalina.bat under the <tomcat>/bin folder. For more information, see the Tomcat documentation.

Database Username

You can leave this field blank when you mention the username in the connection string.

Database Password

You can leave this field blank if you mention the password in the connection string.

For information about other settings for SQL Server 2008 R2, see Microsoft SQL Server JDBC Driver 3.0.

NOTE:If you want to configure SSPR to connect to any LDAP server other than Active Directory and store the response in an external RDBMS database, navigate to Modules > Forgotten Password in SSPR Configuration Editor and do the following:

  • Set Response Read Location to Database

  • Set Response Write Location to Database

This setting is in addition to the database configuration steps above.

Setting Up Oracle Directory Server

The SSPR package includes the ODS-schema.ldif file in the supplemental directory. Use this file to extend the SSPR schema.

SSPR uses Oracle Directory Server attributes to store the following users’ data:

  • The last time when a user changed the password

  • The last time when SSPR sent an e-mail notification to the user about password expiry

  • Secret questions and answers

Using the ODS-schema.ldif File to Extend the Schema and Assign Rights

Import the ldif file by using the standard LDAP Modify tool.

For example, execute the following command in Oracle Directory Server by using the LDAP Modify tool:

ldapmodify -x -h <host ip address> -p 389 -D cn=admin,o=context -password -f ODS-schema.ldif

Running this command adds the following SSPR attributes to the Directory schema:

  • pwmEventLog

  • pwmResponseSet

  • pwmLastPwdUpdate

  • pwmGUID

Oracle Directory Server Rights

SSPR requires permission to perform operations in Oracle Directory Server and uses the following two rights:

Proxy User Rights

Users with generic proxy user rights perform operations such as pre‐authentication. Proxy users need the following rights to user containers:

  • Browse rights to [Entry Rights]

  • Read and Compare rights to the pwmResponseSet and Configured Naming (CN) attribute

  • Read, Compare, and Write rights to objectClass, passwordManagement, pwmEventLog, and pwmLastPwdUpdate

Authenticated User Rights

Users with authenticated user rights perform operations based on the permissions associated with the user’s connection. Authenticated users need the following rights for their own user entry:

  • Browse rights to [Entry Rights]

  • Read, Compare, and Write rights to pwmResponseSet

After setting up Oracle Directory Server for SSPR, continue with Section 2.4.2, Configuring Directories.

2.4.2 Configuring Directories

You can configure directories either by using the Configuration Guide or manually. This section describes how to configure the directories using the Configuration Guide.

NOTE:To configure directories manually, click Manual Configuration on the Welcome page. For more information about configuration, see Section 3.1, Configuring LDAP Settings.

Before proceeding, ensure that you are using Internet Explorer 10 or later version.

To configure the directories using the configuration Guide, Perform the following:

  1. Navigate to the Welcome page.

  2. Click Start Configuration Guide.

  3. Select a template from the list based on the back-end directory that you want to configure for your SSPR.

  4. Click Next.

  5. Specify the following details:

    Field

    Description

    LDAP Hostname/Server Address

    Specify the address or hostname of the LDAP server

    LDAP Port

    Specify the port number.

    For secure connection (HTTPS), use the ldaps://servername:636 format.

    For plain text servers, use the ldap://serverame:389 format (not recommended).

    Secure (SSL Connection)

    Select this check box to enable secure connection through HTTPS.

    Proxy/Admin LDAP DN

    Configure an LDAP proxy user in the LDAP distinguished name format. For example, cn=admin,o=example or cn=administrator,cn=users,dc=subdomain,dc=domain,dc=net

    Password

    Set a password for the LDAP proxy user.

  6. Click Check Settings > Next.

    If there is any error in the setting, you cannot proceed to the next configuration options. SSPR displays the error details to help you troubleshoot the issue.

  7. Specify the following details:

    Field

    Description

    Certificate(s) are trusted by default keystore

    Select this check box to import and remove certificates manually into the Java keystore.

    Use application configuration to manage certificate(s) and import certificates into configuration

    Select this check box if you do not want to import the LDAP server's SSL certificate into the Java keystore. The system trusts all LDAP SSL certificate without any verification.

    You can verify the LDAP server certificates available on the LDAP host server whether these match with your LDAP server certificates.

  8. Click Next.

  9. Specify the following details:

    Field

    Description

    LDAP Contextless Login Root

    Specify the top level LDAP context for your LDAP directory. This is the top level LDAP container under that your users exist. After completing the configuration, you can add multiple values through Settings > LDAP Directory > LDAP Contextless Login Root.

    LDAP Test User DN

    Specify the LDAP DN of a test user account. You need to create a new test user account with the same privileges and policies as any other users in the system. You can change the password of this account and use it periodically to check health of the LDAP server.

    Using a test user account increases the ability to detect and alert you about any configuration and health issues. You can test the following functionalities through a test user:

    • Authentication

    • Read password policy

    • Set password

    • Set challenge-responses

    • Load challenge-responses

    This is a recommended setting. You can configure an LDAP Test User DN later also.

    Administrator Search Filter

    Specify the LDAP query to check whether a user can get the administrator’s access to this system.

    Any user that authenticates and matches this filter can access the system as an administrator.

  10. Click Check Settings > Next.

    If there is any error in the setting, you cannot proceed to the next configuration options. SSPR displays the error details to help you troubleshoot the issue.

  11. Specify a password to lock the configuration changes you have done.

    To make any change in the existing configuring, you must provide the configured password.

  12. Click Next> Save Configuration.

After setting up your environment, continue with Section 3.0, Configuring Self Service Password Reset.