test

Sun OpenSSO Enterprise 8.0 Integration Guide

Configuring Administrator-Initiated Password Reset

By default, when a user password is close to expiring, Directory Server sends a warning to the user. This warning is sent based on the time configured in the password policy. The next time the user attempts to log in to a protected application, OpenSSO Enterprise redirects the user to Identity Manager where the user can change his password. If the user does not change his password, and lets his password expire, he must contact the HelpDesk administrator and request a password-reset.

When a HelpDesk administrator resets the user's password, a flag is set in the user profile. The HelpDesk administrator gives a temporary password to the user by email or over the phone. When the user logs in using the temporary password, the user is redirected to the Identity Manager user interface to reset the user password. After the user password has been reset, the flag that was set earlier is unset.

To configure OpenSSO Enterprise for administrator-initiated password reset, complete the following steps:

  1. Configure Directory Server.

  2. Configure OpenSSO Enterprise for Administrator-Initiated Password Reset.

  3. Configure the Identity Manager password controls.

  4. Test Administrator-Initiated Password Reset configurations.

The following figure illustrates in detail the process flow for administrator-initiated password reset.

Figure 1–10 Process Flow for Administrator-Initiated Password Reset

Text-based. Needs no further explanation.

Configuring Directory Server

Before you can configure OpenSSO Enterprise for administrator-initiated password reset, you must configure the Directory Server must to meet the following conditions:

See the Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide for detailed instructions on configuring these settings.

Important Information About Using Sun Directory Server 6.3

After you install Sun Directory Server Enterprise Edition 6.3, Directory Server uses Legacy mode for its password policy syntax, which works for both Directory Server 5.x and Directory Server 6.x. However, Directory Server 6.3 maintains two sets of password attributes for both password policies and the user's computed password attributes. This may trigger other potential issues. Unless you are planning to use Directory Server 5.x password policies, a good practice is to migrate a new Directory Server 6.3 instance to the Directory Server 6-Only mode. Doing so removes redundancies and avoids any potential problems.

Here is an example of how you can verify which mode the Directory Server is running in, and how you can enable Directory Server 6–Only mode. 


# DirectoryServer-base/ds6/bin/dsconf get-server-prop -p 1389 -D "cn=directory manager" 
-w mypass -c -e pwd-compat-mode
pwd-compat-mode  :  DS5-compatible-mode

# DirectoryServer-base/ds6/bin>dsconf pwd-compat -p 1389 -D "cn=directory manager" 
-w mypass -c -e to-DS6-migration-mode
## Beginning password policy compatibility changes.
## Password policy compatibility changes finished.

Task completed (slapd exit code: 0).

# DirectoryServer-base/ds6/bin/dsconf pwd-compat -p 1389 -D "cn=directory manager" 
-w mypass -c -e to-DS6-mode
## Beginning password policy compatibility changes.
## Password policy compatibility changes finished.

Task completed (slapd exit code: 0).

# DirectoryServer-base/ds6/bin/dsconf get-server-prop -p 1389 -D "cn=directory manager" 
-w mypass -c -e pwd-compat-mode
pwd-compat-mode  :  DS6-mod

Configuring OpenSSO Enterprise for Administrator-Initiated Password Reset

Only the OpenSSO Enterprise LDAP authentication module supports the password change controls enforced by most directory servers.

To configure OpenSSO Enterprise for administrator-initiated password reset, complete the following steps:

  1. Enable LDAP authentication.

  2. Define Identity Manager URLs as Not Enforced.

  3. Create a Custom ChangePassword.jsp file.

  4. Modify the LDAP authentication module XML service file.

  5. Modify the OpenSSO login page.

ProcedureTo Enable LDAP Authentication

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

  2. Click the Access Control tab.

  3. Navigate to Top Level Realm > Authentication > Authentication Chaining.

  4. In the Authentication Chaining section, click New.

  5. Enter a name for the chain and click OK.

    For this example: idmauth.

  6. On the new chain's Properties page, add the LDAP module as REQUIRED, and click Save.

  7. Click Back to Authentication.

  8. For the Organization Authentication Configuration property value, choose the service you just created.

  9. In the Module Instances section, choose LDAP.

  10. Provide the following information to about the LDAP user data store:

    Primary LDAP Server:

    Use the form server.domain:port

    DN to Start User Search:

    Branch of the LDAP tree from which the user-search begins

    DN for Root User Bind:

    DN to use when binding to the LDAP user data store

    Password for Root User Bind:

    Password for the user binding to the LDAP user data store

    Password for Root User Bind (confirm):

    Type the password again

  11. Save the changes.

  12. Log out of the OpenSSO Enterprise console.

Next Steps

After completing this configuration:

