From d59c19407cc0f1c429cd3cab0606b851d5c25a33 Mon Sep 17 00:00:00 2001 From: Mark Adamson Date: Wed, 17 Jan 2001 23:48:53 +0000 Subject: [PATCH] Add new chapter telling how to configure SASL authentication and authorization. --- doc/guide/admin/sasl.sdf | 431 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 431 insertions(+) create mode 100644 doc/guide/admin/sasl.sdf diff --git a/doc/guide/admin/sasl.sdf b/doc/guide/admin/sasl.sdf new file mode 100644 index 0000000000..fc3fba9b79 --- /dev/null +++ b/doc/guide/admin/sasl.sdf @@ -0,0 +1,431 @@ +# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. + +H1: SASL + + OpenLDAP clients and servers are capable of providing authentication +via the Simple Authentication Security Layer (SASL) system, which is +explained in RFC 2222. There are several industry standard +authentication mechanisms that can be used with SASL, including +Kerberos V4, GSSAPI, and some of the Digest mechanisms. The standard +client tools provided with OpenLDAP, such as {{ldapsearch}}(1) and +{{ldapmodify}}(1), will by default attempt to authenticate the user +to the {{slapd}}(8) server using SASL. Basic authentication service +can be set up by the LDAP administrator with a few steps, allowing +users to be authenticated to the slapd server as their LDAP entry. With +a few extra steps, some users and services can be allowed to exploit +SASL's authorization feature, allowing them to authenticate themselves +and then switch their identity to that of another user or service. + + Note that in the following text the term "{{user}}" is used to +describe a person who is connecting to the LDAP server via a client +program, such as {{ldapsearch}}(1). The term can also be used to +describe a computer program that runs itself and accesses the LDAP +database, such as a sendmail program or a nightly update program run +out of cron. Thus {{"user"}} refers to any computer process connecting +to the LDAP server, whether or not it has a human monitoring it. + + +H2: SASL Authentication + + Getting basic SASL authentication running involves a few simple +steps. The first step configures your slapd server environment so that +it can communicate with client programs using the security system in +place at your site. This usually involves setting up a service key, a +public key, or other form of secret. The second step concerns mapping +authentication identities to LDAP DN's, which depends on how entries +are laid out in your directory. An explanation of the first step will +be given in the next section using Kerberos V4 as an example +mechanism. The steps necessary for your site's authentication +mechanism will be similar, but a guide to every mechanism available +under SASL is beyond the scope of this chapter. The next section after +that describes the second step of mapping authentication identities to +DN's. + + +H3: MIT Kerberos V4 + + It will be assumed that you are familiar with the workings of MIT's +Kerberos security system, and that your site has this mechanism in +place. Your users should be familiar with authentication policy, are +aware of how to receive credentials in a Kerberos ticket cache, and +how to refresh expired credentials. + + Client programs will need to be able to obtain a session key for use +when connecting to your LDAP server. This allows the LDAP server to +know the identity of the user, and allows the client to know it is +connecting to a legitimate server. If encryption layers are to be +used, the session key can also be used to help negotiate that option. + + The slapd server runs the service called "{{ldap}}", and the server +will require a srvtab file with a service key. SASL aware client +programs will be obtaining an "ldap" service ticket with the user's +ticket granting ticket (TGT), with the instance of the ticket matching +the hostname of the OpenLDAP server. For example, if your realm is +named EXAMPLE.COM and the slapd server is running on the host named +directory.example.com, the /etc/srvtab file on the server will have a +service key + +> ldap.directory@EXAMPLE.COM + +When a SASL client is authenticating a user to LDAP, it will request a +session key for that same principal, either from the ticket cache or +by obtaining a new one from the kerberos server. This will require the +TGT to be available and valid in the cache as well. If it is not +present or has expired, SASL will print out the message + +> ldap_sasl_interactive_bind_s: Local error + +When the service ticket is obtained, it will be passed to the LDAP +server as proof of the user's identity. The server will take the +user's username and realm out of the service ticket using SASL library +calls, and convert them into an {{authentication request DN}} of the form + +> uid=,cn=,cn=,cn=authzid + +So in our above example, if the user's name were "adamson", the +authentication request DN would be: + +> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTHZID + +This authentication request DN by itself could be placed into ACL's +and {{EX:groupOfNames}} "member" attributes, since it is of legitimate +LDAP DN format. The next section, however, tells how to map that DN +into the DN of a person's own LDAP entry. + + Also note that this example, being for Kerberos, shows the +portion of the DN being filled in with the Kerberos realm of the +company. Several other authentication mechanisms do not emply the +concept of a realm, so the ",cn=" portion of the authentication +request DN would not appear. + + +H3: Mapping Authentication identities to LDAP entries + + The authentication mechanism in the slapd server will use SASL +library calls to obtain the authenticated user's "username", based on +whatever underlying authentication mechanism was used. This username is +in the namespace of the authentication mechanism, and not in the LDAP +namespace. As stated in the section above, that username is +reformatted into an authentication request DN of the form + +> uid=,cn=,cn=,cn=authzid + +or + +> uid=,cn=,cn=authzid + +depending on whether or not employs the concept of "realms". + + It is not intended that you should add LDAP entries of the above +form to your LDAP database. Chances are you have an LDAP entry for +each of the people that will be authenticating to LDAP, laid out in +your directory tree, and the tree does not start at cn=authzid. But if +your site has a clear mapping between the "username" and an LDAP entry +for the person, you will be able to configure your LDAP server to +automatically map a user's authentication username to their +{{authentication DN.}} + + The LDAP administrator will need to tell the slapd server how to map +an authentication request DN to a user's authentication DN. This is +done by adding one or more {{EX:saslRegexp}} directives to the +{{slapd.conf}}(5) file. This directive takes two arguments: + +> saslRegexp + + The authentication request DN is compared to the search pattern +using the regular expression functions {{regcomp}}() and +{{regexec}}(), and if it matches, it is rewritten as the replacement +pattern. If there are multiple {{EX:saslRegexp}} directives, only the first +whose search pattern matches the authentication identity is used. The +string that is output from the replacement pattern should be the +authentication DN of the user, in a legitimate LDAP DN format. It can +also be an LDAP URI, which is discussed below. + + The search pattern can contain any of the regular expression +characters listed in {{regexec}}(3C). The main characters of note are +dot ".", asterisk "*", and the open and close parenthesis "(" and ")". +Essentially, the dot matches any character, the asterisk matches one +or more characters, and terms in parenthesis are remembered for the +replacement pattern. + + The replacement pattern will produce the final authentication DN of +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 pattern, and +will be replaced by the string from the authentication request DN. If +there were multiple sets of parenthesis in the search pattern, the +variables $2, $3, etc are used. + + For example, suppose the user's authentication identity is written +as the DN string + +> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTHZID + +and the user's actual LDAP entry is + +> uid=ADAMSON,ou=PERSON,dc=EXAMPLE,dc=COM + +The {{EX:saslRegexp}} directive in {{slapd.conf}}(5) could be written + +> saslRegexp +> uid=(.*),cn=example.com,cn=kerberos_v4,cn=authzid +> uid=$1,ou=person,dc=example,dc=com + +An even more lenient rule could be written as + +> saslRegexp +> uid=(.*),.*cn=authzid +> uid=$1,ou=person,dc=example,dc=com + + Be careful about setting the search pattern too leniently, however, +since it may mistakenly allow people to become authenticated as a DN +to which they should not have access. It is better to write several +strict directives than one lenient directive which has security +holes. If there is only one authentication mechanism in place at your +site, and zero or one realms in use, you might be able to map between +authentication identities and LDAP DN's with a single {{EX:saslRegexp}} +directive. + + Some sites may have people's DN's spread to multiple areas of the +LDAP tree, such as if there were an ou=accounting tree and an +ou=engineering tree, with people interspersed between them. Or there +may not be enough information in the authentication identity to +isolate the DN, such as if the above person's LDAP entry looked like + +> dn: cn=mark adamson,ou=person,dc=example,dc=com +> objectclass: Person +> cn: mark adamson +> uid: adamson + +In this case, the information in the authentication identity can only +be used to search for the user's DN, not derive it directly. For both +of these situations, and others, the replacement pattern in the +{{EX:saslRegexp}} directives will need to produce an LDAP URI, +described in the next section. + + +H3: Performing searches for a person's DN + + When there is not enough information in the authentication identity +to derive a person's authentication DN directly, the {{EX:saslRegexp}} +directives in the {{slapd.conf}}(5) file will need to produce an +LDAP URI. This URI will then be used to perform an internal search of +the LDAP database to find the person's authentication DN. + + An LDAP URI, similar to other URI's, is of the form + +> ldap:///??? + +This contains all of the elements necessary to perform an LDAP search: +the name of the server , the LDAP DN search base , the +LDAP attributes to retrieve , the search scope which is +one of the three options "base", "one", or "sub", and lastly an LDAP +search filter . Since the search is for an LDAP DN on the +local machine, the portion is ignored. By the same token the + field is also ignored since only the DN is of concern. These +two elements are left in the format of the URI to maintain the clarity +of what information goes where in the string. + + Suppose that the person in the example from above did in fact have +an authentication username of "adamson" and that information was kept +in the attribute "uid" in their LDAP entry. The {{EX:saslRegexp}} +directive might be written as + +> saslRegexp +> uid=(.*),cn=example.com,cn=kerberos_v4,cn=authzid +> ldap://localhost/ou=person,dc=example,dc=com??sub?uid=$1 + + This will initiate an internal search of the LDAP database inside the +slapd server. If the search returns exactly one entry, it is accepted +as being the DN of the user. If there are more than one entries +returned, or if there are zero entries returned, the authentication +fails and the user's connection is left bound as the authentication +request DN. + + Note that if the search scope in the URI is "base", then the +only LDAP entry that will be returned is the searchbase DN , so +the actual search of the database is skipped. This is equivalent to +setting the replacement pattern in the directive to a DN directly, as +in the section above. + + The attributes that are used in the search filter in the +URI should be indexed to allow faster searching. If they are not, the +authentication step alone can take uncomfortably long periods, and +users may assume the server is down. + + +H2: SASL Authorization + + The SASL library offers a feature known as {{authorization}}, which +allows an authenticated user to request that they act on the behalf of +another user. This step occurs after the user has obtained an +authentication DN, and involves sending an authorization identity to +the server. The server will then make a decision on whether or not to +allow the authorization to occur. If it is allowed, the user's LDAP +connection is switched to have a binding DN derived from the +authorization identity, and the LDAP session proceeds with the access +of the new authorization DN. + + The decision to allow an authorization to proceed depends on the +rules and policies of the site where LDAP is running, and thus cannot +be made by SASL alone. The SASL library leaves it up to the server to +make the decision. The LDAP administrator sets the guidelines of who +can authorize to what identity by adding information into the LDAP +database entries. + + +H3: Uses of Authorization + + This sort of service is useful when one entity needs to act on the +behalf of many other users. For example, users may be directed to a +web page to make changes to their personal information in their LDAP +entry. The users authenticate to the web server to establish their +identity, but the web server CGI cannot authenticate to the LDAP +server as that user to make changes for them. Instead, the web server +authenticates itself to the LDAP server as a service identity, say, + +> cn=WebUpdate,dc=example,dc=com + +and then it will SASL authorize to the DN of the user. Once so +authorized, the CGI makes changes to the LDAP entry of the user, and +as far as the slapd server can tell for its ACLs, it is the user +themself on the other end of the connection. The user could have +connected to the LDAP server directly and authenticated as themself, +but that would require the user to have more knowledge of LDAP clients, +knowledge which the web page provides in an easier format. + + Authorization can also be used to limit access to an account that +has greater access to the database. Such an account, perhaps even the +root DN specified in {{slapd.conf}}(5), can have a strict list of +people who can authorize to that DN. Changes to the LDAP database +could then be only allowed by that DN, and in order to 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}} {{slapd.conf}}(5) +directive or through a {{EX:userPassword}} attribute, then auditing +becomes more difficult. + + Note that after a successful authorization, the original +authentication DN in the LDAP connection is overwritten by the new DN +from the authorization request. If a service program is able to +authenticate itself as its own authentication DN and then authorize to +other DN's, and it is planning on switching to several different +identities during one LDAP session, it will need to authenticate itself +each time before authorizing to another DN. The slapd server does not +keep record of the service program's ability to switch to other DN's. +On authentication mechanisms like Kerberos this will not require +multiple connections being made to the Kerberos server, since the +user's TGT and "ldap" session key are valid for multiple uses for the +several hours of the ticket lifetime. + + +H3: Authorization Identities + + The authorization identity is sent to the slapd server via the -X +switch for {{ldapsearch}}(1) and other tools, or in the *authzid +parameter to the {{lutil_sasl_defaults}}() call. The identity can +be in one of two forms, either + +> u: + +or + +> dn: + +In the first form, the 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. 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 + +> uid=,cn=,cn=authzid + +That authorization request DN is then run through the same {{EX:saslRegexp}} +process to convert it into a legitimate authorization DN from the +database. If it cannot be converted due to a failed search from an +LDAP URI, the authorization request fails with "inappropriate access". +Otherwise, the DN string is now a legitimate authorization DN ready to +undergo approval. + + If the authorization identity was provided in the second form, with +a "dn:" prefix, the string after the prefix is already in +authorization DN form, ready to undergo approval. + + +H3: Authorization rules + + Once slapd has the authorization DN, the actual approval process +begins. There are two attributes that the LDAP administrator can put +into LDAP entries to allow authorization: + +> saslAuthzTo +> saslAuthzFrom + +Both can be multivalued. The first is called a source rule, and it is +placed into a person's authentication DN entry to tell what other +authorization DN's the person is allowed to change to. The second form +is called a destination rule, and it is placed into an authorization +DN's entry to tell what authenticated DN a person must be coming from +in order to switch to that authorization DN. The choice of which form +to use is up to the administrator. Source rules are checked first in +the person's authentication DN entry, and if none of the saslAuthzTo +rules specify the authorization is permitted, the saslAuthzFrom rules +in the authorization DN entry are then checked. If neither case +specifies that the request be honored, the request is denied with an +"inappropriate access" message. Since the default behaviour is to deny +authorization requests, rules only specify that a request be allowed; +there are no negative rules telling what authorizations to deny. + + The value(s) in the two attributes are of the same form as the +output of the replacement pattern of a {{EX:saslRegexp}} directive: +either a DN or an LDAP URI. For example, if a saslAuthzTo value is a +DN, that DN is one the authenticated user can authorize to. On the +other hand, if the saslAuthzTo value is an LDAP URI, the URI is used +as an internal search of the LDAP database, and the authenticated user +can become ANY DN returned by the search. If an LDAP entry looked +like: + +> dn: cn=WebUpdate,dc=example,dc=com +> saslAuthzTo: ldap://host/dc=example,dc=com??sub?objectclass=Person + +then any user who authenticated as cn=WebUpdate,dc=example,dc=com +could authorize to any other LDAP entry under the search base +"dc=example,dc=com" which has an objectClass of "Person". + + +H4: Notes on Authorization rules + + An LDAP URI in a saslAuthzTo or saslAuthzFrom attribute will return +a list of DN's, and that list must be linearly scanned. Searches +which return a long list can cause the authorization process to take +an uncomfortably long time. Also, searches should be performed on +attributes that have been indexed by slapd. + + To help produce more sweeping rules for saslAuthzFrom and +saslAuthzTo, the values of these attributes are allowed to be DN's +with regular expression characters in them. This means a source rule +like + +> saslAuthzTo: 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 +comparison can be evaluated much faster than an LDAP search for "uid=*". + + Also note that the values in an authorization rule must be one of the +two forms: an LDAP URI or a DN (with or without regular expression +characters). Anything that does not begin with "ldap://" is taken as a +DN. It is not permissable to enter another authorization identity of +the form "u:" as an authorization rule. + + The decision of which type of rules to use, saslAuthzFrom or +saslAuthzTo, will depend on the site's situation. For example, if the +set of people who may become a given identity can easily be written as +a search filter, then a single destination rule could be written. If +the set of people is not easily defined by a search filter, and the +set of people is small, it may be better to write a source rule in the +entries of each of those people who should be allowed to perform the +authorization. -- 2.39.5