1# $OpenLDAP$ 2# Copyright 1999-2011 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Using SASL 6 7OpenLDAP clients and servers are capable of authenticating via the 8{{TERM[expand]SASL}} ({{TERM:SASL}}) framework, which is detailed 9in {{REF:RFC4422}}. This chapter describes how to make use of 10SASL in OpenLDAP. 11 12There are several industry standard authentication mechanisms that 13can be used with SASL, including {{TERM:GSSAPI}} for {{TERM:Kerberos}} 14V, {{TERM:DIGEST-MD5}}, and {{TERM:PLAIN}} and {{TERM:EXTERNAL}} 15for use with {{TERM[expand]TLS}} (TLS). 16 17The standard client tools provided with OpenLDAP Software, such as 18{{ldapsearch}}(1) and {{ldapmodify}}(1), will by default attempt 19to authenticate the user to the {{TERM:LDAP}} directory server using 20SASL. Basic authentication service can be set up by the LDAP 21administrator with a few steps, allowing users to be authenticated 22to the slapd server as their LDAP entry. With a few extra steps, 23some users and services can be allowed to exploit SASL's proxy 24authorization feature, allowing them to authenticate themselves and 25then switch their identity to that of another user or service. 26 27This chapter assumes you have read {{Cyrus SASL for System 28Administrators}}, provided with the {{PRD:Cyrus SASL}} 29package (in {{FILE:doc/sysadmin.html}}) and have a working Cyrus 30SASL installation. You should use the Cyrus SASL {{EX:sample_client}} 31and {{EX:sample_server}} to test your SASL installation before 32attempting to make use of it with OpenLDAP Software. 33 34Note that in the following text the term {{user}} is used to describe 35a person or application entity who is connecting to the LDAP server 36via an LDAP client, such as {{ldapsearch}}(1). That is, the term 37{{user}} not only applies to both an individual using an LDAP client, 38but to an application entity which issues LDAP client operations 39without direct user control. For example, an e-mail server which 40uses LDAP operations to access information held in an LDAP server 41is an application entity. 42 43 44H2: SASL Security Considerations 45 46SASL offers many different authentication mechanisms. This section 47briefly outlines security considerations. 48 49Some mechanisms, such as PLAIN and LOGIN, offer no greater security 50over LDAP {{simple}} authentication. Like LDAP {{simple}} 51authentication, such mechanisms should not be used unless you have 52adequate security protections in place. It is recommended that 53these mechanisms be used only in conjunction with {{TERM[expand]TLS}} 54(TLS). Use of PLAIN and LOGIN are not discussed further in this 55document. 56 57The DIGEST-MD5 mechanism is the mandatory-to-implement authentication 58mechanism for LDAPv3. Though DIGEST-MD5 is not a strong authentication 59mechanism in comparison with trusted third party authentication 60systems (such as {{TERM:Kerberos}} or public key systems), it does 61offer significant protections against a number of attacks. Unlike 62the {{TERM:CRAM-MD5}} mechanism, it prevents chosen plaintext 63attacks. DIGEST-MD5 is favored over the use of plaintext password 64mechanisms. The CRAM-MD5 mechanism is deprecated in favor of 65DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below. 66 67The GSSAPI mechanism utilizes {{TERM:GSS-API}} {{TERM:Kerberos}} V 68to provide secure authentication services. The KERBEROS_V4 mechanism 69is available for those using Kerberos IV. Kerberos is viewed as a 70secure, distributed authentication system suitable for both small 71and large enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}} 72are discussed below. 73 74The EXTERNAL mechanism utilizes authentication services provided 75by lower level network services such as {{TERM[expand]TLS}} ({{TERM:TLS}}). When 76used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public 77key technology, EXTERNAL offers strong authentication. 78TLS is discussed in the {{SECT:Using TLS}} chapter. 79 80EXTERNAL can also be used with the {{EX:ldapi:///}} transport, as 81Unix-domain sockets can report the UID and GID of the client process. 82 83There are other strong authentication mechanisms to choose from, 84including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure 85remote passwords). These mechanisms are not discussed in this 86document. 87 88 89H2: SASL Authentication 90 91Getting basic SASL authentication running involves a few steps. 92The first step configures your slapd server environment so that it 93can communicate with client programs using the security system in 94place at your site. This usually involves setting up a service key, 95a public key, or other form of secret. The second step concerns 96mapping authentication identities to LDAP {{TERM:DN}}'s, which 97depends on how entries are laid out in your directory. An explanation 98of the first step will be given in the next section using Kerberos 99V4 as an example mechanism. The steps necessary for your site's 100authentication mechanism will be similar, but a guide to every 101mechanism available under SASL is beyond the scope of this chapter. 102The second step is described in the section {{SECT:Mapping 103Authentication Identities}}. 104 105 106H3: GSSAPI 107 108This section describes the use of the SASL GSSAPI mechanism and 109Kerberos V with OpenLDAP. It will be assumed that you have Kerberos 110V deployed, you are familiar with the operation of the system, and 111that your users are trained in its use. This section also assumes 112you have familiarized yourself with the use of the GSSAPI mechanism 113by reading {{Configuring GSSAPI and Cyrus SASL}} (provided with 114Cyrus SASL in the {{FILE:doc/gssapi}} file) and successfully 115experimented with the Cyrus provided {{EX:sample_server}} and 116{{EX:sample_client}} applications. General information about 117Kerberos is available at {{URL:http://web.mit.edu/kerberos/www/}}. 118 119To use the GSSAPI mechanism with {{slapd}}(8) one must create a service 120key with a principal for {{ldap}} service within the realm for the host 121on which the service runs. For example, if you run {{slapd}} on 122{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}}, 123you need to create a service key with the principal: 124 125> ldap/directory.example.com@EXAMPLE.COM 126 127When {{slapd}}(8) runs, it must have access to this key. This is 128generally done by placing the key into a keytab file, 129{{FILE:/etc/krb5.keytab}}. See your Kerberos and Cyrus SASL 130documentation for information regarding keytab location settings. 131 132To use the GSSAPI mechanism to authenticate to the directory, the 133user obtains a Ticket Granting Ticket (TGT) prior to running the 134LDAP client. When using OpenLDAP client tools, the user may mandate 135use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a 136command option. 137 138For the purposes of authentication and authorization, {{slapd}}(8) 139associates an authentication request DN of the form: 140 141> uid=<primary[/instance]>,cn=<realm>,cn=gssapi,cn=auth 142 143Continuing our example, a user with the Kerberos principal 144{{EX:kurt@EXAMPLE.COM}} would have the associated DN: 145 146> uid=kurt,cn=example.com,cn=gssapi,cn=auth 147 148and the principal {{EX:ursula/admin@FOREIGN.REALM}} would have the 149associated DN: 150 151> uid=ursula/admin,cn=foreign.realm,cn=gssapi,cn=auth 152 153 154The authentication request DN can be used directly ACLs and 155{{EX:groupOfNames}} "member" attributes, since it is of legitimate 156LDAP DN format. Or alternatively, the authentication DN could be 157mapped before use. See the section {{SECT:Mapping Authentication 158Identities}} for details. 159 160 161H3: KERBEROS_V4 162 163This section describes the use of the SASL KERBEROS_V4 mechanism 164with OpenLDAP. It will be assumed that you are familiar with the 165workings of the Kerberos IV security system, and that your site has 166Kerberos IV deployed. Your users should be familiar with 167authentication policy, how to receive credentials in 168a Kerberos ticket cache, and how to refresh expired credentials. 169 170Note: KERBEROS_V4 and Kerberos IV are deprecated in favor of GSSAPI 171and Kerberos V. 172 173Client programs will need to be able to obtain a session key for 174use when connecting to your LDAP server. This allows the LDAP server 175to know the identity of the user, and allows the client to know it 176is connecting to a legitimate server. If encryption layers are to 177be used, the session key can also be used to help negotiate that 178option. 179 180The slapd server runs the service called "{{ldap}}", and the server 181will require a srvtab file with a service key. SASL aware client 182programs will be obtaining an "ldap" service ticket with the user's 183ticket granting ticket (TGT), with the instance of the ticket 184matching the hostname of the OpenLDAP server. For example, if your 185realm is named {{EX:EXAMPLE.COM}} and the slapd server is running 186on the host named {{EX:directory.example.com}}, the {{FILE:/etc/srvtab}} 187file on the server will have a service key 188 189> ldap.directory@EXAMPLE.COM 190 191When an LDAP client is authenticating a user to the directory using 192the KERBEROS_IV mechanism, it will request a session key for that 193same principal, either from the ticket cache or by obtaining a new 194one from the Kerberos server. This will require the TGT to be 195available and valid in the cache as well. If it is not present or 196has expired, the client may print out the message: 197 198> ldap_sasl_interactive_bind_s: Local error 199 200When the service ticket is obtained, it will be passed to the LDAP 201server as proof of the user's identity. The server will extract 202the identity and realm out of the service ticket using SASL 203library calls, and convert them into an {{authentication request 204DN}} of the form 205 206> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth 207 208So in our above example, if the user's name were "adamson", the 209authentication request DN would be: 210 211> uid=adamsom,cn=example.com,cn=kerberos_v4,cn=auth 212 213This authentication request DN can be used directly ACLs or, 214alternatively, mapped prior to use. See the section {{SECT:Mapping 215Authentication Identities}} for details. 216 217 218H3: DIGEST-MD5 219 220This section describes the use of the SASL DIGEST-MD5 mechanism 221using secrets stored either in the directory itself or in Cyrus 222SASL's own database. DIGEST-MD5 relies on the client and the server 223sharing a "secret", usually a password. The server generates a 224challenge and the client a response proving that it knows the shared 225secret. This is much more secure than simply sending the secret 226over the wire. 227 228Cyrus SASL supports several shared-secret mechanisms. To do this, 229it needs access to the plaintext password (unlike mechanisms which 230pass plaintext passwords over the wire, where the server can store 231a hashed version of the password). 232 233The server's copy of the shared-secret may be stored in Cyrus SASL's 234own {{sasldb}} database, in an external system accessed via 235{{saslauthd}}, or in LDAP database itself. In either case it is 236very important to apply file access controls and LDAP access controls 237to prevent exposure of the passwords. The configuration and commands 238discussed in this section assume the use of Cyrus SASL 2.1. 239 240To use secrets stored in {{sasldb}}, simply add users with the 241{{saslpasswd2}} command: 242 243> saslpasswd2 -c <username> 244 245The passwords for such users must be managed with the {{saslpasswd2}} 246command. 247 248To use secrets stored in the LDAP directory, place plaintext passwords 249in the {{EX:userPassword}} attribute. It will be necessary to add 250an option to {{EX:slapd.conf}} to make sure that passwords set using 251the LDAP Password Modify Operation are stored in plaintext: 252 253> password-hash {CLEARTEXT} 254 255Passwords stored in this way can be managed either with {{ldappasswd}}(1) 256or by simply modifying the {{EX:userPassword}} attribute. Regardless of 257where the passwords are stored, a mapping will be needed from 258authentication request DN to user's DN. 259 260The DIGEST-MD5 mechanism produces authentication IDs of the form: 261 262> uid=<username>,cn=<realm>,cn=digest-md5,cn=auth 263 264If the default realm is used, the realm name is omitted from the ID, 265giving: 266 267> uid=<username>,cn=digest-md5,cn=auth 268 269See {{SECT: Mapping Authentication Identities}} below for information 270on optional mapping of identities. 271 272With suitable mappings in place, users can specify SASL IDs when 273performing LDAP operations, and the password stored in {{sasldb}} or in 274the directory itself will be used to verify the authentication. 275For example, the user identified by the directory entry: 276 277> dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com 278> objectclass: inetOrgPerson 279> objectclass: person 280> sn: Findlay 281> uid: u000997 282> userPassword: secret 283 284can issue commands of the form: 285 286> ldapsearch -Y DIGEST-MD5 -U u000997 ... 287 288Note: in each of the above cases, no authorization identity (e.g. 289{{EX:-X}}) was provided. Unless you are attempting {{SECT:SASL 290Proxy Authorization}}, no authorization identity should be specified. 291The server will infer an authorization identity from authentication 292identity (as described below). 293 294 295H3: EXTERNAL 296 297The SASL EXTERNAL mechanism makes use of an authentication performed 298by a lower-level protocol: usually {{TERM:TLS}} or Unix {{TERM:IPC}} 299 300Each transport protocol returns Authentication Identities in its own 301format: 302 303H4: TLS Authentication Identity Format 304 305This is the Subject DN from the client-side certificate. 306Note that DNs are displayed differently by LDAP and by X.509, so 307a certificate issued to 308> C=gb, O=The Example Organisation, CN=A Person 309 310will produce an authentication identity of: 311 312> cn=A Person,o=The Example Organisation,c=gb 313 314Note that you must set a suitable value for TLSVerifyClient to make the server 315request the use of a client-side certificate. Without this, the SASL EXTERNAL 316mechanism will not be offered. 317Refer to the {{SECT:Using TLS}} chapter for details. 318 319H4: IPC (ldapi:///) Identity Format 320 321This is formed from the Unix UID and GID of the client process: 322 323> gidNumber=<number>+uidNumber=<number>,cn=peercred,cn=external,cn=auth 324 325Thus, a client process running as {{EX:root}} will be: 326 327> gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth 328 329 330H3: Mapping Authentication Identities 331 332The authentication mechanism in the slapd server will use SASL 333library calls to obtain the authenticated user's "username", based 334on whatever underlying authentication mechanism was used. This 335username is in the namespace of the authentication mechanism, and 336not in the normal LDAP namespace. As stated in the sections above, 337that username is reformatted into an authentication request DN of 338the form 339 340> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth 341 342or 343 344> uid=<username>,cn=<mechanism>,cn=auth 345 346depending on whether or not <mechanism> employs the concept of 347"realms". Note also that the realm part will be omitted if the 348default realm was used in the authentication. 349 350The {{ldapwhoami}}(1) command may be used to determine the identity 351associated with the user. It is very useful for determining proper 352function of mappings. 353 354It is not intended that you should add LDAP entries of the above 355form to your LDAP database. Chances are you have an LDAP entry for 356each of the persons that will be authenticating to LDAP, laid out 357in your directory tree, and the tree does not start at cn=auth. 358But if your site has a clear mapping between the "username" and an 359LDAP entry for the person, you will be able to configure your LDAP 360server to automatically map a authentication request DN to the 361user's {{authentication DN}}. 362 363Note: it is not required that the authentication request DN nor the 364user's authentication DN resulting from the mapping refer to an 365entry held in the directory. However, additional capabilities 366become available (see below). 367 368The LDAP administrator will need to tell the slapd server how to 369map an authentication request DN to a user's authentication DN. 370This is done by adding one or more {{EX:authz-regexp}} directives to 371the {{slapd.conf}}(5) file. This directive takes two arguments: 372 373> authz-regexp <search pattern> <replacement pattern> 374 375The authentication request DN is compared to the search pattern 376using the regular expression functions {{regcomp}}() and {{regexec}}(), 377and if it matches, it is rewritten as the replacement pattern. If 378there are multiple {{EX:authz-regexp}} directives, only the first 379whose search pattern matches the authentication identity is used. 380The string that is output from the replacement pattern should be 381the authentication DN of the user or an LDAP URL. If replacement 382string produces a DN, the entry named by this DN need not be held 383by this server. If the replace string produces an LDAP URL, that 384LDAP URL must evaluate to one and only one entry held by this server. 385 386The search pattern can contain any of the regular expression 387characters listed in {{regexec}}(3C). The main characters of note 388are dot ".", asterisk "*", and the open and close parenthesis "(" 389and ")". Essentially, the dot matches any character, the asterisk 390allows zero or more repeats of the immediately preceding character 391or pattern, and terms in parenthesis are remembered for the replacement 392pattern. 393 394The replacement pattern will produce either a DN or URL referring 395to the user. Anything from the authentication request DN that 396matched a string in parenthesis in the search pattern is stored in 397the variable "$1". That variable "$1" can appear in the replacement 398pattern, and will be replaced by the string from the authentication 399request DN. If there were multiple sets of parentheses in the search 400pattern, the variables $2, $3, etc are used. 401 402H3: Direct Mapping 403 404Where possible, direct mapping of the authentication request DN to 405the user's DN is generally recommended. Aside from avoiding the 406expense of searching for the user's DN, it allows mapping to 407DNs which refer to entries not held by this server. 408 409Suppose the authentication request DN is written as: 410 411> uid=adamson,cn=example.com,cn=gssapi,cn=auth 412 413and the user's actual LDAP entry is: 414 415> uid=adamson,ou=people,dc=example,dc=com 416 417then the following {{EX:authz-regexp}} directive in {{slapd.conf}}(5) 418would provide for direct mapping. 419 420> authz-regexp 421> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth 422> uid=$1,ou=people,dc=example,dc=com 423 424An even more lenient rule could be written as 425 426> authz-regexp 427> uid=([^,]*),cn=[^,]*,cn=auth 428> uid=$1,ou=people,dc=example,dc=com 429 430Be careful about setting the search pattern too leniently, however, 431since it may mistakenly allow persons to become authenticated as a 432DN to which they should not have access. It is better to write 433several strict directives than one lenient directive which has 434security holes. If there is only one authentication mechanism in 435place at your site, and zero or one realms in use, you might be 436able to map between authentication identities and LDAP DN's with a 437single {{EX:authz-regexp}} directive. 438 439Don't forget to allow for the case where the realm is omitted as 440well as the case with an explicitly specified realm. This may well 441require a separate {{EX:authz-regexp}} directive for each case, with 442the explicit-realm entry being listed first. 443 444H3: Search-based mappings 445 446There are a number of cases where mapping to a LDAP URL may be 447appropriate. For instance, some sites may have person objects 448located in multiple areas of the LDAP tree, such as if there were 449an {{EX:ou=accounting}} tree and an {{EX:ou=engineering}} tree, 450with persons interspersed between them. Or, maybe the desired 451mapping must be based upon information in the user's information. 452Consider the need to map the above authentication request DN to 453user whose entry is as follows: 454 455> dn: cn=Mark Adamson,ou=People,dc=Example,dc=COM 456> objectclass: person 457> cn: Mark Adamson 458> uid: adamson 459 460The information in the authentication request DN is insufficient 461to allow the user's DN to be directly derived, instead the user's 462DN must be searched for. For these situations, a replacement pattern 463which produces a LDAP URL can be used in the {{EX:authz-regexp}} 464directives. This URL will then be used to perform an internal 465search of the LDAP database to find the person's authentication DN. 466 467An LDAP URL, similar to other URL's, is of the form 468 469> ldap://<host>/<base>?<attrs>?<scope>?<filter> 470 471This contains all of the elements necessary to perform an LDAP 472search: the name of the server <host>, the LDAP DN search base 473<base>, the LDAP attributes to retrieve <attrs>, the search scope 474<scope> which is one of the three options "base", "one", or "sub", 475and lastly an LDAP search filter <filter>. Since the search is for 476an LDAP DN within the current server, the <host> portion should be 477empty. The <attrs> field is also ignored since only the DN is of 478concern. These two elements are left in the format of the URL to 479maintain the clarity of what information goes where in the string. 480 481Suppose that the person in the example from above did in fact have 482an authentication username of "adamson" and that information was 483kept in the attribute "uid" in their LDAP entry. The {{EX:authz-regexp}} 484directive might be written as 485 486> authz-regexp 487> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth 488> ldap:///ou=people,dc=example,dc=com??one?(uid=$1) 489 490This will initiate an internal search of the LDAP database inside 491the slapd server. If the search returns exactly one entry, it is 492accepted as being the DN of the user. If there are more than one 493entries returned, or if there are zero entries returned, the 494authentication fails and the user's connection is left bound as the 495authentication request DN. 496 497The attributes that are used in the search filter <filter> in the 498URL should be indexed to allow faster searching. If they are not, 499the authentication step alone can take uncomfortably long periods, 500and users may assume the server is down. 501 502A more complex site might have several realms in use, each mapping 503to a different subtree in the directory. These can be handled with 504statements of the form: 505 506> # Match Engineering realm 507> authz-regexp 508> uid=([^,]*),cn=engineering.example.com,cn=digest-md5,cn=auth 509> ldap:///dc=eng,dc=example,dc=com??one?(&(uid=$1)(objectClass=person)) 510> 511> # Match Accounting realm 512> authz-regexp 513> uid=([^,].*),cn=accounting.example.com,cn=digest-md5,cn=auth 514> ldap:///dc=accounting,dc=example,dc=com??one?(&(uid=$1)(objectClass=person)) 515> 516> # Default realm is customers.example.com 517> authz-regexp 518> uid=([^,]*),cn=digest-md5,cn=auth 519> ldap:///dc=customers,dc=example,dc=com??one?(&(uid=$1)(objectClass=person)) 520 521Note that the explicitly-named realms are handled first, to avoid 522the realm name becoming part of the UID. Also note the use of scope 523and filters to limit matching to desirable entries. 524 525Note as well that {{EX:authz-regexp}} internal search are subject 526to access controls. Specifically, the authentication identity 527must have {{EX:auth}} access. 528 529See {{slapd.conf}}(5) for more detailed information. 530 531 532H2: SASL Proxy Authorization 533 534The SASL offers a feature known as {{proxy authorization}}, which 535allows an authenticated user to request that they act on the behalf 536of another user. This step occurs after the user has obtained an 537authentication DN, and involves sending an authorization identity 538to the server. The server will then make a decision on whether or 539not to allow the authorization to occur. If it is allowed, the 540user's LDAP connection is switched to have a binding DN derived 541from the authorization identity, and the LDAP session proceeds with 542the access of the new authorization DN. 543 544The decision to allow an authorization to proceed depends on the 545rules and policies of the site where LDAP is running, and thus 546cannot be made by SASL alone. The SASL library leaves it up to the 547server to make the decision. The LDAP administrator sets the 548guidelines of who can authorize to what identity by adding information 549into the LDAP database entries. By default, the authorization 550features are disabled, and must be explicitly configured by the 551LDAP administrator before use. 552 553 554H3: Uses of Proxy Authorization 555 556This sort of service is useful when one entity needs to act on the 557behalf of many other users. For example, users may be directed to 558a web page to make changes to their personal information in their 559LDAP entry. The users authenticate to the web server to establish 560their identity, but the web server CGI cannot authenticate to the 561LDAP server as that user to make changes for them. Instead, the 562web server authenticates itself to the LDAP server as a service 563identity, say, 564 565> cn=WebUpdate,dc=example,dc=com 566 567and then it will SASL authorize to the DN of the user. Once so 568authorized, the CGI makes changes to the LDAP entry of the user, 569and as far as the slapd server can tell for its ACLs, it is the 570user themself on the other end of the connection. The user could 571have connected to the LDAP server directly and authenticated as 572themself, but that would require the user to have more knowledge 573of LDAP clients, knowledge which the web page provides in an easier 574format. 575 576Proxy authorization can also be used to limit access to an account 577that has greater access to the database. Such an account, perhaps 578even the root DN specified in {{slapd.conf}}(5), can have a strict 579list of people who can authorize to that DN. Changes to the LDAP 580database could then be only allowed by that DN, and in order to 581become that DN, users must first authenticate as one of the persons 582on the list. This allows for better auditing of who made changes 583to the LDAP database. If people were allowed to authenticate 584directly to the privileged account, possibly through the {{EX:rootpw}} 585{{slapd.conf}}(5) directive or through a {{EX:userPassword}} 586attribute, then auditing becomes more difficult. 587 588Note that after a successful proxy authorization, the original 589authentication DN of the LDAP connection is overwritten by the new 590DN from the authorization request. If a service program is able to 591authenticate itself as its own authentication DN and then authorize 592to other DN's, and it is planning on switching to several different 593identities during one LDAP session, it will need to authenticate 594itself each time before authorizing to another DN (or use a different 595proxy authorization mechanism). The slapd server does not keep 596record of the service program's ability to switch to other DN's. 597On authentication mechanisms like Kerberos this will not require 598multiple connections being made to the Kerberos server, since the 599user's TGT and "ldap" session key are valid for multiple uses for 600the several hours of the ticket lifetime. 601 602 603H3: SASL Authorization Identities 604 605The SASL authorization identity is sent to the LDAP server via the 606{{EX:-X}} switch for {{ldapsearch}}(1) and other tools, or in the 607{{EX:*authzid}} parameter to the {{lutil_sasl_defaults}}() call. 608The identity can be in one of two forms, either 609 610> u:<username> 611 612or 613 614> dn:<dn> 615 616In the first form, the <username> is from the same namespace as 617the authentication identities above. It is the user's username as 618it is referred to by the underlying authentication mechanism. 619Authorization identities of this form are converted into a DN format 620by the same function that the authentication process used, producing 621an {{authorization request DN}} of the form 622 623> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth 624 625That authorization request DN is then run through the same 626{{EX:authz-regexp}} process to convert it into a legitimate authorization 627DN from the database. If it cannot be converted due to a failed 628search from an LDAP URL, the authorization request fails with 629"inappropriate access". Otherwise, the DN string is now a legitimate 630authorization DN ready to undergo approval. 631 632If the authorization identity was provided in the second form, with 633a {{EX:"dn:"}} prefix, the string after the prefix is already in 634authorization DN form, ready to undergo approval. 635 636 637H3: Proxy Authorization Rules 638 639Once slapd has the authorization DN, the actual approval process 640begins. There are two attributes that the LDAP administrator can 641put into LDAP entries to allow authorization: 642 643> authzTo 644> authzFrom 645 646Both can be multivalued. The {{EX:authzTo}} attribute is a 647source rule, and it is placed into the entry associated with the 648authentication DN to tell what authorization DNs the authenticated 649DN is allowed to assume. The second attribute is a destination 650rule, and it is placed into the entry associated with the requested 651authorization DN to tell which authenticated DNs may assume it. 652 653The choice of which authorization policy attribute to use is up to 654the administrator. Source rules are checked first in the person's 655authentication DN entry, and if none of the {{EX:authzTo}} rules 656specify the authorization is permitted, the {{EX:authzFrom}} 657rules in the authorization DN entry are then checked. If neither 658case specifies that the request be honored, the request is denied. 659Since the default behavior is to deny authorization requests, rules 660only specify that a request be allowed; there are no negative rules 661telling what authorizations to deny. 662 663The value(s) in the two attributes are of the same form as the 664output of the replacement pattern of a {{EX:authz-regexp}} directive: 665either a DN or an LDAP URL. For example, if a {{EX:authzTo}} 666value is a DN, that DN is one the authenticated user can authorize 667to. On the other hand, if the {{EX:authzTo}} value is an LDAP 668URL, the URL is used as an internal search of the LDAP database, 669and the authenticated user can become ANY DN returned by the search. 670If an LDAP entry looked like: 671 672> dn: cn=WebUpdate,dc=example,dc=com 673> authzTo: ldap:///dc=example,dc=com??sub?(objectclass=person) 674 675then any user who authenticated as {{EX:cn=WebUpdate,dc=example,dc=com}} 676could authorize to any other LDAP entry under the search base 677{{EX:dc=example,dc=com}} which has an objectClass of {{EX:Person}}. 678 679 680H4: Notes on Proxy Authorization Rules 681 682An LDAP URL in a {{EX:authzTo}} or {{EX:authzFrom}} attribute 683will return a set of DNs. Each DN returned will be checked. Searches 684which return a large set can cause the authorization process to 685take an uncomfortably long time. Also, searches should be performed 686on attributes that have been indexed by slapd. 687 688To help produce more sweeping rules for {{EX:authzFrom}} and 689{{EX:authzTo}}, the values of these attributes are allowed to 690be DNs with regular expression characters in them. This means a 691source rule like 692 693> authzTo: dn.regex:^uid=[^,]*,dc=example,dc=com$ 694 695would allow that authenticated user to authorize to any DN that 696matches the regular expression pattern given. This regular expression 697comparison can be evaluated much faster than an LDAP search for 698{{EX:(uid=*)}}. 699 700Also note that the values in an authorization rule must be one of 701the two forms: an LDAP URL or a DN (with or without regular expression 702characters). Anything that does not begin with "{{EX:ldap://}}" is 703taken as a DN. It is not permissible to enter another authorization 704identity of the form "{{EX:u:<username>}}" as an authorization rule. 705 706 707H4: Policy Configuration 708 709The decision of which type of rules to use, {{EX:authzFrom}} 710or {{EX:authzTo}}, will depend on the site's situation. For 711example, if the set of people who may become a given identity can 712easily be written as a search filter, then a single destination 713rule could be written. If the set of people is not easily defined 714by a search filter, and the set of people is small, it may be better 715to write a source rule in the entries of each of those people who 716should be allowed to perform the proxy authorization. 717 718By default, processing of proxy authorization rules is disabled. 719The {{EX:authz-policy}} directive must be set in the 720{{slapd.conf}}(5) file to enable authorization. This directive can 721be set to {{EX:none}} for no rules (the default), {{EX:to}} for 722source rules, {{EX:from}} for destination rules, or {{EX:both}} for 723both source and destination rules. 724 725Source rules are extremely powerful. If ordinary users have 726access to write the {{EX:authzTo}} attribute in their own 727entries, then they can write rules that would allow them to authorize 728as anyone else. As such, when using source rules, the 729{{EX:authzTo}} attribute should be protected with an ACL that 730only allows privileged users to set its values. 731 732