ProcedureTo Define Identity Manager URLs as Not Enforced

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

  2. Click the Access Control tab.

  3. Click the appropriate realm name and navigate to the Policy Agent Profile for the policy agent that protects Identity Manager.

  4. Under the Policy Agent Profile, click the Application tab.

  5. Add the following URIs to the Not Enforced URIs property:

    • /idm/authutil/

    • /idm/authutil/*

    • /idm/authutil/*?*

  6. Click Save.

  7. Log out of OpenSSO Enterprise.

Creating a Custom ChangePassword.jsp File

By default, the user is directed to the OpenSSO Enterprise password change page. Create a custom JSP file, ChangePassword.jsp, that redirects a user to Identity Manager for password change events. The new ChangePassword.jsp forwards the following information to Identity Manager:

This customized ChangePassword.jsp file is referenced in the section Modifying the LDAP Authentication Module XML Service File.

To create a custom ChangePassword.jsp file, choose only one of the following procedures:

ProcedureTo Create a New ChangePassword.jsp File

  1. Create the file config/auth/default/ChangePassword.jsp in the OpenSSO Enterprise web-app directory.


    Example:
    		 

    <html>

<%@page info="Login" language="java"%>
<%@taglib uri="/WEB-INF/jato.tld" prefix="jato"%>
<%@taglib uri="/WEB-INF/auth.tld" prefix="auth"%>
<jato:useViewBean className="com.sun.identity.authentication.UI.LoginViewBean">


<%@ page contentType="text/html" %>

<head>
<title><jato:text name="htmlTitle_Login" /></title>

<%
String ServiceURI = (String) viewBean.getDisplayFieldValue(viewBean.SERVICE_URI);
%>

<link rel="stylesheet" href="<%= ServiceURI %>/css/styles.css" type="text/css" />
<script language="JavaScript" src="<%= ServiceURI %>/js/browserVersion.js"></script>
<script language="JavaScript" src="<%= ServiceURI %>/js/auth.js"></script>
</head>

<%
    System.out.println("AccountId: " + request.getParameter("IDToken1"));
    System.out.println("goto: " + request.getParameter("goto"));
        System.out.println("plaingoto: " + request.getParameter("plaingoto"));

    String accountId = request.getParameter("IDToken1");
    String gotoURL = request.getParameter("plaingoto");

    String redirectURL = 
        "http://HostName.DomainName:6480/idm/authutil/anonResetPassword.jsp";
if(accountId != null){
        redirectURL = redirectURL + "?accountId=" + accountId;
        }        
if(gotoURL != null && !gotoURL.equals("null") && (gotoURL.length() > 0)){
        if(accountId == null){
            redirectURL = redirectURL + "?goto=" + gotoURL;
                }else{
            redirectURL = redirectURL + "&goto=" + gotoURL;
                }
        }
    System.out.println("Redirect URL is:" + redirectURL);
        response.sendRedirect(redirectURL);
%>

</jato:useViewBean>

</html>

  2. Customize the URL to the Identity Manager page that performs the password-reset functions.

    The URL is highlighted in bold above. Determine this URL with help from your Identity Manager administrator, and customize the URL for your deployment.

ProcedureTo Use the Sample Source Code

  1. Copy the sample file opensso/integrations/idm/jsps/ChangePassword.jsp in the opensso.zip distribution to the directory web-container-deploy-base/opensso/config/auth/default.

  2. Customize the URL to the Identity Manager page that performs the password-reset functions.

    Determine this URL with help from your Identity Manager administrator, and customize the URL for your deployment. See step 2 of Creating a Custom ChangePassword.jsp File .

Modifying the LDAP Authentication Module XML Service File

By default, upon receiving a directory-server request for the user to change his password, OpenSSO Enterprise directs the user to its own password-change page. Configure OpenSSO Enterprise to use a custom JSP for password-change events. Modify the LDAP.xmlfile to use ChangePassword.jsp that you created in Creating a Custom ChangePassword.jsp File .

You can manually change the deployed LDAP.xml file, or you can use the sample LDAP.xml included with the opensso.zip download. Choose only one of the following procedures:

ProcedureTo Manually Modify a Deployed LDAP.xml File

  1. Use a text editor to open the /web-container-deploy-base/opensso/config/auth/default/LDAP.xml file, and add the section of code highlighted in bold in the following example:


    PasswordCallback echoPassword="false" >
<Prompt> Password: </Prompt>
</PasswordCallback>

</Callbacks>
<Callbacks length="4" order="2" timeout="120" template="ChangePassword.jsp" 
header="Change Password&lt;BR&gt;&lt;/BR&gt;#REPLACE#&lt;BR&gt;&lt;/BR&gt;" >

<PasswordCallback echoPassword="false" >
<Prompt>Old Password </Prompt>
</PasswordCallback>

  2. Use a text editor to open the /web-container-deploy-base/opensso/config/auth/default_en/LDAP.xml file, and make the same change as in step 1.

ProcedureTo Use the Sample LDAP.xml

  1. Change to the opensso/integrations/idm/xml/ directory in the decompressed opensso.zip to access the sample LDAP.xml.

  2. Replace your deployed /web-container-deploy-base/opensso/config/auth/default/LDAP.xml with the a customLDAP.xml.

    Choose only one of the following options:

    • Replace your existing LDAP.xml file with the sample LDAP.xml file. If you choose this option, you will lose any custom changes you may have made to this file earlier.

    • Run the diff command to compare the files, then manually make the necessary changes.

Modifying the OpenSSO Login Page

Embed code into the OpenSSO Enterprise Login.jsp file that will save the URL in the HTTP request parameter goto. This URL is required by the ChangePassword.jsp that you created in the section To Create a New ChangePassword.jsp File. Once saved, the URL can be passed onto Identity Manager. Identity Manager later redirects the user to that URL.

The URL in the HTTP request parameter goto is the original URL requested by the user, before he was redirected to OpenSSO Enterprise for login.

You can manually change the deployed Login.jsp file, or you can use the sample Login.jsp included with the opensso.zip download. Choose only one of the following procedures:

ProcedureTo Modify a Deployed Login.jsp File

  1. Use a text editor to open the file web-container-deploy-base/opensso/config/auth/default/Login.jsp and add the sections of code displayed in bold the following example:


    ...

<%

String ServiceURI = (String) viewBean.getDisplayFieldValue(viewBean.SERVICE_URI);
String encoded = "false";
String gotoURL = (String) viewBean.getValidatedInputURL(
request.getParameter("goto"), request.getParameter("encoded"), request);
String encodedQueryParams = (String) viewBean.getEncodedQueryParams(request);
if ((gotoURL != null) && (gotoURL.length() != 0)) {
encoded = "true";

}

String replaygotoURL = "";
String goToURL = request.getParameter("goto");
if(gotoURL != null && !gotoURL.equals("null") && (gotoURL.length() > 0)){
replaygotoURL = "&goto=" + goToURL;

}

System.out.println("replaygotoURL: " + replaygotoURL);
%>


<link rel="stylesheet" href="<%= ServiceURI %>/css/styles.css" type="text/css" />
<script language="JavaScript" src="<%= ServiceURI %>/js/browserVersion.js"></script>
<script language="JavaScript" src="<%= ServiceURI %>/js/auth.js"></script>

...


<input type="hidden" name="goto" value="<%= gotoURL %>">
<input type="hidden" name="SunQueryParamsString" value="<%= encodedQueryParams %>">
<input type="hidden" name="encoded" value="<%= encoded %>">

<input type="hidden" name="plaingoto" value="<%= request.getParameter("goto") %>">
</auth:form>

</jato:content>


...

  2. Remove the web container's temporary, compiled JSP to ensure that the changes made are picked up.

    For example, if you are using GlassFish, the temporary, compiled classes are in the glassfish-home/domains/your-domain/generated/ directory.

  3. Restart the OpenSSO Enterprise web container after making the changes.

ProcedureTo Use the Sample Login.jsp

  1. Locate the file opensso/integrations/idm/jsps/Login.jsp in the decompressed opensso.zip distribution.

  2. Replace the deployed web-container-deploy-base/opensso/config/auth/default/Login.jsp file.

    Choose only one of the following two options:

    You can replace your existing Login.jsp with the sample Login.jsp. If you choose this option, the following will occur:

    • You will lose any custom changes made to the existing Login.jsp.

    • You will inherit changes that might have been previously made to the sample Login.jsp to incorporate requirements for other use cases related to the OpenSSO integration with Identity Manager.

    • You must change the Identity Manager URL embedded in the sample Login.jsp to reflect the Identity Manager system URL of your architecture.

      You can search for the string /idm to locate the URLs.

    Alternatively, you can make the changes manually. If you choose this option, first run the diff command to view the differences between the deployed Login.jsp and the sample Login.jsp, and then make the changes manually.

  3. Remove the web containers temporary, compiled JSP to ensure that the changes made are picked up.

    For example, if you are using GlassFish, the temporary, compiled classes is in the glassfish-home/domains/your-domain/generated/ directory.

  4. Restart the OpenSSO web container after making the changes.

Configuring the Identity Manager Password Controls

When the Identity Manager password controls are configured for administrator-initiated password reset, the following occur:

ProcedureTo Configure the Identity Manager Password Controls

  1. Log in to Identity Manager as an administrator.

  2. Navigate to the Configure tab.

  3. Click on the link "Form and Process Mappings.”

  4. Search for the entry "endUserChangePassword. "

    In the text field, replace "End User Change Password Form" with "Basic Change Password Form.”

  5. Save the changes.

ProcedureTo Test the Identity Manager Password Control Configuration

  1. Login to Identity Manager as a regular user .

  2. Under the "Profile" tab, go to the "Change password" page.

    You should see that SunAccessManagerRealm requires the old password.

  3. Enter the user's the old password, the new password, and confirmation of the new password,

    The user's password should be set in the Directory Server user data store as a "self-change” instead of am "admin-change.” This is especially important if the pwdMustChange or passwordMustChange attributes had been earlier set on the user's profile on the Directory Server. If the self-change configuration is not implemented, when the user logs back into OpenSSO Enterprise, the user will be asked to change his password again

Testing Administrator-Initiated Password Reset Configurations

To verify the behavior for each stage of this use case, perform the following validation tests in this exact order:

  1. Test the password expiration warning.

  2. Test the password expiration.

  3. Test the administrator-initiated password reset.

ProcedureTo Test the Password Expiration Warning

Complete the following steps after the time for the password expiration warning, as defined in the password policy, would take effect.

  1. Access a URL protected by OpenSSO Enterprise .

    The OpenSSO login page is displayed.

  2. Enter the test user name and password.

    You are redirected to Identity Manager to change your password. Note the following about the Identity Manager URL:

    • The URL is the one configured in ChangePassword.jsp.

    • The user will be forwarded to the value of the goto parameter after the password has been successfully changed.

    • The value of the accountId parameter determines the account for which the password needs to be changed. Identity Manager will make the changes to the password on both Identity Manager and OpenSSO Enterprise .

ProcedureTo Test the Password Expiration

Complete the following steps after the time the password should have expired, as defined in the password policy.

  1. Access a URL protected by OpenSSO Enterprise.

    The OpenSSO Enterprise login page is displayed.

  2. Enter the test user name and password.

    An error page is displayed indicating the test user that the password has expired. The user is then instructed to ask the administrator to reset the password.

ProcedureTo Test Administrator-Initiated Password Reset

Before You Begin

The Directory Server must have logging and auditing features enabled. Use these features to monitor the Directory Server audit log as you complete the test. See the Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide .

  1. Log in as the Directory Administrator, and change the password for a test user.

    This simulates the password reset by a HelpDesk administrator.

  2. Verify that the user's userPassword attribute was modified, and that the pwdreset attribute was set to TRUE using the audit log.

    The pwdreset attribute will force the user to change the password at the next login. The audit log might resemble this sample:

    time: 20090713074720
dn: uid=idmuser1,dc=sun,dc=com
changetype: modify
replace: userPassword
userPassword: {SSHA}4Bgy/HF9SGN9nnS4Ii6/KJj9ktFdAxQUIDvwVQ==
-
replace: modifiersname
modifiersname: cn=admin,cn=administrators,cn=dscc
-
replace: modifytimestamp
modifytimestamp: 20090713144720Z
-
replace: passwordexpirationtime
passwordexpirationtime: 19700101000000Z
-
replace: pwdreset
pwdreset: TRUE

  3. Access the Identity Manager user URL.

    You are redirected to OpenSSO Enterprise for login.

  4. Enter the test user name and password.

    You are redirected to Identity Manager to change your password. Note the following about the Identity Manager URL:

    • The URL is the one configured in ChangePassword.jsp.

    • The user is forwarded to the value of the goto parameter after the password has been successfully changed.

    • The value of the accountId parameter determines the account for which the password needs to be changed. Identity Manager will make the changes to the password on both Identity Manager and OpenSSO Enterprise.

Troubleshooting Administrator-Initiated Account Unlock

If you cannot log in to OpenSSO Enterprise, verify that you are using the correct userid and password. The Directory Administrator who reset your password should have communicated to you the temporary password for the user account.

Monitor the Directory Server's access log, during login. You should see successful SRCH and BIND operations, for the user. Example: 


[15/Jul/2009:09:32:12 -0700] conn=158 op=9 msgId=269 - 
SRCH base="dc=sun,dc=com" scope=2 filter="(uid=idmuser1)" attrs="dn uid"

[15/Jul/2009:09:32:12 -0700] conn=158 op=9 msgId=269 - 
RESULT err=0 tag=101 nentries=1 etime=0

[15/Jul/2009:09:32:12 -0700] conn=160 op=5 msgId=270 - 
BIND dn="uid=idmuser1,dc=sun,dc=com" method=128 version=3

[15/Jul/2009:09:32:12 -0700] conn=160 op=5 msgId=270 - 
RESULT err=0 tag=97 nentries=0 etime=0 dn="uid=idmuser1,dc=sun,dc=com"

The string err=0 in the entries above indicates success for that operation.

After you log in to OpenSSO Enterprise , if you are not redirected to the Identity Manager page, check the following :