-# Copyright 1999-2006 The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# 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
or pattern, and terms in parenthesis are remembered for the replacement
pattern.
-The replacement pattern will produce either a DN or URL refering
+The replacement pattern will produce either a DN or URL referring
to the user. Anything from the authentication request DN that
matched a string in parenthesis in the search pattern is stored in
the variable "$1". That variable "$1" can appear in the replacement
become that DN, users must first authenticate as one of the persons
on the list. This allows for better auditing of who made changes
to the LDAP database. If people were allowed to authenticate
-directly to the priviliged account, possibly through the {{EX:rootpw}}
+directly to the privileged account, possibly through the {{EX:rootpw}}
{{slapd.conf}}(5) directive or through a {{EX:userPassword}}
attribute, then auditing becomes more difficult.
In the first form, the <username> is from the same namespace as
the authentication identities above. It is the user's username as
-it is refered to by the underlying authentication mechanism.
+it is referred to by the underlying authentication mechanism.
Authorization identities of this form are converted into a DN format
by the same function that the authentication process used, producing
an {{authorization request DN}} of the form
specify the authorization is permitted, the {{EX:authzFrom}}
rules in the authorization DN entry are then checked. If neither
case specifies that the request be honored, the request is denied.
-Since the default behaviour is to deny authorization requests, rules
+Since the default behavior is to deny authorization requests, rules
only specify that a request be allowed; there are no negative rules
telling what authorizations to deny.
be DNs with regular expression characters in them. This means a
source rule like
-> authzTo: 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
Also note that the values in an authorization rule must be one of
the two forms: an LDAP URL or a DN (with or without regular expression
characters). Anything that does not begin with "{{EX:ldap://}}" is
-taken as a DN. It is not permissable to enter another authorization
+taken as a DN. It is not permissible to enter another authorization
identity of the form "{{EX:u:<username>}}" as an authorization rule.
By default, processing of proxy authorization rules is disabled.
The {{EX:authz-policy}} directive must be set in the
{{slapd.conf}}(5) file to enable authorization. This directive can
-be set to {{EX:none}} for no rules (the default), {{EX:from}} for
-source rules, {{EX:to}} for destination rules, or {{EX:both}} for
+be set to {{EX:none}} for no rules (the default), {{EX:to}} for
+source rules, {{EX:from}} for destination rules, or {{EX:both}} for
both source and destination rules.
-Destination rules are extremely powerful. If ordinary users have
+Source rules are extremely powerful. If ordinary users have
access to write the {{EX:authzTo}} attribute in their own
entries, then they can write rules that would allow them to authorize
-as anyone else. As such, when using destination rules, the
+as anyone else. As such, when using source rules, the
{{EX:authzTo}} attribute should be protected with an ACL that
only allows privileged users to set its values.