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$
-# 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
@@ -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
-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
-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
@@ -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
-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
@@ -289,6 +292,41 @@ The server will infer an authorization identity from authentication
 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
@@ -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
 
->      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