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

<chapter xml:id='chap-pta'

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

<title>Configuring Pass Through Authentication</title>

<indexterm><primary>Pass through authentication</primary></indexterm>

<para>This chapter focuses on pass through authentication (PTA), whereby you

configure another server to determine the response to an authentication

request. A typical use case for pass through authentication involves

passing authentication through to Active Directory for users coming

from Microsoft Windows systems.</para>

<section xml:id="about-pta">

<title>About Pass Through Authentication</title>

<para>You use <firstterm>LDAP pass through authentication</firstterm> when

the credentials for authenticating are stored not in OpenDJ, but instead

in a remote directory service. In effect OpenDJ redirects the bind operation

against a remote LDAP server.</para>

<para>Exactly how OpenDJ redirects the bind depends on how the user entry

in OpenDJ maps to the corresponding user entry in the remote directory.</para>

<itemizedlist>

<para>OpenDJ provides you several choices to set up the mapping.</para>

<listitem>

<para>When both the local entry in OpenDJ and the remote entry in the

other server have the same DN, you do not have to set up the mapping at

all. By default, OpenDJ redirects the bind with the original DN and

password from the client application.</para>

</listitem>

<listitem>

<para>When the local entry in OpenDJ has been provisioned with an attribute

holding the DN of the remote entry, you can specify which attribute holds

the DN, and OpenDJ redirects the bind on the remote server using the DN

value.</para>

</listitem>

<listitem>

<para>When you cannot get the remote bind DN directly, you need an

attribute and value on the OpenDJ entry that corresponds to an identical

attribute and value on the remote server in order to map the local entry

to the remote entry. In this case you also need the bind credentials for

a user who can search for the entry on the remote server. OpenDJ performs

a search for the entry using the matching attribute and value, and then

redirects the bind with the DN from the remote entry.</para>

</listitem>

</itemizedlist>

<para>You configure pass through authentication as an authentication policy

that you associate with a user's entry in the same way that you associate

a password policy with a user's entry. Either a user has an authentication

policy for pass through authentication, or the user has a local password

policy.</para>

</section>

<section xml:id="configure-pta">

<title>Setting Up Pass Through Authentication</title>

<para>When setting up pass through authentication, you need to know to which

remote server or servers to redirect binds, and you need to know how you map

user entries in OpenDJ to user entries in the remote directory.</para>

<procedure xml:id="configure-ssl-to-test-pta">

<title>To Set Up SSL Communication For Testing</title>

<para>When performing pass through authentication, you no doubt protect

communications between OpenDJ and the server providing authentication. If

you test using SSL with self-signed certificates, and you do not want

the client blindly to trust the server, follow these steps to import

the authentication server's certificate into the OpenDJ key store.</para>

<step>

<para>Export the server certificate from the authentication server.</para>

<para>How you perform this step depends on the authentication directory

server. With OpenDJ, you can export the certificate as shown here.</para>

<screen>

$ <userinput>cd /path/to/PTA-Server/config</userinput>

$ <userinput>keytool \

-exportcert \

-rfc \

-alias server-cert \

-keystore keystore \

-storepass `cat keystore.pin` \

> /tmp/pta-srv-cert.pem</userinput>

</screen>

</step>

<step>

<para>Make note of the host name used in the certificate.</para>

<para>You use the host name when configuring the SSL connection. With

OpenDJ, you can view the certificate details as shown here.</para>

<screen>

$ <userinput>keytool \

-list \

-v \

-alias server-cert \

-keystore keystore \

-storepass `cat keystore.pin`</userinput>

<computeroutput>Alias name: server-cert

Creation date: Sep 12, 2011

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate[1]:

Owner: CN=pta-server.example.com, O=OpenDJ Self-Signed Certificate

Issuer: CN=pta-server.example.com, O=OpenDJ Self-Signed Certificate

Serial number: 4e6dc429

Valid from: Mon Sep 12 10:34:49 CEST 2011 until: Wed Sep 11 10:34:49 CEST 2013

Certificate fingerprints:

MD5: B6:EE:1C:A0:71:12:EF:6F:21:24:B9:50:EF:8B:4E:6A

SHA1: 7E:A1:C9:07:D2:86:56:31:24:14:F7:07:A8:6B:3E:A1:39:63:F4:0E

Signature algorithm name: SHA1withRSA

Version: 3</computeroutput>

</screen>

</step>

<step>

