<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-passwords'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Password Management</title>

<para>OpenIDM provides password management features that help you enforce

password policies, limit the number of passwords users must remember, and

let users reset and change their passwords.</para>

<section xml:id="enforce-password-policy">

<title>Enforcing Password Policy</title>

<para>A password policy is a set of rules defining what sequence of

characters constitutes an acceptable password. Acceptable passwords generally

are too complex for users or automated programs to generate or guess.</para>

<para>Password policies set requirements for password length, character sets

that passwords must contain, dictionary words and other values that passwords

must not contain. Password policies also require that users not reuse old

passwords, and that users change their passwords on a regular basis.</para>

<para>OpenIDM can enforce password policy rules by applying validation rules

to attributes of managed user objects. Suppose you want to rule out use of

the following user passwords.</para>

<itemizedlist>

<listitem><para><literal>password</literal></para></listitem>

<listitem><para><literal>123456</literal></para></listitem>

<listitem><para><literal>12345678</literal></para></listitem>

<listitem><para><literal>qwerty</literal></para></listitem>

<listitem><para><literal>abc123</literal></para></listitem>

</itemizedlist>

<para>You could include the following configuration in

<filename>conf/manage.json</filename> where you installed OpenIDM to prevent

users from using those passwords.</para>

<programlisting language="javascript">

{

"objects": [

{

"name": "user",

"properties": [

{

"name": "password",

"encryption": {

"key": "openidm-sym-default"

}

}

],

"validate": {

"type": "text/javascript",

"source": "TODO"

}

}

]

}</programlisting>

<para>The validation policy lets you define rules to validate a property's

value after OpenIDM retrieves the object, and before storing the object. If

the value violates the rules, OpenIDM throws an exception.</para>

<para>The following example extends the set of rules to ensure the password

has at least 8 characters, and that it starts with a numeric character.</para>

<programlisting language="javascript">

{

"objects": [

{

"name": "user",

"properties": [

{

"name": "password",

"encryption": {

"key": "openidm-sym-default"

}

}

],

"validate": {

"type": "text/javascript",

"source": "TODO"

}

}

]

}</programlisting>

<para>TODO: Show results when a user violates a rule.</para>

<variablelist>

<para>This mechanism can apply in many situations.</para>

<varlistentry>

<term>Password change and password reset</term>

<listitem>

<para>Password change involves changing a user or account password

in accordance with password policy. Password reset involves setting a

new user or account password on behalf of a user.</para>

<para>You can configure OpenIDM to control password values as they are

provisioned as shown in the previous examples.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password recovery</term>

<listitem>

<para>Password recovery involves recovering a password or setting a new

password when the password has been forgotten.</para>

<para>OpenIDM can provide a self-service end user interface for password

changes, password recovery, and password reset.</para>

<para>TODO: Show how to set up UI for this</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password comparisons with dictionary words</term>

<listitem>

<para>You can add dictionary lookups to prevent use of password values

that match dictionary words.</para>

<para>TODO: Example</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password history</term>

<listitem>

<para>You can add checks to prevent reuse of previous password

values</para>

<para>TODO: Example</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password expiration</term>

<listitem>

<para>You can configure OpenIDM to call a workflow that ensures users

are able to change expiring or to reset expired passwords.</para>

<para>TODO: Example</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="password-sync">

<title>Password Synchronization</title>

<para>Password synchronization intercepts user password changes, and ensures

uniform password changes across resources that store the password. Following

password synchronization, the user authenticates using the same password on

each resource. No centralized directory or authentication server is required

for performing authentication. Password synchronization reduces the number of

passwords users need to remember, so they can use fewer, stronger

passwords.</para>

<para>OpenIDM can propagate passwords to the resources storing a user's

password. OpenIDM can intercept and synchronize passwords changed natively

on OpenDJ and Active Directory. See the example in

<filename>samples/misc/managed.json</filename> where you installed OpenIDM

for a sample password synchronization configuration.</para>

<para>Before using the sample, you must set up OpenDJ and Active Directory,

and adjust the password attributes, set in the sample as

<literal>ldapPassword</literal> for OpenDJ, <literal>adPassword</literal>

for Active Directory, and <literal>password</literal> for the internal

OpenIDM password. Also, either set up password policy enforcement on OpenDJ

or Active Directory rather than OpenIDM, or ensure that all password policies

enforced are identical to prevent password updates on one resource from being

rejected by OpenIDM or by another resource.</para>

<para>Also set up password synchronization plugins for OpenDJ and for Active

Directory. The password synchronization plugins help by intercepting password

changes on the resource before the passwords are stored in encrypted

form. The plugins then send intercepted password values to OpenIDM over an

encrypted channel.</para>

<procedure xml:id="install-opendj-password-sync-plugin">

<title>To Install the OpenDJ Password Synchronization Plugin</title>

<para>The following steps install the plugin in OpenDJ directory server

running on the same host as OpenIDM. If you run OpenDJ on a different host

use the fully qualified domain name rather than <literal>localhost</literal>

as shown here, and use your certificates rather than the example.</para>

