3 Application Working Group M. Ansari
4 INTERNET-DRAFT Infoblox
5 Expires January 2005 L. Howard
6 PADL Software Pty. Ltd.
8 Hewlett-Packard Company
11 Intended Category: Informational
14 A Configuration Schema for LDAP Based
16 <draft-joslin-config-schema-08.txt>
21 This memo provides information for the Internet community. This
22 memo does not specify an Internet standard of any kind. Distribu-
23 tion of this memo is unlimited.
25 This document is an Internet-Draft and is in full conformance with
26 all provisions of Section 10 of RFC2026.
28 This document is an Internet-Draft. Internet-Drafts are working
29 documents of the Internet Engineering Task Force (IETF), its areas,
30 and its working groups. Note that other groups may also distribute
31 working documents as Internet-Drafts.
33 Internet-Drafts are draft documents valid for a maximum of six
34 months. Internet-Drafts may be updated, replaced, or made obsolete
35 by other documents at any time. It is not appropriate to use
36 Internet-Drafts as reference material or to cite them other than as
37 a "working draft" or "work in progress".
39 To learn the current status of any Internet-Draft, please check the
40 1id-abstracts.txt listing contained in the Internet-Drafts Shadow
41 Directories on ds.internic.net (US East Coast), nic.nordu.net
42 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
45 Distribution of this document is unlimited.
49 This document describes a mechanism for global configuration of
50 similar directory user agents. This document defines a schema for
56 Internet-Draft DUA Configuration Schema October 2002
59 configuration of these DUAs that may be discovered using the Light-
60 weight Directory Access Protocol in RFC 2251[17]. A set of attri-
61 bute types and an objectclass are proposed, along with specific
62 guidelines for interpreting them. A significant feature of the
63 global configuration policy for DUAs is a mechanism that allows
64 DUAs to re-configure their schema to that of the end user's
65 environment. This configuration is achieved through attribute and
66 objectclass mapping. This document is intended to be a skeleton
67 for future documents that describe configuration of specific DUA
71 1. Background & Motivation
73 The LDAP protocol has brought about a new and nearly ubiquitous
74 acceptance of the directory server. Many new client applications
75 (DUAs) are being created that use LDAP directories for many dif-
76 ferent services. And although the LDAP protocol has eased the
77 development of these applications, some challenges still exist for
78 both developers and directory administrators.
80 The authors of this document are implementers of DUAs described by
81 RFC 2307 [14]. In developing these agents, we felt there are
82 several issues that still need to be addressed to ease the deploy-
83 ment and configuration of a large network of these DUAs.
85 One of these challenges stems from the lack of a utopian schema. A
86 utopian schema would be one that every application developer could
87 agree upon and that would support every application. Unfortunately
88 today, many DUAs define their own schema (like RFC 2307 vs.
89 Microsoft's Services for Unix [13]) containing similar attributes,
90 but with different attribute names. This can lead to data redun-
91 dancy within directory entries and give directory administrators
92 unwanted challenges, updating schemas and synchronizing data.
94 So, one goal of this document is to eliminate data redundancy by
95 having DUAs configure themselves to the schema of the deployed
96 directory, instead of forcing it's own schema on the directory.
98 Another goal of this document is to provide the DUA with enough
99 configuration information so that it can discover how to retrieve
100 its data in the directory, such as what locations to search in the
103 Finally, this document intends to describe a configuration method
104 for DUAs that can be shared among many DUAs, on various platforms,
105 providing as such, a configuration profile, the purpose is to cen-
106 tralize and simplify management of DUAs.
112 Internet-Draft DUA Configuration Schema October 2002
115 This document is intended to provide the skeleton framework for
116 future drafts, which will describe the individual implementation
117 details for the particular services provided by that DUA. The
118 authors of this document plan to develop such a document for the
119 Network Information Service DUA, described by RFC 2307 or its suc-
122 We expect that as DUAs take advantage of this configuration scheme,
123 each DUA will require additional configuration parameters, not
124 specified by this document. Thus, we would expect that new auxili-
125 ary object classes, containing new configuration attributes will be
126 created, and then joined with the structural class defined by this
127 document to create a configuration profile for a particular DUA
128 service. And that by joining various auxiliary objectclasses for
129 different DUA services, that configuration of various DUA services
130 can be controlled by a single configuration profile entry.
135 The schema defined by this document is defined under the "DUA Con-
136 figuration Schema." This schema is derived from the OID: iso (1)
137 org (3) dod (6) internet (1) private (4) enterprises (1) Hewlett-
138 Packard Company (11) directory (1) LDAP-UX Integration Project (3)
139 DUA Configuration Schema (1). This OID is represented in this
140 document by the keystring "DUAConfSchemaOID"
141 (1.3.6.1.4.1.11.1.3.1).
145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
147 this document are to be interpreted as described in RFC 2119 [15].
151 The attributes and classes defined in this document are summarized
154 The following attributes are defined in this document:
162 serviceSearchDescriptor
168 Internet-Draft DUA Configuration Schema October 2002
171 serviceCredentialLevel
172 serviceAuthenticationMethod
183 The following object class is defined in this document:
187 2.4 Syntax Definitions
189 The following syntax definitions are used throughout this document.
190 This document does not define new syntaxes that must be supported
191 by the directory server. The string encoding used by the attri-
192 butes defined in this document can be found section 5.
194 keystring as defined by RFC 2252 [2]
195 descr as defined by RFC 2252 section 4.1
196 a as defined by RFC 2252 section 4.1
197 d as defined by RFC 2252 section 4.1
198 space as defined by RFC 2252 section 4.1
199 whsp as defined by RFC 2252 section 4.1
200 base as defined by RFC 2253 [3]
201 DistinguishedName as defined by RFC 2253 section 2
202 RelativeDistinguishedName as defined by RFC 2253 section 2
203 scope as defined by RFC 2255 [5]
204 IPv4address as defined by RFC 2396 [9]
205 hostport as defined by RFC 2396 section 3.2.2
206 port as defined by RFC 2396 section 3.2.2
207 ipv6reference as defined by RFC 2732 [10]
208 host as defined by RFC 2732 section 3
209 serviceID = keystring
212 3. Attribute Definitions
214 This section contains attribute definitions to be used by DUAs when
215 discovering their configuration.
217 ( DUAConfSchemaOID.1.0 NAME 'defaultServerList'
218 DESC 'Default LDAP server host address used by a DUA'
224 Internet-Draft DUA Configuration Schema October 2002
227 EQUALITY caseIgnoreMatch
228 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
231 ( DUAConfSchemaOID.1.1 NAME 'defaultSearchBase'
232 DESC 'Default LDAP base DN used by a DUA'
233 EQUALITY distinguishedNameMatch
234 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
237 ( DUAConfSchemaOID.1.2 NAME 'preferredServerList'
238 DESC 'Preferred LDAP server host addresses to be used by a
240 EQUALITY caseIgnoreMatch
241 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
244 ( DUAConfSchemaOID.1.3 NAME 'searchTimeLimit'
245 DESC 'Maximum time in seconds a DUA should allow for a
247 EQUALITY integerMatch
248 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
251 ( DUAConfSchemaOID.1.4 NAME 'bindTimeLimit'
252 DESC 'Maximum time in seconds a DUA should allow for the
253 bind operation to complete'
254 EQUALITY integerMatch
255 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
258 ( DUAConfSchemaOID.1.5 NAME 'followReferrals'
259 DESC 'Tells DUA if it should follow referrals
260 returned by a DSA search result'
261 EQUALITY booleanMatch
262 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
265 ( DUAConfSchemaOID.1.16 NAME 'dereferenceAliases'
266 DESC 'Tells DUA if it should dereference aliases'
267 EQUALITY booleanMatch
268 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
271 ( DUAConfSchemaOID.1.6 NAME 'authenticationMethod'
272 DESC 'A keystring which identifies the type of
273 authentication method used to contact the DSA'
274 EQUALITY caseIgnoreMatch
280 Internet-Draft DUA Configuration Schema October 2002
283 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
286 ( DUAConfSchemaOID.1.7 NAME 'profileTTL'
287 DESC 'Time to live, in seconds, before a client DUA
288 should re-read this configuration profile'
289 EQUALITY integerMatch
290 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
293 ( DUAConfSchemaOID.1.14 NAME 'serviceSearchDescriptor'
294 DESC 'LDAP search descriptor list used by a DUA'
295 EQUALITY caseExactMatch
296 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
298 ( DUAConfSchemaOID.1.9 NAME 'attributeMap'
299 DESC 'Attribute mappings used by a DUA'
300 EQUALITY caseIgnoreIA5Match
301 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
303 ( DUAConfSchemaOID.1.10 NAME 'credentialLevel'
304 DESC 'Identifies type of credentials a DUA should
305 use when binding to the LDAP server'
306 EQUALITY caseIgnoreIA5Match
307 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
310 ( DUAConfSchemaOID.1.11 NAME 'objectclassMap'
311 DESC 'Objectclass mappings used by a DUA'
312 EQUALITY caseIgnoreIA5Match
313 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
315 ( DUAConfSchemaOID.1.12 NAME 'defaultSearchScope'
316 DESC 'Default search scope used by a DUA'
317 EQUALITY caseIgnoreIA5Match
318 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
321 ( DUAConfSchemaOID.1.13 NAME 'serviceCredentialLevel'
322 DESC 'Identifies type of credentials a DUA
323 should use when binding to the LDAP server for a
325 EQUALITY caseIgnoreIA5Match
326 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
328 ( DUAConfSchemaOID.1.15 NAME 'serviceAuthenticationMethod'
329 DESC 'Authentication method used by a service of the DUA'
330 EQUALITY caseIgnoreMatch
336 Internet-Draft DUA Configuration Schema October 2002
339 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
344 The objectclass below is constructed from the attributes defined in
345 3, with the exception of the cn attribute, which is defined in RFC
346 2256 [8]. cn is used to represent the name of the DUA configura-
349 ( DUAConfSchemaOID.2.5 NAME 'DUAConfigProfile'
351 DESC 'Abstraction of a base configuration for a DUA'
353 MAY ( defaultServerList $ preferredServerList $
354 defaultSearchBase $ defaultSearchScope $
355 searchTimeLimit $ bindTimeLimit $
356 credentialLevel $ authenticationMethod $
357 followReferrals $ dereferenceAliases $
358 serviceSearchDescriptor $ serviceCredentialLevel $
359 serviceAuthenticationMethod $ objectclassMap $
360 attributeMap $ profileTTL ) )
363 5. Implementation Details
365 5.1.1 Interpreting the preferredServerList attribute
369 As described by the syntax, the preferredServerList parameter
370 is a white-space separated list of server addresses and asso-
371 ciated port numbers. When the DUA needs to contact a DSA, the
372 DUA MUST first attempt to contact one of the servers listed in
373 the preferredServerList attribute. The DUA MUST contact the
374 DSA specified by the first server address in the list. If
375 that DSA is unavailable, the remaining DSAs MUST be queried in
376 the order provided until a connection is established with a
377 DSA. Once a connection with a DSA is established, the DUA
378 SHOULD NOT attempt to establish a connection with the remain-
381 If the DUA is unable to contact any of the DSAs specified by
382 the preferredServerList, the defaultServerList attribute MUST
383 be examined, as described in 5.1.2. The servers identified by
384 the preferredServerList MUST be contacted before attempting to
385 contact any of the servers specified by the defaultServerList.
392 Internet-Draft DUA Configuration Schema October 2002
397 serverList = host *(space [host])
401 The preferredServerList attribute does not have a default
402 value. Instead a DUA MUST examine the defaultServerList
405 Other attribute notes:
407 This attribute is used in conjunction with the defaultServer-
408 List attribute. Please see section 5.1.2 for additional
409 implementation notes. Determining how the DUA should query
410 the DSAs also depends on the additional configuration attri-
411 butes, credentialLevel, serviceCredentialLevel, bindTimeLimit,
412 serviceAuthenticationMethod and authenticationMethod. Please
413 review section 5.2 for details on how a Posix DUA should prop-
418 preferredServerList: 1.2.3.4 ldap1.mycorp.com ldap2:1389
419 [1080::8:800:200C:417A]:1389
421 5.1.2 Interpreting the defaultServerList attribute
425 The defaultServerList attribute MUST only be examined if the
426 preferredServerList attribute is not provided, or the DUA is
427 unable to establish a connection with one of the DSAs speci-
428 fied by the preferredServerList.
430 If more than one address is provided, the DUA may choose to
431 either accept the order provided, or choose to create its own
432 order, based on what the DUA determines is the "best" order of
433 servers to query. For example, the DUA may choose to examine
434 the server list and choose to query the DSAs in order based on
435 the "closest" server or the server with the least amount of
436 "load." Interpretation of the "best" server order is entirely
437 up to the DUA, and not part of this document.
439 Once the order of server addresses is determined, the DUA con-
440 tacts the DSA specified by the first server address in the
441 list. If that DSA is unavailable, the remaining DSAs SHOULD
442 be queried until an available DSA is found or no more DSAs are
448 Internet-Draft DUA Configuration Schema October 2002
451 available. If a server address or port is invalid, the DUA
452 SHOULD proceed to the next server address as described just
457 serverList = host *(space [host])
461 If a defaultServerList attribute is not provided, the DUA
462 should xxx attempt to contact the same DSA that provided the
463 configuration profile entry itself. The default DSA is con-
464 tacted only if the preferredServerList attribute is also not
467 Other attribute notes:
469 This attribute is used in conjunction with the preferredSer-
470 verList attribute. Please see section 5.1.1 for additional
471 implementation notes. Determining how the DUA should query
472 the DSAs also depends on the additional configuration attri-
473 butes, credentialLevel, serviceCredentialLevel, bindTimeLimit,
474 serviceAuthenticationMethod and authenticationMethod. Please
475 review section 5.2 for details on how a DUA should properly
480 defaultServerList: 1.2.3.4 ldap1.mycorp.com ldap2:1389
481 [1080::8:800:200C:417A]:1389
483 5.1.3 Interpreting the defaultSearchBase attribute
487 When a DUA needs to search the DSA for information, this
488 attribute provides the "base" for the search. This parameter
489 can be overridden or appended by the serviceSearchDescriptor
490 attribute. See section 5.1.6.
494 Defined by OID 1.3.6.1.4.1.1466.115.121.1.12
498 There is no default value for the defaultSearchBase. A DUA
504 Internet-Draft DUA Configuration Schema October 2002
507 MAY define its own method for determining the search base, if
508 the defaultSearchBase is not provided.
510 Other attribute notes:
512 This attribute is used in conjunction with the serviceSear-
513 chDescriptor attribute. See section 5.1.6.
517 defaultSearchBase: dc=mycompany,dc=com
519 5.1.4 Interpreting the authenticationMethod attribute
523 The authenticationMethod attribute defines an ordered list of
524 LDAP bind methods to be used when attempting to contact a
525 DSA[1]. The serviceAuthenticationMethod overrides this value
526 for a particular service (see 5.1.15.) Each method MUST be
527 attempted in the order provided by the attribute, until a suc-
528 cessful LDAP bind is performed ("none" is assumed to always be
529 successful.) However the DUA MAY skip over one or more
530 methods. See section 5.2 for more information.
532 none - The DUA does not perform an LDAP bind.
533 simple - The DUA performs an LDAP simple bind.
534 sasl - The DUA performs an LDAP SASL bind using the
535 specified SASL mechanism and options.
536 tls - The DUA performs an LDAP StartTLS operation
537 followed by the specified bind method (for more
538 information refer to section 5.1 of RFC 2830 [12]).
542 authMethod = method *(";" method)
543 method = none | simple | sasl | tls
546 sasl = "sasl/" saslmech [ ":" sasloption ]
547 sasloption = "auth-conf" | "auth-int"
548 tls = "tls:" (none | simple | sasl)
549 saslmech = SASL mechanism name as defined in
550 RFC 2222[7], section 3
552 Note: Although multiple authentication methods may be speci-
553 fied in the syntax, at most one of each type is allowed.
558 Neal-Joslin [Page 10]
560 Internet-Draft DUA Configuration Schema October 2002
565 If the authenticationMethod or serviceAuthenticationMethod
566 (for that particular service) attributes are not provided, the
567 DUA MAY choose to bind to the DSA using any method defined by
568 the DUA. However, if either authenticationMethod or servi-
569 ceAuthenticationMethod are provided, the DUA MUST only use the
572 Other attribute notes:
574 When using TLS, the string "tls:sasl/EXTERNAL" implies that
575 two way authentication is to be performed. Any other TLS
576 authentication method implies one way (DSA side credential)
579 Determining how the DUA should bind to the DSAs also depends
580 on the additional configuration attributes, credentialLevel,
581 serviceCredentialLevel, serviceAuthenticationMethod and
582 bindTimeLimit. Please review section 5.2 for details on how
583 to properly bind to a DSA.
587 authenticationMethod: tls:simple;sasl/DIGEST-MD5
590 5.1.5 Interpreting the credentialLevel attribute
594 The credentialLevel attribute defines what type(s) of
595 credential(s) the DUA SHOULD use when contacting the DSA. The
596 serviceCredentialLevel overrides this value for a particular
597 service (5.1.16.) The credentialLevel can contain more than
598 one credential type, separated by white space.
600 anonymous - The DUA SHOULD NOT use a credential when binding
603 proxy - The DUA SHOULD use a known proxy identity when binding
604 to the DSA. A proxy identity is a specific credential that
605 was created to represent the DUA. This document does not
606 define how the proxy user should be created, or how the DUA
607 should determine what the proxy user's credential is. This
608 functionality is up to each implementation.
610 self - When the DUA is acting on behalf of a "real user" the
614 Neal-Joslin [Page 11]
616 Internet-Draft DUA Configuration Schema October 2002
619 DUA SHOULD attempt to bind to the DSA as that user. The DUA
620 SHOULD map the user's identity to a credential used in the
623 If the credentialLevel contains more than one credential type,
624 the DUA MUST use the credential types in the order specified.
625 However, the DUA MAY skip over one or more credential types.
626 As soon as the DUA is able to successfully bind to the DSA,
627 the DUA SHOULD NOT attempt to bind using the remaining creden-
632 credentialLevel = level *(space level)
633 level = self | proxy | anonymous
636 anonymous = "anonymous"
638 Note: Although multiple credential levels may be specified in
639 the syntax, at most one of each type is allowed. Refer to
640 implementation notes in section 5.2 for additional syntax
641 requirements for the credentialLevel attribute.
645 If the credentialLevel attribute is not defined, the DUA
646 SHOULD NOT use a credential when binding to the DSA (also
649 Other attribute notes:
651 Determining how the DUA should bind to the DSAs also depends
652 on the additional configuration attributes, authentication-
653 Method, serviceAuthenticationMethod, serviceCredentialLevel
654 and bindTimeLimit. Please review section 5.2 for details on
655 how to properly bind to a DSA.
659 credentialLevel: proxy anonymous
661 5.1.6 Interpreting the serviceSearchDescriptor attribute
665 The serviceSearchDescriptor attribute defines how and where a
666 DUA SHOULD search for information for a particular service.
670 Neal-Joslin [Page 12]
672 Internet-Draft DUA Configuration Schema October 2002
675 The serviceSearchDescriptor contains a serviceID, followed by
676 one or more base-scope-filter triples. These base-scope-
677 filter triples are used to define searches only for the
678 specific service. Multiple base-scope-filters allow the DUA
679 to search for data in multiple locations of the DIT. Although
680 this syntax is very similar to the LDAP URL[6], this draft
681 requires the ability to supply multiple hosts as part of the
682 configuration of the DSA. In addition, an ordered list of
683 search descritors is required, which can not be specified by
686 In addition to the triples, serviceSearchDescriptor might also
687 contain the DN of an entry that will contain an alternate pro-
688 file. The DSA SHOULD re-evaluate the alternate profile and
689 perform searches as specified by that profile.
691 If the base, as defined in the serviceSearchDescriptor, is
692 followed by the "," (ASCII 0x2C) character, this base is known
693 as a relative base. This relative base may be constructed of
694 one or more RDN components. The DUA MUST define the search
695 base by appending the relative base with the defaultSear-
700 serviceSearchList = serviceID ":" serviceSearchDesc
701 *(";" serviceSearchDesc)
702 serviceSearchDesc = confReferral | searchDescriptor
703 searchDescriptor = [base] ["?" [scope] ["?" [filter]]]
704 confReferral = "ref:" DistinguishedName
705 base = DistinguishedName |
707 RelativeBaseName = 1*(RelativeDistinguishedName ",")
708 filter = UTF-8 encoded string
710 If the base or filter contains the ";" (ASCII 0x3B) "?" (ASCII
711 0x3F) """ (ASCII 0x22) or "\" (ASCII 0x5C) characters, those
712 characters MUST be escaped (preceded with the "\" character.)
713 Alternately the DN may be surrounded by quotes (ASCII 0x22.)
714 Refer to RFC 2253, section 4. If the base or filter are sur-
715 rounded by quotes, only the """ character needs to be escaped.
716 Any character that is preceded by the "\" character, which
717 does not need to be escaped results in both "\" character and
718 the character itself.
720 The usage and syntax of the filter string MUST be defined by
721 the DUA service. A suggested syntax would be that as defined
726 Neal-Joslin [Page 13]
728 Internet-Draft DUA Configuration Schema October 2002
731 If a DUA is performing a search for a particular service,
732 which has a serviceSearchDescriptor defined, the DUA MUST set
733 the base, scope and filter as defined. Each base-scope-filter
734 triple represents a single LDAP search operation. If multiple
735 base-scope-filter triples are provided in the serviceSear-
736 chDescriptor, the DUA SHOULD perform multiple search requests
737 and in that case it MUST be in the order specified by the ser-
738 viceSearchDescriptor.
740 FYI: Service search descriptors do not exactly follow the LDAP
741 URL syntax [5]. The reasoning for this difference is to
742 separate the host name(s) from the filter. This allows the
743 DUA to have a more flexible solution in choosing its provider.
747 If a serviceSearchDescriptor, or an element their-of, is not
748 defined for a particular service, the DUA SHOULD create the
749 base, scope and filter as follows:
751 base - Same as the defaultSearchBase or as
752 defined by the DUA service.
753 scope - Same as the defaultSearchScope or as
754 defined by the DUA service.
755 filter - Use defaults as defined by DUAs service.
757 If the defaultSearchBase or defaultSearchScope are not
758 defined, then the DUA service may use its own default.
761 Other attribute notes:
763 If a serviceSearchDescriptor exists for a given service, the
764 service MUST use at least one base-scope-filter triple in per-
765 forming searches. It SHOULD perform multiple searches per
766 service if multiple base-scope-filter triples are defined for
769 The details of how the "filter" is interpreted by each DUA's
770 service is defined by that service. This means the filter is
771 NOT REQUIRED to be a legal LDAP filter [4]. Furthermore,
772 determining how attribute and objectclass mapping affects that
773 search filter MUST be defined by the service. I.E. The DUA
774 SHOULD specify if the filter has been assumed to already have
775 been mapped, or if it is expected that mapping would be
776 applied to the filter. In general practice, implementation
777 and usability suggests that attribute and objectclass mapping
778 (sections 5.1.7 and 5.1.13) SHOULD NOT be applied to the
782 Neal-Joslin [Page 14]
784 Internet-Draft DUA Configuration Schema October 2002
787 filter defined in the serviceSearchDescriptor.
789 It is assumed the serviceID is unique to a given service
790 within the scope of any DUA that might use the given profile.
794 defaultSearchBase: dc=mycompany,dc=com
796 serviceSearchDescriptor: email:ou=people,ou=org1,?
797 one;ou=contractor,?one;
798 ref:cn=profile,dc=mycompany,dc=com
800 In this example, the DUA MUST search in
801 "ou=people,ou=org1,dc=mycompany,dc=com" first. The DUA then
802 SHOULD search in "ou=contractor,dc=mycompany,dc=com", and
803 finally it SHOULD search other locations as specified in the
804 profile described at "cn=profile,dc=mycompany,dc=com". For
805 more examples, see section 9.
808 5.1.7 Interpreting the attributeMap attribute
812 A DUA SHOULD perform attribute mapping for all LDAP operations
813 performed for a service that has an attributeMap entry.
814 Because attribute mapping is specific to each service within
815 the DUA, a "serviceID" is required as part of the attributeMap
816 syntax. I.E. not all DUA services should necessarily perform
817 the same attribute mapping.
819 Attribute mapping in general is expected be used to map attri-
820 butes of similar syntaxes as specified by the service sup-
821 ported by the DUA. However, a DUA is NOT REQUIRED to verify
822 syntaxes of mapped attributes. If the DUA does discover that
823 the syntax of the mapped attribute does not match that of the
824 original attribute, the DUA MAY perform translation between
825 the original syntax and the new syntax. When DUAs do support
826 attribute value translation, the list of capabable transla-
827 tions SHOULD be documented in a description of the DUA ser-
832 attributeMap = serviceID ":" origAttribute "="
834 origAttribute = attribute
838 Neal-Joslin [Page 15]
840 Internet-Draft DUA Configuration Schema October 2002
843 attributes = wattribute *( space wattribute )
844 wattribute = whsp newAttribute whsp
845 newAttribute = descr | "*NULL*"
848 Values of the origAttribute are defined by and SHOULD be docu-
849 mented for the DUA service, as a list of known supported
854 By default, attributes that are used by a DUA service are not
855 mapped unless mapped by the attributeMap attributes. The DUA
856 MUST NOT map an attribute unless it is explicitly defined by
857 an attributeMap attribute.
859 Other attribute notes:
861 When an attribute is mapped to the special keystring "*NULL*",
862 the DUA SHOULD NOT request that attribute from the DSA, when
863 performing a search or compare request. If the DUA is also
864 capable of performing modification on the DSA, the DUA SHOULD
865 NOT attempt to modify any attribute which has been mapped to
868 It is assumed the serviceID is unique to a given service
869 within the scope of the DSA.
871 A DUA SHOULD support attribute mapping. If it does, the fol-
872 lowing additional rules apply:
874 1) The list of attributes that are allowed to be mapped SHOULD
875 defined by and documented for the service.
877 2) Any supported translation of mapping from attributes of
878 dissimilar syntax SHOULD also be defined and documented.
880 3) If an attribute may be mapped to multiple attributes the
881 DSA SHOULD define a syntax or usage statement for how the new
882 attribute value will be evaluated. Furthermore, the resulting
883 translated syntax of the combined attributes MUST be the same
884 as the attribute being mapped.
886 4) A DUA MUST support mapping of attributes using the attri-
887 bute OID. It SHOULD support attribute mapping based on the
890 5) It is recommended that attribute mapping not be applied to
894 Neal-Joslin [Page 16]
896 Internet-Draft DUA Configuration Schema October 2002
899 parents of the target entries.
901 6) Attribute mapping is not recursive. In other words, if an
902 attribute has been mapped to a target attribute, that new tar-
903 get attribute MUST NOT be mapped to a third attribute.
905 7) A given attribute MUST only be mapped once for a given ser-
911 Suppose a DUA is acting on behalf of an email service. By
912 default the "email" service uses the "mail", "cn" and "sn"
913 attributes to discover mail addresses. However, the email
914 service has been deployed in an environment that uses "employ-
915 eeName" instead of "cn." And also instead of using the "mail"
916 attribute for email addresses, the "email" attribute is used
917 for that purpose. In this case, the attribute "cn" can be
918 mapped to "employeeName," allowing the DUA to perform searches
919 using the "employeeName" attribute as part of the search
920 filter, instead of "cn". And "mail" can be mapped to "email"
921 when attempting to retrieve the email address. This mapping
922 is performed by adding the attributeMap attributes to the con-
923 figuration profile entry as follows (represented in LDIF[18]):
925 attributeMap: email:cn=employeeName
926 attributeMap: email:mail=email
928 As described above, the DUA MAY also map a single attribute to
929 multiple attributes. When mapping a single attribute to more
930 than one attribute, the new syntax or usage of the mapped
931 attribute must be intrinsically defined by the DUAs service.
933 attributeMap: email:cn=firstName lastName
935 In the above example, the DUA creates the new value by gen-
936 erating space separated string using the values of the mapped
937 attributes. In this case, a special mapping must be defined
938 so that a proper search filter can be created. For further
939 information on this example, please refer to section 9.
941 Another possibility for multiple attribute mapping might come
942 in when constructing returned attributes. For example,
943 perhaps all email addresses are of a guaranteed syntax of
944 "uid@domain". And in this example, the uid and domain are
945 separate attributes in the directory. The email service may
946 define that if the "mail" attribute is mapped to two different
950 Neal-Joslin [Page 17]
952 Internet-Draft DUA Configuration Schema October 2002
955 attributes, it will construct the email address as a concate-
956 nation of the uid and domain attributes, placing the "@" char-
959 attributeMap: email:mail=uid domain
962 5.1.8 Interpreting the searchTimeLimit attribute
966 The searchTimeLimit attribute defines the maximum time, in
967 seconds, that a DUA SHOULD allow to perform a search request.
971 Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
975 If the searchTimeLimit attribute is not defined or is zero,
976 the search time limit is not enforced by the DUA.
978 Other attribute notes:
980 This time limit only includes the amount of time required to
981 perform the LDAP search operation. If other operations are
982 required, those operations do not need to be considered part
983 of the search time. See bindTimeLimit for the LDAP bind
986 5.1.9 Interpreting the bindTimeLimit attribute
990 The bindTimeLimit attribute defines the maximum time, in
991 seconds, that a DUA SHOULD allow to perform an LDAP bind
992 request against each server on the preferredServerList or
997 Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
1001 If the bindTimeLimit attribute is not defined or is zero, the
1002 bind time limit is not enforced by the DUA.
1006 Neal-Joslin [Page 18]
1008 Internet-Draft DUA Configuration Schema October 2002
1011 Other attribute notes:
1013 This time limit only includes the amount of time required to
1014 perform the LDAP bind operation. If other operations are
1015 required, those operations do not need to be considered part
1016 of the bind time. See searchTimeLimit for the LDAP search
1019 5.1.10 Interpreting the followReferrals attribute
1023 If set to TRUE, the DUA SHOULD follow any referrals if
1026 If set to FALSE, the DUA MUST NOT follow referrals.
1030 Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.
1034 If the followReferrals attribute is not set or set to an
1035 invalid value the default value is TRUE.
1037 5.1.11 Interpreting the dereferenceAliases attribute
1041 If set to TRUE, the DUA SHOULD enable alias dereferening.
1043 If set to FALSE, the DUA MUST NOT enable alias dereferencing.
1047 Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.
1051 If the dereferenceAliases attribute is not set or set to an
1052 invalid value the default value is TRUE.
1054 5.1.12 Interpreting the profileTTL attribute
1058 The profileTTL attribute defines how often the DUA SHOULD re-
1062 Neal-Joslin [Page 19]
1064 Internet-Draft DUA Configuration Schema October 2002
1067 load and reconfigure itself using the corresponding configura-
1068 tion profile entry. The value is represented in seconds.
1069 Once a DUA reloads the profile entry, it SHOULD re-configure
1070 itself with the new values.
1074 Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
1078 If not specified the DUA MAY use its own reconfiguration pol-
1081 Other attribute notes:
1083 If the profileTTL value is zero, the DUA SHOULD NOT automati-
1084 cally re-load the configuration profile.
1086 5.1.13 Interpreting the objectclassMap attribute
1090 A DUA MAY perform objectclass mapping for all LDAP operations
1091 performed for a service that has an objectclassMap entry.
1092 Because objectclass mapping is specific for each service
1093 within the DUA, a "serviceID" is required as part of the
1094 objectclassMap syntax. I.E. Not all DUA services should
1095 necessarily perform the same objectclass mapping.
1097 Objectclass mapping SHOULD be used in conjunction with attri-
1098 bute mapping to map the required schema by the service to an
1099 equivalent schema that is available in the directory.
1101 Objectclass mapping may or may not be required by a DUA. In
1102 general, the objectclass attribute is used primarily in search
1103 filters. If a service search descriptor is provided, it is
1104 expected that the search filter contains a "correct" search
1105 filter (though this is not a requirement,) which does not need
1106 to be re-mapped. However, when the service search descriptor
1107 is not provided, and the default search filter for that ser-
1108 vice contains the objectclass attribute, that search filter
1109 SHOULD be re-defined by objectclass mapping. If a default
1110 search filter is not used, it SHOULD be re-defined through the
1111 serviceSearchDescriptor. If a serviceSearchDescriptor is
1112 defined for a particular service, it SHOULD NOT be re-mapped
1113 by either the objectclassMap or attributeMap values.
1118 Neal-Joslin [Page 20]
1120 Internet-Draft DUA Configuration Schema October 2002
1123 One condition where the objectclassMap SHOULD be used is when
1124 the DUA is providing gateway functionality. In this case, the
1125 DUA is acting on behalf of another service, which may pass in
1126 a search filter itself. In this type of DUA, the DUA may
1127 alter the search filter according to the appropriate attribu-
1128 teMap and objectclassMap values. And in this case, it is also
1129 assumed that a serviceSearchDescriptor is not defined.
1133 objectclassMap = serviceID ":" origObjectclass "="
1135 origObjectclass = objectclass
1136 objectclass = keystring
1138 Values of the origObjectclass depend on the type of DUA Ser-
1139 vice using the objectclass mapping feature.
1143 The DUA MUST NOT remap an objectclass unless it is explicitly
1144 defined by an objectclassMap attribute.
1146 Other attribute notes:
1148 A DUA SHOULD support objectclass mapping. If it does, the DUA
1149 MUST support mapping of objectclasses using the objectclass
1150 OID. It SHOULD support objectclass mapping based on the
1153 It is assumed the serviceID is unique to a given service
1154 within the scope of the DSA.
1158 Suppose a DUA is acting on behalf of an email service. By
1159 default the "email" service uses the "mail", "cn" and "sn"
1160 attributes to discover mail addresses in entries created using
1161 inetOrgPerson objectclass [16]. However, the email service
1162 has been deployed in an environment that uses entries created
1163 using "employee" objectclass. In this case, the attribute
1164 "cn" can be mapped to "employeeName", and "inetOrgPerson" can
1165 be mapped to "employee", allowing the DUA to perform LDAP
1166 operations using the entries that exist in the directory.
1167 This mapping is performed by adding attributeMap and
1168 objectclassMap attributes to the configuration profile entry
1169 as follows (represented in LDIF[18]):
1174 Neal-Joslin [Page 21]
1176 Internet-Draft DUA Configuration Schema October 2002
1179 attributeMap: email:cn=employeeName
1180 objectclassMap: email:inetOrgPerson=employee
1183 5.1.14 Interpreting the defaultSearchScope attribute
1187 When a DUA needs to search the DSA for information, this
1188 attribute provides the "scope" for the search. This parameter
1189 can be overridden by the serviceSearchDescriptor attribute.
1194 scopeSyntax = "base" | "one" | "sub"
1198 The default value for the defaultSearchScope SHOULD be defined
1199 by the DUA service. If the default search scope for a service
1200 is not defined then the scope SHOULD be for the DUA to perform
1204 5.1.15 Interpreting the serviceAuthenticationMethod attribute
1208 The serviceAuthenticationMethod attribute defines an ordered
1209 list of LDAP bind methods to be used when attempting to con-
1210 tact a DSA for a particular service. Interpretation and use
1211 of this attribute is the same as 5.1.4, but specific for each
1216 svAuthMethod = service ":" method *(";" method)
1218 Note: Although multiple authentication methods may be speci-
1219 fied in the syntax, at most one of each type is allowed.
1223 If the serviceAuthenticationMethod attribute is not provided,
1224 the authenticationMethod SHOULD be followed, or its default.
1226 Other attribute notes:
1230 Neal-Joslin [Page 22]
1232 Internet-Draft DUA Configuration Schema October 2002
1235 Determining how the DUA should bind to the DSAs also depends
1236 on the additional configuration attributes, credentialLevel,
1237 serviceCredentialLevel and bindTimeLimit. Please review sec-
1238 tion 5.2 for details on how to properly bind to a DSA.
1242 serviceAuthenticationMethod: email:tls:simple;sasl/DIGEST-MD5
1245 5.1.16 Interpreting the serviceCredentialLevel attribute
1249 The serviceCredentialLevel attribute defines what type(s) of
1250 credential(s) the DUA SHOULD use when contacting the DSA for a
1251 particular service. Interpretation and used of this attribute
1252 are the same as 5.1.5.
1256 svCredentialLevel = service ":" level *(space level)
1258 Refer to implementation notes in section 5.2 for additional
1259 syntax requirements for the credentialLevel attribute.
1261 Note: Although multiple credential levels may be specified in
1262 the syntax, at most one of each type is allowed.
1266 If the serviceCredentialLevel attribute is not defined, the
1267 DUA MUST examine the credentialLevel attribute, or follow its
1268 default if not provided.
1270 Other attribute notes:
1272 Determining how the DUA should bind to the DSAs also depends
1273 on the additional configuration attributes, serviceAuthentica-
1274 tionMethod, authenticationMethod and bindTimeLimit. Please
1275 review section 5.2 for details on how to properly bind to a
1280 serviceCredentialLevel: email:proxy anonymous
1286 Neal-Joslin [Page 23]
1288 Internet-Draft DUA Configuration Schema October 2002
1291 5.2 Binding to the Directory Server
1293 The DUA SHOULD use the following algorithm when binding to the
1296 for (clevel in credLevel) [see note 1]
1297 if (clevel is "anonymous")
1298 for (host in hostnames) [see note 2]
1299 if (server is responding)
1303 for (amethod in authMethod) [see note 3]
1304 if (amethod is none)
1305 for (host in hostnames)
1306 if (server is responding)
1310 for (host in hostnames)
1311 authenticate using amethod and clevel
1312 if (authentication passed)
1316 Note 1: The credLevel is a list of credential levels as defined
1317 in serviceCredentialLevel (section 5.1.16) for a given
1318 service. If the serviceCredentialLevel is not defined,
1319 the DUA MUST examine the credentialLevel attribute.
1321 Note 2: hostnames is the list of servers to contact as defined
1324 Note 3: The authMethod a list of authentication methods as defined
1325 in serviceAuthenticationMethod (section 5.1.15) for a
1326 given service. If the serviceAuthenticationMethod is not
1327 defined, the DUA MUST examine the authenticationMethod
1332 6. Security Considerations
1334 The profile entries MUST be protected against unauthorized modifi-
1335 cation. Since the profile is most useful if its content is avail-
1336 able broadly, it is recommended that the profile entries will be
1337 readable anonymously. However, ultimately each service needs to
1338 consider implications of providing its service configuration as
1342 Neal-Joslin [Page 24]
1344 Internet-Draft DUA Configuration Schema October 2002
1347 part of this profile and limit access to the profile entries
1348 accordingly. Additionally, the management of the authentication
1349 credentials for the DUA is outside the scope of this document and
1350 needs to be handled by the DUA.
1352 The algorithm described by section 5.2 also has security considera-
1353 tions. Altering that design will alter the security aspectes of
1354 the configuration profile.
1359 There were several additional authors of this document. However we
1360 chose to represent only one author per company in the heading.
1361 From Sun we also would like to acknowledge Roberto Tam for his
1362 design work on Sun's first LDAP name service product and his input
1363 for this document. From Hewlett-Packard we'd like to acknowledge
1364 Dave Binder for his work architecting Hewlett-Packard's LDAP name
1365 service product as well as his design guidance on this document.
1366 We'd also like to acknowledge Grace Lu from HP, for her input and
1367 implementation of HP's configuration profile manager code.
1373 M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication
1374 Methods for LDAP", RFC 2828, May 2000
1377 M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
1378 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252,
1382 M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
1383 (v3): UTF-8 String Representation of Distinguished Names", RFC
1384 2253, December 1997.
1387 T. Howes, "The String Representation of LDAP Search Filters", RFC
1388 2254, December 1997.
1391 T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December 1997.
1394 T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
1398 Neal-Joslin [Page 25]
1400 Internet-Draft DUA Configuration Schema October 2002
1403 Locators (URL)", RFC 1738, December 1994.
1406 J. Meyers, "Simple Authentication and Security Layer [SASL]", RFC
1410 M. Wahl, "A Summary of the X.500(96) User Schema for use with
1411 LDAPv3", RFC 2256, December 1997.
1414 T. Berners-Lee, R. Fielding, R. Fielding, "Uniform Resource Iden-
1415 tifiers (URI): Generic Syntax", RFC 2396, August 1998.
1418 R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6
1419 Addresses in URL's, RFC 2732, December 1999.
1422 P. Leach, C. Newman, "Using Digest Authentication as a SASL Mechan-
1423 ism", RFC 2831, May 2000
1426 J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto-
1427 col [v3]: Extension for Transport Layer Security", RFC 2830, May
1431 Microsoft Corporation, "Services for Unix 2.0",
1432 http://www.microsoft.com/WINDOWS2000/sfu/default.asp
1435 L. Howard, "An Approach for Using LDAP as a Network Information
1436 Service", RFC 2307, March 1998.
1439 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
1440 els", RFC 2119, March 1997.
1443 M. Smith, "Definition of the inetOrgPerson LDAP Object Class", RFC
1447 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
1448 (v3)", RFC 2251, December 1997.
1454 Neal-Joslin [Page 26]
1456 Internet-Draft DUA Configuration Schema October 2002
1459 G. Good, "The LDAP Data Interchange Format (LDIF) - Technical
1460 Specification", RFC 2849, June 2000.
1465 In this section we will describe a fictional DUA which provides one
1466 service, called the "email" service. This service would be similar
1467 to an email client that uses an LDAP directory to discover email
1468 addresses based on a textual representation of the recipient's col-
1471 This email service is defined by default to expect that users with
1472 email addresses will be of the "inetOrgPerson" objectclass type
1473 [16]. And by default, the "email" service expects the colloquial
1474 name to be stored in the "cn" attribute, while it expects the email
1475 address to be stored in the "mail" attribute (as one would expect
1476 as defined by the inetOrgPerson objectclass.)
1478 As a special feature, the "email" service will perform a special
1479 type of attribute mapping, when performing searches. If the "cn"
1480 attribute has been mapped to two or more attributes, the "email"
1481 service will parse the requested search string and map each white-
1482 space separated token into the mapped attributes, respectively.
1484 The default search filter for the "email" service is
1485 "(objectclass=inetOrgPerson)". The email service also defines that
1486 when it performs a name to address discovery, it will wrap the
1487 search filter inside a complex search filter as follows:
1489 (&(<filter>)(cn~=<name string>)
1491 or if "cn" has been mapped to multiple attributes, that wrapping
1492 would appear as follows:
1494 (&(<filter>)(attr1~=<token1>)(attr2~=<token2>)...)
1496 The below examples show how the "email" service builds it search
1497 requests, based on the defined profile. In all cases, the
1498 defaultSearchBase is "o=airius.com" and the defaultSearchScope is
1501 In addition, for all examples, we assume that the "email" service
1502 has been requested to discover the email address for "Jane Hernan-
1510 Neal-Joslin [Page 27]
1512 Internet-Draft DUA Configuration Schema October 2002
1515 serviceSearchDescriptor: email:"ou=marketing,"
1517 base: ou=marketing,o=airius.com
1519 filter: (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))
1523 serviceSearchDescriptor: email:"ou=marketing,"?one?
1524 (&(objectclass=inetOrgPerson)(c=us))
1525 attributeMap: email:cn=2.5.4.42 sn
1527 Note: 2.5.4.42 is the OID that represents the "givenName"
1530 In this example, the email service performs <name string> parsing
1531 as described above to generate a complex search filter. The above
1532 example results in one search.
1534 base: ou=marketing,o=airius.com
1536 filter: (&(&(objectclass=inetOrgPerson)(c=us))
1537 (2.5.4.42~=Jane)(sn~=Hernandez))
1541 serviceSearchDescriptor: email:ou=marketing,"?base
1542 attributeMap: email:cn=name
1544 This example is invalid, because either the quote should have been
1545 escaped, or there should have been a leading quote.
1549 serviceSearchDescriptor: email:ou=\mar\\keting,\"?base
1550 attributeMap: email:cn=name
1552 base: ou=\mar\keting,"
1554 filter (&(objectclass=inetOrgPerson)(name~=Jane Hernandez))
1558 serviceSearchDescriptor: email:ou="marketing",o=supercom
1560 This example is invalid, since the quote was not a leading quote,
1561 and thus should have been escaped.
1566 Neal-Joslin [Page 28]
1568 Internet-Draft DUA Configuration Schema October 2002
1573 serviceSearchDescriptor: email:??(&(objectclass=person)
1574 (ou=Org1 \\(temporary\\)))
1578 filter: (&((&(objectclass=person)(ou=Org1 \(Temporary\)))
1579 (cn~=Jane Henderson)))
1583 serviceSearchDescriptor: email:"ou=funny?org,"
1585 base: ou=funny?org,o=airius.com
1587 filter (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))
1590 10. Author's Addresses
1593 PADL Software Pty. Ltd.
1595 Central Park Vic 3145
1598 EMail: lukeh@padl.com
1602 Hewlett-Packard Company
1603 19420 Homestead RD MS43-LF
1607 Phone: +1 408 447-3044
1608 EMail: bob_joslin@hp.com
1617 Phone: +1 408-716-4300
1618 EMail: morteza@infoblox.com
1622 Neal-Joslin [Page 29]
1624 Internet-Draft DUA Configuration Schema October 2002
1678 Neal-Joslin [Page 30]