<para>Import the authentication server certificate into OpenDJ's

key store.</para>

<screen>

$ <userinput>cd /path/to/opendj/config</userinput>

$ <userinput>keytool \

-importcert \

-alias pta-cert \

-keystore truststore \

-storepass `cat keystore.pin` \

-file /tmp/pta-srv-cert.pem</userinput>

<computeroutput>Owner: CN=pta-server.example.com, O=OpenDJ Self-Signed Certificate

Issuer: CN=pta-server.example.com, O=OpenDJ Self-Signed Certificate

Serial number: 4e6dc429

Valid from: Mon Sep 12 10:34:49 CEST 2011 until: Wed Sep 11 10:34:49 CEST 2013

Certificate fingerprints:

MD5: B6:EE:1C:A0:71:12:EF:6F:21:24:B9:50:EF:8B:4E:6A

SHA1: 7E:A1:C9:07:D2:86:56:31:24:14:F7:07:A8:6B:3E:A1:39:63:F4:0E

Signature algorithm name: SHA1withRSA

Version: 3

Trust this certificate? [no]:</computeroutput> <userinput>yes</userinput>

<computeroutput>Certificate was added to keystore</computeroutput>

</screen>

</step>

</procedure>

<procedure xml:id="configure-pta-policy">

<title>To Configure an LDAP Pass Through Authentication Policy</title>

<para>You configure authentication policies with the

<command>dsconfig</command> command. Notice that authentication policies

are part of the server configuration, and therefore not replicated.</para>

<step>

<para>Set up an authentication policy for pass through

authentication to the authentication server.</para>

<screen>

$ <userinput>dsconfig \

create-password-policy \

--port 4444 \

--hostname opendj.example.com \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--type ldap-pass-through \

--policy-name "PTA Policy" \

--set primary-remote-ldap-server:pta-server.example.com:636 \

--set mapped-attribute:uid \

--set mapped-search-base-dn:"dc=PTA Server,dc=com" \

--set mapping-policy:mapped-search \

--set use-ssl:true \

--set trust-manager-provider:JKS \

--trustAll \

--no-prompt</userinput>

</screen>

<para>The policy shown here maps identities having this password policy

to identities under <literal>dc=PTA Server,dc=com</literal>. Users must

have the same <literal>uid</literal> values on both servers. The policy

here also uses SSL between OpenDJ and the authentication server.</para>

</step>

<step>

<para>Check that your policy has been added to the list.</para>

<screen>

$ <userinput>dsconfig \

list-password-policies \

--port 4444 \

--hostname opendj.example.com \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--property use-ssl</userinput>

<computeroutput>

Password Policy : Type : use-ssl

------------------------:-------------------:--------

Default Password Policy : password-policy : -

PTA Policy : ldap-pass-through : true

Root Password Policy : password-policy : -</computeroutput>

</screen>

</step>

</procedure>

<procedure xml:id="configure-pta-to-ad">

<title>To Configure Pass Through Authentication To Active Directory</title>

<indexterm>

<primary>Active Directory</primary>

<see>Pass through authentication</see>

</indexterm>

<para>The steps below demonstrate setting up pass through authentication

to Active Directory. Here is some background to help you make sense of the

steps.</para>

<para>Entries on the OpenDJ side use <literal>uid</literal> as the naming

attribute, and entries also have <literal>cn</literal> attributes. Active

Directory entries use <literal>cn</literal> as the naming attribute.

User entries on both sides share the same <literal>cn</literal> values. The

mapping between entries therefore uses <literal>cn</literal>.</para>

<para>Consider the example where an OpenDJ account with <literal>cn=LDAP

PTA User</literal> and DN

<literal>uid=ldapptauser,ou=People,dc=example,dc=com</literal> corresponds

to an Active Directory account with DN <literal>CN=LDAP PTA

User,CN=Users,DC=internal,DC=forgerock,DC=com</literal>. The steps below

enable the user with <literal>cn=LDAP PTA User</literal> on OpenDJ

authenticate through to Active Directory.</para>

<screen>

$ <userinput>ldapsearch \

--hostname opendj.example.com \

--baseDN dc=example,dc=com \

uid=ldapptauser \

cn</userinput>

<computeroutput>dn: uid=ldapptauser,ou=People,dc=example,dc=com

cn: LDAP PTA User</computeroutput>

$ <userinput>ldapsearch \

--hostname ad.example.com \

