Password Hook Tool

SAP NetWeaver® Identity Management

Password Hook

Configuration Guide

Version 7.0 Rev 2

© Copyright 2008 SAP AG. All rights reserved.

SAP Library document classification: PUBLIC

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Microsoft, Windows, Outlook, Excel, and PowerPoint are registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, System i, System i5, System p, System p5, System x, System z, System z9, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/OS, POWER, POWER5, POWER5+, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML, and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves information purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

i

Preface

The product The purpose of the SAP NetWeaver Identity Management Password Hook is to synchronize passwords from a Microsoft domain to one or more applications. This is achieved by capturing password changes from the Microsoft domain and updating the password in the other applications through a provisioning solution.

The reader This manual is written for people who are going to install and configure the Password Hook.

Prerequisites To get the most benefit from this manual, you should have the following knowledge:

• Knowledge of the Identity Center.

• Microsoft Domain security.

• Knowledge of the security policy of your organization.

The following software is required:

• SAP NetWeaver Identity Management Identity Center version 7.0 SP2 or newer must be correctly installed and licensed.

• Password Hook version 7.0 SP2 or newer.

The manual This manual consists of five sections. In the first section you see how to install and update the Password Hook. The second section describes how you configure the Password Hook. The third section describes integration with the Identity Center. The fourth section highlights some implementation considerations, while the fifth section is about troubleshooting. The introduction describes the scenario, some security and policy issues and file locations.

Related documents You can find useful information in the following documents:

• Article in Microsoft Developer Network Library: "Password filter", http://msdn2.microsoft.com/en-us/library/ms721882%28VS.85%29.aspx

• SAP NetWeaver Identity Management Security Guide


http://msdn2.microsoft.com/en-us/library/ms721882%28VS.85%29.aspx

ii


iii

Table of contents Introduction........................................................................................................................................ 1

The scenario ...............................................................................................................................................1 Security and policy issues ..........................................................................................................................1 Files and file locations................................................................................................................................2 Section overview........................................................................................................................................2

Section 1: Installing and upgrading the Password Hook ............................................................... 3 Installing the Password Hook.....................................................................................................................3 Upgrading the Password Hook...................................................................................................................4

Section 2: Configuring the Password Hook..................................................................................... 5 Section 3: Integrating with the Identity Center .............................................................................. 9

The Password Hook configuration .............................................................................................................9 The job definition .....................................................................................................................................10

Section 4: Implementation considerations..................................................................................... 11 Section 5: Troubleshooting.............................................................................................................. 12


iv


1 Introduction SAP NetWeaver Identity Management Password Hook Configuration Guide

Introduction The SAP NetWeaver Identity Management Password Hook is a password hook DLL that can be installed on the Microsoft domain controller(s) in the password verification chain. If the correct domain security policy is enabled, the Password Hook will be notified whenever a user tries to change his/her password. This allows the hook to intercept password changes in the Microsoft domain and distribute it to other applications using the SAP NetWeaver Identity Management Identity Center. This allows the user passwords of other applications to be synchronized with the passwords in the Windows domain.

The Password Hook can be one of several password hooks installed on the Microsoft controller. All enabled password hooks will be notified for each password change.

The scenario The Password Hook can start a job that writes the password to an identity store in the Identity Center. From there, the new password is distributed to a number of target applications using mechanisms in the Identity Center.

Security and policy issues Note: By installing the Password Hook, you may be violating the security policy of your organization. SAP makes no guarantees regarding the security and takes no responsibility for any security breaches which may occur as a result of implementing this product.

It is important to understand the nature of passwords when implementing a solution using the Password Hook.

A password is used by a user to authenticate against an application, and will give the user certain rights within that system. The password is known as a "shared secret", based on the assumption that it is known only by the user and the application. If the password is exposed, an attacker may be able to masquerade as (that is log in as) the user, and perform operations only allowed by this user. There is no way of detecting or logging this kind of security attack.

Applications make efforts to store the password as securely as possible, for example using a one-way encryption algorithm. By implementing any type of password hook, you will in most cases increase the risk of password exposure, and this risk should be carefully assessed with regards to consequences of exposure.

Another detail that should be considered is to which applications a password is synchronized. When the same password is used in all applications, a security attack with the purpose of obtaining a given user’s password could be directed towards the application with the weakest security. Therefore you should carefully consider which systems should be synchronized.


2 Introduction

SAP NetWeaver Identity Management Password Hook Configuration Guide

Files and file locations The Password Hook is distributed together with the Identity Center. It is not installed together with the Identity Center – it needs to be installed separately. The files you need to install/update (and configure) the Password Hook are to be found in the installation kit under the PasswordHook folder.

