# $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
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
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
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
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