--baseDN "CN=Users,DC=internal,DC=forgerock,DC=com" \

--bindDN "cn=administrator,cn=Users,DC=internal,DC=forgerock,DC=com" \

--bindPassword password \

"(cn=LDAP PTA User)" \

cn</userinput>

<computeroutput>dn: CN=LDAP PTA User,CN=Users,DC=internal,DC=forgerock,DC=com

cn: LDAP PTA User</computeroutput>

</screen>

<para>OpenDJ must map its

<literal>uid=ldapptauser,ou=People,dc=example,dc=com</literal> entry to the

Active Directory entry, <literal>CN=LDAP PTA

User,CN=Users,DC=internal,DC=forgerock,DC=com</literal>. In order to do the

mapping, OpenDJ has to perform a search for the user in Active Directory

using the <literal>cn</literal> value it recovers from its own entry for the

user. Active Directory does not allow anonymous searches, so part of the

authentication policy configuration consists of the administrator DN and

password OpenDJ uses to bind to Active Directory to be able to search.</para>

<para>Finally, before setting up the pass through authentication policy,

make sure OpenDJ can connect to Active Directory over a secure connection

to avoid sending passwords in the clear.</para>

<step>

<para>Export the certificate from the Windows server.</para>

<substeps>

<step>

<para>Click start &gt; All Programs &gt; Administrative Tools &gt;

Certification Authority, then right-click the CA and select

Properties.</para>

</step>

<step>

<para>In the General tab, select the certificate and click View

Certificate.</para>

</step>

<step>

<para>In the Certificate dialog, click the Details tab, then click

Copy to File...</para>

</step>

<step>

<para>Use the Certificate Export Wizard to export the certificate into

a file, such as <filename>windows.cer</filename>.</para>

</step>

</substeps>

</step>

<step>

<para>Copy the exported certificate to the system running OpenDJ.</para>

</step>

<step>

<para>Import the server certificate into OpenDJ's key store.</para>

<screen>

$ <userinput>cd /path/to/opendj/config</userinput>

$ <userinput>keytool \

-importcert \

-alias ad-cert \

-keystore truststore \

-storepass `cat keystore.pin` \

-file ~/Downloads/windows.cer</userinput>

<computeroutput>Owner: CN=internal-ACTIVEDIRECTORY-CA, DC=internal, DC=forgerock, DC=com

Issuer: CN=internal-ACTIVEDIRECTORY-CA, DC=internal, DC=forgerock, DC=com

Serial number: 587465257200a7b14a6976cb47916b32

Valid from: Tue Sep 20 11:14:24 CEST 2011 until: Tue Sep 20 11:24:23 CEST 2016

Certificate fingerprints:

MD5: A3:D6:F1:8D:0D:F9:9C:76:00:BC:84:8A:14:55:28:38

SHA1: 0F:BD:45:E6:21:DF:BD:6A:CA:8A:7C:1D:F9:DA:A1:8E:8A:0D:A4:BF

Signature algorithm name: SHA1withRSA

Version: 3

Extensions:

#1: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[

CA:true

PathLen:2147483647

]

#2: ObjectId: 2.5.29.15 Criticality=false

KeyUsage [

DigitalSignature

Key_CertSign

Crl_Sign

]

#3: ObjectId: 2.5.29.14 Criticality=false

SubjectKeyIdentifier [

KeyIdentifier [

0000: A3 3E C0 E3 B2 76 15 DC 97 D0 B3 C0 2E 77 8A 11 .>...v.......w..

0010: 24 62 70 0A $bp.

]

]

#4: ObjectId: 1.3.6.1.4.1.311.21.1 Criticality=false

Trust this certificate? [no]:</computeroutput> <userinput>yes</userinput>

<computeroutput>Certificate was added to keystore</computeroutput>

</screen>

<para>At this point OpenDJ can connect to Active Directory over SSL.</para>

</step>

<step>

<para>Set up an authentication policy for OpenDJ users to authenticate

to Active Directory.</para>

<screen>

$ <userinput>dsconfig \

create-password-policy \

--port 4444 \

--hostname opendj.example.com \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--type ldap-pass-through \

--policy-name "AD PTA Policy" \

--set primary-remote-ldap-server:ad.example.com:636 \

--set mapped-attribute:cn \

--set mapped-search-base-dn:"CN=Users,DC=internal,DC=forgerock,DC=com" \

--set mapped-search-bind-dn:"cn=administrator,cn=Users,DC=internal, \