When the Password Hook is installed, the default destination directory for the installation folder "HookConfig" is C:\Program Files. We recommend that you change the destination directory to C:\Program Files\SAP\IdM\Password Hook that also is used in this manual. The .dll file is installed in the Windows System directory (C:\WINDOWS\system32\MxPwdHook.dll).

File Directory Description setup.exe .\PasswordHook Run this file to install the Password Hook. Install

the Password Hook on the Microsoft domain controller.

newpass.bat C:\Program Files\SAP\IdM\Password Hook\

This is a sample BAT file that can be used to test the Password Hook. The file is included in the installation.

TestHook.exe C:\Program Files\SAP\IdM\Password Hook\

This is a small test program included in the installation. It simulates a password change for a test user and can be used to test the configuration of the Password Hook.

Section overview The manual consists of the following sections:

Section 1: Installing and upgrading the Password Hook

In this section you see how to install and update the Password Hook.

Section 2: Configuring the Password Hook Here you configure the Password Hook.

Section 3: Integrating with the Identity Center Here you learn how to configure and integrate the Password Hook with the Identity Center. You see how a job in the Identity Center can be run as the password notification program.

Section 4: Implementation considerations This section describes some issues you need to take into the consideration when implementing the Password Hook.

Section 5: Troubleshooting This section addresses some possible problems and their solutions.


3 Section 1: Installing and upgrading the Password Hook SAP NetWeaver Identity Management Password Hook Configuration Guide

Section 1: Installing and upgrading the Password Hook Even though the Password Hook is distributed together with the Identity Center, it still needs to be installed separately. The necessary data for installing the Password Hook is included in the installation kit. The files are located in the PasswordHook folder in the kit.

Install the Password Hook on the Microsoft domain controller.

Note: Make sure that you are logged on as a user with administrator privileges when running the installation program.

Installing the Password Hook To install the program:

1. Navigate to the PasswordHook folder in the installation kit.

2. Start the installation by choosing setup.exe. You can use the default values for all steps in the process, though we advice to change the installation directory to C:\Program Files\SAP\IdM\Password Hook. When creating a new installation folder, a dialog box appears, warning you that the directory does not exist and asking whether you want to create it. Answer "Yes" to close the dialog box and to create a folder before continuing the installation.

3. Enable the following setting, if necessary:

Choose All Programs/Administrative Tools/Domain Controller Security Policy from the "Start" menu to open the "Domain Controller Security Policy" window.

Choose "Windows Settings\Security Settings\Account Policies\Password Policy" in the

console tree and enable "Passwords must meet complexity requirements".

4. Restart the server.


4 Section 1: Installing and upgrading the Password Hook


Upgrading the Password Hook If you are upgrading the Password Hook, you must disable the Password Hook and restart the server before the program can be upgraded. This is because the Windows LSA (Local Security Authority) locks the DLL file until the DLL has been disabled and the system restarted. Thus, the DLL has to be disabled before it can be upgraded. This is done by deselecting "Enable hook" in the "SAP Password Hook configuration" dialog box. Remember to choose the "Save to registry" button, to save the changes before closing the dialog box.

To upgrade, you run the same procedure as when installing the Password Hook.


5 Section 2: Configuring the Password Hook SAP NetWeaver Identity Management Password Hook Configuration Guide

Section 2: Configuring the Password Hook The Password Hook must be configured to perform the necessary actions when a user changes his/her password. The Password Hook can call two applications when a password change is initiated. Both of them receive the user name and password as parameters.

• The (optional) password filter program is called before the password is changed in the domain controller. This can be used for external password verification/password policy, and can return a status value preventing the password from being changed.

• The password notification program that is called after the password is changed in the domain controller. This is used to distribute the new password to other applications.

The Password Hook can call any script or program that can take the user's name and password as arguments. The installation of the Password Hook contains a sample BAT file, newpass.bat, which can be used to test the Password Hook.

For more information about password change filtering and notification, see "Password filter" in Microsoft Developer Network Library, http://msdn2.microsoft.com/en-us/library/ms721882%28VS.85%29.aspx

To configure the Password Hook:

1. Open the "SAP Password Hook configuration" dialog box by choosing All Programs/SAP NetWeaver Identity Management/SAP PasswordHook from the "Start" menu.

2. Fill in the fields with the following values:

Enable hook Select this check box to enable the hook.

Note: If the hook was not enabled at the last startup, the computer must be restarted before the hook is activated. If the hook was enabled at the last startup, the hook can be disabled (and enabled) without restarting the server.




6 Section 2: Configuring the Password Hook


