Merge remote-tracking branch 'origin/mdb.master' into OPENLDAP_REL_ENG_2_4

[openldap] / doc / guide / admin / sasl.sdf

diff --git a/doc/guide/admin/sasl.sdf b/doc/guide/admin/sasl.sdf
index c2d8a5742b02cbe43aa25e3e0c5118e96fb8a715..9f8a7a66cd3eb0a12b66294dc34a5e98997078b2 100644 (file)
--- a/doc/guide/admin/sasl.sdf
+++ b/doc/guide/admin/sasl.sdf
@@ -1,5 +1,5 @@
 # $OpenLDAP$
 # $OpenLDAP$

-# Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.

 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Using SASL
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Using SASL


@@ -72,10 +72,13 @@ and large enterprises.  Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}}
 are discussed below.
 
 The EXTERNAL mechanism utilizes authentication services provided
 are discussed below.
 
 The EXTERNAL mechanism utilizes authentication services provided

-by lower level network services such as {{TERM:TLS}} (TLS).  When
+by lower level network services such as {{TERM[expand]TLS}} ({{TERM:TLS}}).  When

 used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public
 used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public

-key technology, EXTERNAL offers strong authentication.  Use of
-EXTERNAL is discussed in the {{SECT:Using TLS}} chapter.
+key technology, EXTERNAL offers strong authentication.
+TLS is discussed in the {{SECT:Using TLS}} chapter.
+
+EXTERNAL can also be used with the {{EX:ldapi:///}} transport, as
+Unix-domain sockets can report the UID and GID of the client process.

 
 There are other strong authentication mechanisms to choose from,
 including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure
 
 There are other strong authentication mechanisms to choose from,
 including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure


@@ -267,9 +270,9 @@ See {{SECT: Mapping Authentication Identities}} below for information
 on optional mapping of identities.
 
 With suitable mappings in place, users can specify SASL IDs when
 on optional mapping of identities.
 
 With suitable mappings in place, users can specify SASL IDs when

-performing LDAP operations and sldb}} and the directory itself will
-be used to verify the authentication.  For example, the user
-identified by the directory entry:
+performing LDAP operations, and the password stored in {{sasldb}} or in
+the directory itself will be used to verify the authentication.
+For example, the user identified by the directory entry:

 
 >       dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com
 >       objectclass: inetOrgPerson
 
 >       dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com
 >       objectclass: inetOrgPerson


@@ -289,6 +292,41 @@ The server will infer an authorization identity from authentication
 identity (as described below).
 
 
 identity (as described below).
 
 

+H3: EXTERNAL
+
+The SASL EXTERNAL mechanism makes use of an authentication performed
+by a lower-level protocol: usually {{TERM:TLS}} or Unix {{TERM:IPC}}
+
+Each transport protocol returns Authentication Identities in its own
+format:
+
+H4: TLS Authentication Identity Format
+
+This is the Subject DN from the client-side certificate.
+Note that DNs are displayed differently by LDAP and by X.509, so
+a certificate issued to
+>      C=gb, O=The Example Organisation, CN=A Person
+
+will produce an authentication identity of:
+
+>      cn=A Person,o=The Example Organisation,c=gb
+
+Note that you must set a suitable value for TLSVerifyClient to make the server
+request the use of a client-side certificate. Without this, the SASL EXTERNAL
+mechanism will not be offered.
+Refer to the {{SECT:Using TLS}} chapter for details.
+
+H4: IPC (ldapi:///) Identity Format
+
+This is formed from the Unix UID and GID of the client process:
+
+>      gidNumber=<number>+uidNumber=<number>,cn=peercred,cn=external,cn=auth
+
+Thus, a client process running as {{EX:root}} will be:
+
+>      gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
+
+

 H3: Mapping Authentication Identities
 
 The authentication mechanism in the slapd server will use SASL
 H3: Mapping Authentication Identities
 
 The authentication mechanism in the slapd server will use SASL


@@ -652,7 +690,7 @@ To help produce more sweeping rules for {{EX:authzFrom}} and
 be DNs with regular expression characters in them. This means a
 source rule like
 
 be DNs with regular expression characters in them. This means a
 source rule like
 

->      authzTo: dn.regex=^uid=[^,]*,dc=example,dc=com$
+>      authzTo: dn.regex:^uid=[^,]*,dc=example,dc=com$

 
 would allow that authenticated user to authorize to any DN that
 matches the regular expression pattern given. This regular expression
 
 would allow that authenticated user to authorize to any DN that
 matches the regular expression pattern given. This regular expression