DC=forgerock,DC=com" \

--set mapped-search-bind-password:password \

--set mapping-policy:mapped-search \

--set trust-manager-provider:JKS \

--set use-ssl:true \

--trustAll \

--no-prompt</userinput>

</screen>

</step>

<step>

<para>Assign the authentication policy to a test user.</para>

<screen>

$ <userinput>ldapmodify \

--port 1389 \

--bindDN "cn=Directory Manager" \

--bindPassword password

dn: uid=ldapptauser,ou=People,dc=example,dc=com

changetype: modify

add: ds-pwp-password-policy-dn

ds-pwp-password-policy-dn: cn=AD PTA Policy,cn=Password Policies,cn=config</userinput>

<computeroutput>Processing MODIFY request for uid=ldapptauser,ou=People,dc=example,dc=com

MODIFY operation successful for DN uid=ldapptauser,ou=People,dc=example,dc=com</computeroutput>

</screen>

</step>

<step>

<para>Check that the user can bind using pass through authentication to

Active Directory.</para>

<screen>

$ <userinput>ldapsearch \

--hostname opendj.example.com \

--port 1389 \

--baseDN dc=example,dc=com \

--bindDN uid=ldapptauser,ou=People,dc=example,dc=com \

--bindPassword password \

"(cn=LDAP PTA User)" \

userpassword cn</userinput>

<computeroutput>dn: uid=ldapptauser,ou=People,dc=example,dc=com

cn: LDAP PTA User</computeroutput>

</screen>

<para>Notice that to complete the search, the user authenticated with a

password to Active Directory, though no <literal>userpassword</literal>

value is present on the entry on the OpenDJ side.</para>

</step>

</procedure>

</section>

<section xml:id="assigning-pta">

<title>Assigning Pass Through Authentication Policies</title>

<para>You assign authentication policies in the same way as you

assign password policies, by using the

<literal>ds-pwp-password-policy-dn</literal> attribute.</para>

<note>

<para>Although you assign the pass through authentication policy using

the same attribute as for password policy, the authentication policy is

not in fact a password policy. Therefore, the user with a pass through

authentication policy does not have a value for the operational attribute

<literal>pwdPolicySubentry</literal>.</para>

<screen>

$ <userinput>ldapsearch \

--port 1389 \

--baseDN dc=example,dc=com \

uid=user.0 \

pwdPolicySubentry</userinput>

<computeroutput>dn: uid=user.0,ou=People,dc=example,dc=com</computeroutput>

</screen>

</note>

<procedure xml:id="assign-pta-to-user">

<title>To Assign a Pass Through Authentication Policy To a User</title>

<para>Users depending on pass through authentication no longer need a local

password policy, as they no longer authenticate locally.</para>

<para>Examples in the following procedure work for this user, whose

entry on OpenDJ is as shown. Notice that the user has no password set. The

user's password on the authentication server is

<literal>password</literal>.</para>

<programlisting language="ldif">

dn: uid=user.0,ou=People,dc=example,dc=com

cn: Aaccf Amar

description: This is the description for Aaccf Amar.

employeeNumber: 0

givenName: Aaccf

homePhone: +1 225 216 5900

initials: ASA

l: Panama City

mail: user.0@maildomain.net

mobile: +1 010 154 3228

objectClass: person

objectClass: inetorgperson

objectClass: organizationalperson

objectClass: top

pager: +1 779 041 6341

postalAddress: Aaccf Amar$01251 Chestnut Street$Panama City, DE 50369

postalCode: 50369

sn: Amar

st: DE

street: 01251 Chestnut Street

telephoneNumber: +1 685 622 6202

uid: user.0

</programlisting>

<para>This user's entry on the authentication server also has

<literal>uid=user.0</literal>, and the pass through authentication policy

performs the mapping to find the user entry in the authentication

server.</para>

<step>

<para>Prevent users from changing their own password policies.</para>

<screen>

$ <userinput>cat protect-pta.ldif</userinput>

<computeroutput>dn: ou=People,dc=example,dc=com

changetype: modify

add: aci