General parameters:

Working directory The working directory for the notification and filter programs.

Environment variables Environment variables set before executing the notification and filter programs. Use the syntax parameter=value separated by pipe (|).

This can be path to any JDBC drivers or other client software necessary to access the target systems. For instance:

PATH = E:\oracle\ora90\bin|SystemRoot = d:\winnt

Priority Priority to use for the process running the notification and filter programs. You can choose between:

• Idle

• Normal, recommended

• High

Encrypt password Select this check box to specify that the password should be encrypted when submitted to the notification and filter applications.

Note: This will not actually encrypt the password, but scramble it to hide it from the viewers. This assumes that applications which receive the encrypted password are applications which are able to decrypt the password. This functionality exists in the Identity Center. If not checked, the password will be passed unencrypted.

This is important for two reasons. The password is submitted to the filter and notification programs as parameters on the command line. Thus, the password should be encrypted.

Encrypting the password also ensures that a user is not able to execute code disguised as a carefully crafted password. The filter and notification programs are executed with administrator privileges, and such code will be executed with administrator privileges.

Notification:

Password notification program Enter the name of or select the program which will be called after the user's password has been changed in the domain controller.

Arguments Specify any arguments to the password notification program or script. You can use the following variables:

%1 user name

%2 password

%3 relative ID

If any of the parameters includes spaces, enclose them in double quotes.

Wait for execution Maximum time in milliseconds to wait for the password notification program to complete execution. If it fails to complete within this limit, an error message will be logged. "0" means that it will not wait for the program to complete.


7 Section 2: Configuring the Password Hook SAP NetWeaver Identity Management Password Hook Configuration Guide

Filter:

Password filter program Enter the name of or select the program that will be called before the user's password is changed in the domain controller.

Note: If the filter program fails or it cannot be executed, any password change will be denied. Make sure that this field is empty if you are not using the filter mechanism.

This should be an executable program or a .bat file. All arguments must be specified in the in the "Arguments" field.

If this script returns anything but a zero (0) as the exit condition, the password change will be denied. This gives us a good way to allow/deny password changes based on a particular programs result, for example to enforce a password policy.

Leave this field empty if you do not want to filter passwords.

Arguments Specify any arguments to the password filter program. You can use the following parameters:

%1 user name

%2 password

%3 full name

If any of the parameters includes spaces, enclose them in double quotes.

For example, if you are using a Java program to handle user passwords, the "Password filter program" will be set to "jre" or "C:\Program Files\Java\bin\jre.exe". The "Arguments" would be any parameters to the Java runtime and the class you would like to run. For instance:

"-cp "C:\Program Files\MyJavaClasses" passwd %1 %2"

Using this example, when the user test changes the password to "P@ssW0rd", the full command line executed will be:

"C:\Program Files\Java\bin\jre.exe" -cp "C:\Program Files\MyJavaClasses" passwd test P@ssW0rd

Note: The definition of the program must not contain any parameters. These must always be defined in the arguments field.

Wait for execution Maximum time in milliseconds to wait for the password filter program to complete execution. If it fails to complete within this limit, the password change will be denied. "0" means that it will not wait for the program to complete, and the password will never be changed.

Logging:

Log file Enter the path and the file name of the log file. This should be a local file.

Maximum log file size Specify the maximum size in kilobytes of the log file. When this limit is reached, the log file is truncated to 25% of this size, with the most recent log entries kept. The old log file is renamed with a .bak extension. To disable the log truncation, enter "0" in this field.


8 Section 2: Configuring the Password Hook


Redirect program output to log file Select this check box to specify that the output from the notification and filter programs should be included in the log file.

Log level Select a log level. You can choose between:

• None (0)

• Error (1)

• Debug (2)

• All (3)

With the log level "All", the user passwords are stored in the log file together with other data, so use this option with care.

Note: Choosing a value different from "None" and not specifying a valid log file may have unpredictable results.

3. You can:

Choose "Save to registry" to save the settings to registry and close the dialog box.

Choose the button "Save to file…" to save the configuration to a file for back-up purposes, or to easily be able to copy the configuration to another machine.

Choose the "Read to registry" button to read the configuration from the registry.

Choose the "Read from file…" button to read the configuration from a previously saved file.

Choose "Close" to close the dialog box without saving the settings.


9 Section 3: Integrating with the Identity Center SAP NetWeaver Identity Management Password Hook Configuration Guide

Section 3: Integrating with the Identity Center The Identity Center can be used as a password notification program. When installing the Password Hook, a number of job/pass templates are installed that can be used to create jobs that can be called from the Password Hook.

