<?xml version="1.0" encoding="UTF-8"?>
|
<!--
|
! CCPL HEADER START
|
!
|
! This work is licensed under the Creative Commons
|
! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
|
! To view a copy of this license, visit
|
! http://creativecommons.org/licenses/by-nc-nd/3.0/
|
! or send a letter to Creative Commons, 444 Castro Street,
|
! Suite 900, Mountain View, California, 94041, USA.
|
!
|
! You can also obtain a copy of the license at
|
! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
|
! See the License for the specific language governing permissions
|
! and limitations under the License.
|
!
|
! If applicable, add the following below this CCPL HEADER, with the fields
|
! enclosed by brackets "[]" replaced with your own identifying information:
|
! Portions Copyright [yyyy] [name of copyright owner]
|
!
|
! CCPL HEADER END
|
!
|
! Copyright 2011-2013 ForgeRock AS
|
!
|
-->
|
<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'
|
xmlns:xlink='http://www.w3.org/1999/xlink'
|
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
|
<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>$ cd /path/to/PTA-Server/config
|
$ keytool
|
-exportcert
|
-rfc
|
-alias server-cert
|
-keystore keystore
|
-storepass `cat keystore.pin`
|
> /tmp/pta-srv-cert.pem</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>$ keytool
|
-list
|
-v
|
-alias server-cert
|
-keystore keystore
|
-storepass `cat keystore.pin`
|
Alias name: server-cert
|
Creation date: Sep 12, 2011
|
Entry type: PrivateKeyEntry
|
Certificate chain length: 1
|
Certificate[1]:
|
Owner: CN=<emphasis role="strong">pta-server.example.com</emphasis>, O=OpenDJ Self-Signed Certificate
|
Issuer: CN=<emphasis role="strong">pta-server.example.com</emphasis>, 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</screen>
|
</step>
|
<step>
|
<para>Import the authentication server certificate into OpenDJ's
|
key store.</para>
|
<screen>$ cd /path/to/opendj/config
|
$ keytool
|
-importcert
|
-alias pta-cert
|
-keystore truststore
|
-storepass `cat keystore.pin`
|
-file /tmp/pta-srv-cert.pem
|
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]: yes
|
Certificate was added to keystore</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>$ 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</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>$ dsconfig
|
list-password-policies
|
--port 4444
|
--hostname opendj.example.com
|
--bindDN "cn=Directory Manager"
|
--bindPassword password
|
--property use-ssl
|
|
Password Policy : Type : use-ssl
|
------------------------:-------------------:--------
|
Default Password Policy : password-policy : -
|
PTA Policy : ldap-pass-through : true
|
Root Password Policy : password-policy : -</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>$ ldapsearch
|
--hostname opendj.example.com
|
--baseDN dc=example,dc=com
|
uid=ldapptauser
|
cn
|
dn: uid=ldapptauser,ou=People,dc=example,dc=com
|
cn: LDAP PTA User
|
|
$ 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
|
dn: CN=LDAP PTA User,CN=Users,DC=internal,DC=forgerock,DC=com
|
cn: LDAP PTA User</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 > All Programs > Administrative Tools >
|
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>$ cd /path/to/opendj/config
|
$ keytool
|
-importcert
|
-alias ad-cert
|
-keystore truststore
|
-storepass `cat keystore.pin`
|
-file ~/Downloads/windows.cer
|
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]: yes
|
Certificate was added to keystore</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>$ 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</screen>
|
</step>
|
<step>
|
<para>Assign the authentication policy to a test user.</para>
|
<screen>$ 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
|
|
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</screen>
|
</step>
|
<step>
|
<para>Check that the user can bind using pass through authentication to
|
Active Directory.</para>
|
<screen>$ 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
|
dn: uid=ldapptauser,ou=People,dc=example,dc=com
|
cn: LDAP PTA User</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>$ ldapsearch
|
--port 1389
|
--baseDN dc=example,dc=com
|
uid=user.0
|
pwdPolicySubentry
|
dn: uid=user.0,ou=People,dc=example,dc=com
|
</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>$ cat protect-pta.ldif
|
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");)
|
|
$ ldapmodify
|
--port 1389
|
--bindDN "cn=Directory Manager"
|
--bindPassword password
|
--filename protect-pta.ldif
|
Processing MODIFY request for ou=People,dc=example,dc=com
|
MODIFY operation successful for DN ou=People,dc=example,dc=com</screen>
|
</step>
|
<step>
|
<para>Update the user's <literal>ds-pwp-password-policy-dn</literal>
|
attribute.</para>
|
<screen>$ 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
|
|
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</screen>
|
</step>
|
<step>
|
<para>Check that the user can authenticate through to the authentication
|
server.</para>
|
<screen>$ 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
|
dn: uid=user.0,ou=People,dc=example,dc=com
|
cn: Aaccf Amar
|
sn: Amar
|
</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>$ cat pta-coll.ldif
|
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)"}
|
|
$ ldapmodify
|
--port 1389
|
--bindDN "cn=Directory Manager"
|
--bindPassword password
|
--defaultAdd
|
--filename pta-coll.ldif
|
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</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>$ ldapsearch
|
--port 2389
|
--bindDN "uid=kvaughan,ou=People,dc=PTA Server,dc=com"
|
--bindPassword password
|
--baseDN "dc=PTA Server,dc=com"
|
uid=kvaughan
|
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
|
</screen>
|
</step>
|
<step>
|
<para>Check that the user can authenticate through to the authentication
|
server from OpenDJ.</para>
|
<screen>$ ldapsearch
|
--port 1389
|
--bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
|
--bindPassword password
|
--baseDN dc=example,dc=com
|
uid=kvaughan
|
cn sn
|
dn: uid=kvaughan,ou=People,dc=example,dc=com
|
cn: Kirsten Vaughan
|
sn: Vaughan</screen>
|
</step>
|
</substeps>
|
</step>
|
</procedure>
|
</section>
|
</chapter>
|