aci: (target ="ldap:///uid=*,ou=People,dc=example,dc=com")(targetattr =

"ds-pwp-password-policy-dn")(version 3.0;acl "Cannot choose own pass

word policy";deny (write)(userdn = "ldap:///self");)</computeroutput>

$ <userinput>ldapmodify \

--port 1389 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--filename protect-pta.ldif</userinput>

<computeroutput>Processing MODIFY request for ou=People,dc=example,dc=com

MODIFY operation successful for DN ou=People,dc=example,dc=com</computeroutput>

</screen>

</step>

<step>

<para>Update the user's <literal>ds-pwp-password-policy-dn</literal>

attribute.</para>

<screen>

$ <userinput>ldapmodify \

--port 1389 \

--bindDN "cn=Directory Manager" \

--bindPassword password

dn: uid=user.0,ou=People,dc=example,dc=com

changetype: modify

add: ds-pwp-password-policy-dn

ds-pwp-password-policy-dn: cn=PTA Policy,cn=Password Policies,cn=config</userinput>

<computeroutput>Processing MODIFY request for uid=user.0,ou=People,dc=example,dc=com

MODIFY operation successful for DN uid=user.0,ou=People,dc=example,dc=com</computeroutput>

</screen>

</step>

<step>

<para>Check that the user can authenticate through to the authentication

server.</para>

<screen>

$ <userinput>ldapsearch \

--port 1389 \

--baseDN dc=example,dc=com \

--bindDN uid=user.0,ou=People,dc=example,dc=com \

--bindPassword password \

uid=user.0 \

cn sn</userinput>

<computeroutput>dn: uid=user.0,ou=People,dc=example,dc=com

cn: Aaccf Amar

sn: Amar</computeroutput>

</screen>

</step>

</procedure>

<procedure xml:id="assign-pta-to-group">

<title>To Assign a Pass Through Authentication Policy To a Group</title>

<para>Examples in the following steps use the pass through authentication

policy as defined above. Kirsten Vaughan's entry has been reproduced on

the authentication server under <literal>dc=PTA

Server,dc=com</literal>.</para>

<step>

<para>Create a subentry to assign a collective attribute that sets the

<literal>ds-pwp-password-policy-dn</literal> attribute for group

members' entries.</para>

<screen>

$ <userinput>cat pta-coll.ldif</userinput>

<computeroutput>dn: cn=PTA Policy for Dir Admins,dc=example,dc=com

objectClass: collectiveAttributeSubentry

objectClass: extensibleObject

objectClass: subentry

objectClass: top

cn: PTA Policy for Dir Admins

ds-pwp-password-policy-dn;collective: cn=PTA Policy,cn=Password Policies,

cn=config

subtreeSpecification: { base "ou=People", specificationFilter "(isMemberOf=

cn=Directory Administrators,ou=Groups,dc=example,dc=com)"}</computeroutput>

$ <userinput>ldapmodify \

--port 1389 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--defaultAdd \

--filename pta-coll.ldif</userinput>

<computeroutput>Processing ADD request for cn=PTA Policy for Dir Admins,dc=example,dc=com

ADD operation successful for DN cn=PTA Policy for Dir Admins,dc=example,dc=com</computeroutput>

</screen>

</step>

<step>

<para>Check that OpenDJ has applied the policy.</para>

<substeps>

<step>

<para>Make sure you can bind as the user on the authentication

server.</para>

<screen>

$ <userinput>ldapsearch \

--port 2389 \

--bindDN "uid=kvaughan,ou=People,dc=PTA Server,dc=com" \

--bindPassword password \

--baseDN "dc=PTA Server,dc=com" \

uid=kvaughan</userinput>

<computeroutput>dn: uid=kvaughan,ou=People,dc=PTA Server,dc=com

objectClass: person

objectClass: organizationalPerson

objectClass: inetOrgPerson

objectClass: top

givenName: Kirsten

uid: kvaughan

cn: Kirsten Vaughan

sn: Vaughan

userPassword: {SSHA}x1BdtrJyRTw63kBSJFDvgvd4guzk66CV8L+t8w==

ou: People

mail: jvaughan@example.com</computeroutput>

</screen>

</step>

<step>

<para>Check that the user can authenticate through to the authentication

server from OpenDJ.</para>

<screen>

$ <userinput>ldapsearch \

--port 1389 \

--bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \

--bindPassword password \

--baseDN dc=example,dc=com \

uid=kvaughan \

cn sn</userinput>

<computeroutput>dn: uid=kvaughan,ou=People,dc=example,dc=com

cn: Kirsten Vaughan

sn: Vaughan</computeroutput>

</screen>

</step>

</substeps>

</step>

</procedure>

</section>

</chapter>