The Password Hook configuration This sample configuration shows how you can run a job in the Identity Center as the password notification program and the sample BAT file newpass.bat is called as the filter program:

Notification:

Password notification program This command line will start the Windows runtime engine of the Identity Center.

Arguments The parameters to the runtime engine are the job file name, and the user name and password as global constants that are used by the pass.

The password must be the last parameter when using the Windows runtime engine. When using the Java runtime engine, the sequence of the parameters is insignificant.


10 Section 3: Integrating with the Identity Center


Filter:

Password filter program This command line will start the sample BAT file.

Arguments The user name and password are passed to the bat file.

Given the user name Testus and the password P@ssw0rd, the Windows runtime engine will be called with the following command line:

newpass.dse "-DUSER=Testus" "-DPASSWORD={CRYPT}C1ZFd3Z5MXJj("

The job definition The sample job contains a single pass that writes the user name and password to a text file. To insert the job newpass.dse (in the Identity Center):

1. Choose "First group" under the "Data Synchronization Engine" entry in the console tree, and choose "Import job…" from the context menu.

2. Navigate to the newpass.dse job in the directory C:\Program Files\SAP\IdM\Password Hook, and choose "Open".

The job is created in the Identity Center.


11 Section 4: Implementation considerations SAP NetWeaver Identity Management Password Hook Configuration Guide

Section 4: Implementation considerations When implementing the Password Hook, the following should be considered:

• The company’s password policy.

• The security of the applications where the password is written. If one application does not store password securely, an attacker may get access to all systems by cracking this system.

• Access rights to intermediate files within the implemented solution. Intermediate files may contain a password, and is a risk of exposure.

• The security of the Identity Center configuration file. If an attacker has access to the configuration file, it may be modified to expose the password, for example by writing this to a file.

• The log from the Identity Center. Ensure that the clear-text password never is written to log files which are accessible by possible attackers.


12 Section 5: Troubleshooting


Section 5: Troubleshooting If you encounter some problems, you can use the following table to solve the problem:

Symptom: The password hook was installed, but nothing happens when a password is changed.

1. Are there any entries in the log file that provide some information?

The log file should be specified (with full path) in the configuration dialog.

2. Check that the Password Hook was properly installed, and that it has been loaded at startup.

Open the configuration dialog box, and check that the "Enable hook" checkbox is selected.

The hook DLL is called MxPwdHook.dll, and should be installed in the Windows System directory. If the DLL has been loaded at startup, it will be locked by the operating system. Try to rename the DLL. If you are allowed to rename it, it has not been loaded. Remember to rename it back to MxPwdHook.dll.

The server must be restarted before the hook will be called. Hook DLLs are only loaded at startup.

If the hook was disabled during the last boot, you will have to restart the server after re-enabling the hook.

If the hook was enabled during boot, you can disable/re-enable it without restarting the server.

3. Is password policy enabled?

If not already enabled, you must enable the setting:

"Domain Security Policy>Windows Settings>Security Settings>Account Policies>Password Policy>Passwords must meet complexity requirements".

Symptom: After installing the password hook, nobody is allowed to change their password.

1. Check the configuration of the "Password filter program".

The password hook allows you to specify password filtering. This is implemented by executing the configured "Password filter program". If this fails, it will be interpreted as "Password did not satisfy the filter" and the password change will be denied.

If you are not using the filter mechanism, make sure that this field is empty.

2. Password policy

If you had to enable the setting:

"Domain Security Policy>Windows Settings>Security Settings>Account Policies>Password Policy>Passwords must meet complexity requirements".

Some other filter may have set a stricter password policy. Try to identify the password policy of these filter programs. Or try to specify a complex password containing a mix of lowercase/uppercase characters and numbers.

i.e. try P@ssW0rd, Password123, kdhgvHJe3456 etc.


13 Section 5: Troubleshooting SAP NetWeaver Identity Management Password Hook Configuration Guide

Symptom: The filter detected the password change, but the application specified as "Password notification program" was never started, or failed to run properly

1. The setup job includes a small test program TestHook.exe.

It will simulate a password change for user "Testus", full name "Test User", relative ID "1234" and new password: P@ssw0rd.

You can use this to test the configuration of the password hook.

If everything is ok when using the test program, but fails on actual password changes, the cause is most likely in the user environment.

When you execute the test program, everything is executed in the context of the logged on user, with its access rights, and environment.

When the notification and filter programs are called from the system on a real password change, everything is executed in the context of the system account.

This might cause problems if the program(s) called depend(s) on environment variables, specific accesses or needs to interact with the desktop.


14 Section 5: Troubleshooting



Documents

Password Hook Tool