<step>

<para>Download the OpenDJ password synchronization plugin,

<link xlink:href="http://download.forgerock.org/downloads/openidm/snapshot/opendj-accountchange-handler-1.0.0-SNAPSHOT.zip"

>opendj-accountchange-handler-1.0.0-SNAPSHOT.zip</link>.</para>

<para></para>

</step>

<step>

<para>Unzip the plugin in the directory where you installed OpenDJ.</para>

<screen>$ cd /path/to/OpenDJ

$ unzip ~/Downloads/opendj-accountchange-handler-1.0.0-SNAPSHOT.zip</screen>

</step>

<step>

<para>Import the self-signed OpenIDM certificate into the trust store for

OpenDJ.</para>

<screen>$ cd /path/to/OpenDJ/config

$ keytool

-import

-alias openidm-localhost

-keystore truststore

-storepass `cat keystore.pin`

-file /path/to/openidm/samples/security/openidm-localhost-cert.txt

Owner: CN=localhost, O=OpenIDM Self-Signed Certificate

Issuer: CN=localhost, O=OpenIDM Self-Signed Certificate

Serial number: 4e4bc38e

Valid from: Wed Aug 17 15:35:10 CEST 2011 until: Tue Aug 17 15:35:10 CEST 2021

Certificate fingerprints:

MD5: B8:B3:B4:4C:F3:22:89:19:C6:55:98:C5:DF:47:DF:06

SHA1: DB:BB:F1:14:55:A0:53:80:9D:62:E7:39:FB:83:15:DA:60:63:79:D1

Signature algorithm name: SHA1withRSA

Version: 3

Trust this certificate? [no]: yes

Certificate was added to keystore</screen>

</step>

<step>

<para>Configure an OpenIDM notification handler in OpenDJ.</para>

<screen>$ cd /path/to/OpenDJ/bin

$ /dsconfig TODO</screen>

</step>

<step>

<para>Restart OpenDJ.</para>

<screen>$ /stop-ds --restart</screen>

</step>

<step>

<para>Enable the plugin for the appropriate password policy.</para>

<para>The following command enables the plugin for the default password

policy.</para>

<screen>$ dsconfig

set-password-policy-prop

--port 4444

--hostname opendj.example.com

--bindDN "cn=Directory Manager"

--bindPassword password

--policy-name "Default Password Policy"

--set account-status-notification-handler:"OpenIDM Notification Handler"

--trustStorePath config/admin-truststore

--no-prompt</screen>

</step>

<step>

<para>Configure OpenIDM to access the password changes from OpenDJ.</para>

<para>TODO: show how this works</para>

</step>

</procedure>

<procedure xml:id="install-ad-password-sync-plugin">

<title>To Install the Active Directory Password Synchronization Plugin</title>

<para>You install the plugin on Active Directory primary domain controllers

to intercept password changes, and send the password values to OpenIDM over

an encrypted channel. You must have Administrator privileges to install the

plugin.</para>

<step>

<para>Download the Active Directory password synchronization plugin,

<filename>ad-passwordchange-handler-<?eval ${docTargetVersion}?>.exe</filename>.</para>

<para>http://maven.forgerock.org/repo/simple/releases/org/forgerock/openidm/agent/ad-passwordchange-handler/1.0.0/ad-passwordchange-handler-1.0.0.exe</para>

</step>

<step>

<para>Unzip the plugin, and double-click <filename>setup.exe</filename> to

launch the installation wizard.</para>

</step>

<step>

<para>Complete the installation with the help of the following hints.</para>

<variablelist>

<varlistentry>

<!-- Yes, this hint seems unnecessary. But if people need to know what

<term>CDDL license agreement</term>

<listitem>

<para>You must accept the agreement to proceed with the

installation.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>OpenIDM URL</term>

<listitem>

<para>URL where OpenIDM is deployed such as

<literal>https://openidm.example.com:8080/openidm</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Private Key alias</term>

<listitem>

<para>TODO: Check this. Alias used when importing the OpenIDM

certificate, such as <literal>openidm-cert</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>Private Key password</term>

<listitem>

<para>TODO: Check this. Password to access the OpenIDM private key</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Directory poll interval (seconds)</term>

<listitem>

<para>TODO: Check this. Number of seconds between calls to check that

Active Directory is available ????, such as 5</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Select Certificate File</term>

<listitem>

<para>TODO: Check this. The PKCS 12 format file containing the

certificate used to encrypt communications with OpenIDM.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Select Output Directory</term>

<listitem>

<para>The plugin stores files in the location you select. This can be

the same as the directory where you install the plugin.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Select Log Directory</term>

<listitem>

<para>The plugin stores logs in the location you select. This can be

the same as the directory where you install the plugin.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Select Destination Location</term>

<listitem>

<para>Setup installs the plugin in the location you select, by default

<filename>C:\Program Files\OpenIDM Password Sync</filename>.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

<step>

<para>After running the installation wizard, restart the computer.</para>

</step>

</procedure>

<para>TODO: show password synchronization in operation</para>

</section>

</chapter>