4 Application Working Group M. Ansari
5 INTERNET-DRAFT Sun Microsystems, Inc.
6 Expires Febuary 2003 L. Howard
7 PADL Software Pty. Ltd.
9 Hewlett-Packard Company
12 Intended Category: Informational
15 A Configuration Schema for LDAP Based
17 <draft-joslin-config-schema-07.txt>
22 This memo provides information for the Internet community. This
23 memo does not specify an Internet standard of any kind. Distribu-
24 tion of this memo is unlimited.
26 This document is an Internet-Draft and is in full conformance with
27 all provisions of Section 10 of RFC2026.
29 This document is an Internet-Draft. Internet-Drafts are working
30 documents of the Internet Engineering Task Force (IETF), its areas,
31 and its working groups. Note that other groups may also distribute
32 working documents as Internet-Drafts.
34 Internet-Drafts are draft documents valid for a maximum of six
35 months. Internet-Drafts may be updated, replaced, or made obsolete
36 by other documents at any time. It is not appropriate to use
37 Internet-Drafts as reference material or to cite them other than as
38 a "working draft" or "work in progress".
40 To learn the current status of any Internet-Draft, please check the
41 1id-abstracts.txt listing contained in the Internet-Drafts Shadow
42 Directories on ds.internic.net (US East Coast), nic.nordu.net
43 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
46 Distribution of this document is unlimited.
50 This document describes a mechanism for global configuration of
51 similar directory user agents. This document defines a schema for
57 Internet-Draft DUA Configuration Schema October 2002
60 configuration of these DUAs that may be discovered using the Light-
61 weight Directory Access Protocol in RFC 2251[17]. A set of attri-
62 bute types and an objectclass are proposed, along with specific
63 guidelines for interpreting them. A significant feature of the
64 global configuration policy for DUAs is a mechanism that allows
65 DUAs to re-configure their schema to that of the end user's
66 environment. This configuration is achieved through attribute and
67 objectclass mapping. This document is intended to be a skeleton
68 for future documents that describe configuration of specific DUA
72 1. Background & Motivation
74 The LDAP protocol has brought about a new and nearly ubiquitous
75 acceptance of the directory server. Many new client applications
76 (DUAs) are being created that use LDAP directories for many dif-
77 ferent services. And although the LDAP protocol has eased the
78 development of these applications, some challenges still exist for
79 both developers and directory administrators.
81 The authors of this document are implementers of DUAs described by
82 RFC 2307 [14]. In developing these agents, we felt there are
83 several issues that still need to be addressed to ease the deploy-
84 ment and configuration of a large network of these DUAs.
86 One of these challenges stems from the lack of a utopian schema. A
87 utopian schema would be one that every application developer could
88 agree upon and that would support every application. Unfortunately
89 today, many DUAs define their own schema (like RFC 2307 vs.
90 Microsoft's Services for Unix [13]) containing similar attributes,
91 but with different attribute names. This can lead to data redun-
92 dancy within directory entries and give directory administrators
93 unwanted challenges, updating schemas and synchronizing data.
95 So, one goal of this document is to eliminate data redundancy by
96 having DUAs configure themselves to the schema of the deployed
97 directory, instead of forcing it's own schema on the directory.
99 Another goal of this document is to provide the DUA with enough
100 configuration information so that it can discover how to retrieve
101 its data in the directory, such as what locations to search in the
104 Finally, this document intends to describe a configuration method
105 for DUAs that can be shared among many DUAs, on various platforms,
106 providing as such, a configuration profile, the purpose is to cen-
107 tralize and simplify management of DUAs.
113 Internet-Draft DUA Configuration Schema October 2002
116 This document is intended to provide the skeleton framework for
117 future drafts, which will describe the individual implementation
118 details for the particular services provided by that DUA. The
119 authors of this document plan to develop such a document for the
120 Network Information Service DUA, described by RFC 2307 or its suc-
123 We expect that as DUAs take advantage of this configuration scheme,
124 each DUA will require additional configuration parameters, not
125 specified by this document. Thus, we would expect that new auxili-
126 ary object classes, containing new configuration attributes will be
127 created, and then joined with the structural class defined by this
128 document to create a configuration profile for a particular DUA
129 service. And that by joining various auxiliary objectclasses for
130 different DUA services, that configuration of various DUA services
131 can be controlled by a single configuration profile entry.
136 The schema defined by this document is defined under the "DUA Con-
137 figuration Schema." This schema is derived from the OID: iso (1)
138 org (3) dod (6) internet (1) private (4) enterprises (1) Hewlett-
139 Packard Company (11) directory (1) LDAP-UX Integration Project (3)
140 DUA Configuration Schema (1). This OID is represented in this
141 document by the keystring "DUAConfSchemaOID"
142 (1.3.6.1.4.1.11.1.3.1).
146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
148 this document are to be interpreted as described in RFC 2119 [15].
152 The attributes and classes defined in this document are summarized
155 The following attributes are defined in this document:
163 serviceSearchDescriptor
169 Internet-Draft DUA Configuration Schema October 2002
172 serviceCredentialLevel
173 serviceAuthenticationMethod
184 The following object class is defined in this document:
188 2.4 Syntax Definitions
190 The following syntax definitions are used throughout this document.
191 This document does not define new syntaxes that must be supported
192 by the directory server. The string encoding used by the attri-
193 butes defined in this document can be found section 5.
195 keystring as defined by RFC 2252 [2]
196 descr as defined by RFC 2252 section 4.1
197 a as defined by RFC 2252 section 4.1
198 d as defined by RFC 2252 section 4.1
199 space as defined by RFC 2252 section 4.1
200 whsp as defined by RFC 2252 section 4.1
201 base as defined by RFC 2253 [3]
202 DistinguishedName as defined by RFC 2253 section 2
203 RelativeDistinguishedName as defined by RFC 2253 section 2
204 scope as defined by RFC 2255 [5]
205 IPv4address as defined by RFC 2396 [9]
206 hostport as defined by RFC 2396 section 3.2.2
207 port as defined by RFC 2396 section 3.2.2
208 ipv6reference as defined by RFC 2732 [10]
209 host as defined by RFC 2732 section 3
210 serviceID = keystring
213 3. Attribute Definitions
215 This section contains attribute definitions to be used by DUAs when
216 discovering their configuration.
218 ( DUAConfSchemaOID.1.0 NAME 'defaultServerList'
219 DESC 'Default LDAP server host address used by a DUA'
225 Internet-Draft DUA Configuration Schema October 2002
228 EQUALITY caseIgnoreMatch
229 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
232 ( DUAConfSchemaOID.1.1 NAME 'defaultSearchBase'
233 DESC 'Default LDAP base DN used by a DUA'
234 EQUALITY distinguishedNameMatch
235 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
238 ( DUAConfSchemaOID.1.2 NAME 'preferredServerList'
239 DESC 'Preferred LDAP server host addresses to be used by a
241 EQUALITY caseIgnoreMatch
242 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
245 ( DUAConfSchemaOID.1.3 NAME 'searchTimeLimit'
246 DESC 'Maximum time in seconds a DUA should allow for a
248 EQUALITY integerMatch
249 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
252 ( DUAConfSchemaOID.1.4 NAME 'bindTimeLimit'
253 DESC 'Maximum time in seconds a DUA should allow for the
254 bind operation to complete'
255 EQUALITY integerMatch
256 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
259 ( DUAConfSchemaOID.1.5 NAME 'followReferrals'
260 DESC 'Tells DUA if it should follow referrals
261 returned by a DSA search result'
262 EQUALITY booleanMatch
263 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
266 ( DUAConfSchemaOID.1.16 NAME 'dereferenceAliases'
267 DESC 'Tells DUA if it should dereference aliases'
268 EQUALITY booleanMatch
269 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
272 ( DUAConfSchemaOID.1.6 NAME 'authenticationMethod'
273 DESC 'A keystring which identifies the type of
274 authentication method used to contact the DSA'
275 EQUALITY caseIgnoreMatch
281 Internet-Draft DUA Configuration Schema October 2002
284 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
287 ( DUAConfSchemaOID.1.7 NAME 'profileTTL'
288 DESC 'Time to live, in seconds, before a client DUA
289 should re-read this configuration profile'
290 EQUALITY integerMatch
291 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
294 ( DUAConfSchemaOID.1.14 NAME 'serviceSearchDescriptor'
295 DESC 'LDAP search descriptor list used by a DUA'
296 EQUALITY caseExactMatch
297 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
299 ( DUAConfSchemaOID.1.9 NAME 'attributeMap'
300 DESC 'Attribute mappings used by a DUA'
301 EQUALITY caseIgnoreIA5Match
302 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
304 ( DUAConfSchemaOID.1.10 NAME 'credentialLevel'
305 DESC 'Identifies type of credentials a DUA should
306 use when binding to the LDAP server'
307 EQUALITY caseIgnoreIA5Match
308 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
311 ( DUAConfSchemaOID.1.11 NAME 'objectclassMap'
312 DESC 'Objectclass mappings used by a DUA'
313 EQUALITY caseIgnoreIA5Match
314 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
316 ( DUAConfSchemaOID.1.12 NAME 'defaultSearchScope'
317 DESC 'Default search scope used by a DUA'
318 EQUALITY caseIgnoreIA5Match
319 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
322 ( DUAConfSchemaOID.1.13 NAME 'serviceCredentialLevel'
323 DESC 'Identifies type of credentials a DUA
324 should use when binding to the LDAP server for a
326 EQUALITY caseIgnoreIA5Match
327 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
329 ( DUAConfSchemaOID.1.15 NAME 'serviceAuthenticationMethod'
330 DESC 'Authentication method used by a service of the DUA'
331 EQUALITY caseIgnoreMatch
337 Internet-Draft DUA Configuration Schema October 2002
340 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
345 The objectclass below is constructed from the attributes defined in
346 3, with the exception of the cn attribute, which is defined in RFC
347 2256 [8]. cn is used to represent the name of the DUA configura-
350 ( DUAConfSchemaOID.2.5 NAME 'DUAConfigProfile'
352 DESC 'Abstraction of a base configuration for a DUA'
354 MAY ( defaultServerList $ preferredServerList $
355 defaultSearchBase $ defaultSearchScope $
356 searchTimeLimit $ bindTimeLimit $
357 credentialLevel $ authenticationMethod $
358 followReferrals $ dereferenceAliases $
359 serviceSearchDescriptor $ serviceCredentialLevel $
360 serviceAuthenticationMethod $ objectclassMap $
361 attributeMap $ profileTTL ) )
364 5. Implementation Details
366 5.1.1 Interpreting the preferredServerList attribute
370 As described by the syntax, the preferredServerList parameter
371 is a white-space separated list of server addresses and asso-
372 ciated port numbers. When the DUA needs to contact a DSA, the
373 DUA MUST first attempt to contact one of the servers listed in
374 the preferredServerList attribute. The DUA MUST contact the
375 DSA specified by the first server address in the list. If
376 that DSA is unavailable, the remaining DSAs MUST be queried in
377 the order provided until a connection is established with a
378 DSA. Once a connection with a DSA is established, the DUA
379 SHOULD NOT attempt to establish a connection with the remain-
382 If the DUA is unable to contact any of the DSAs specified by
383 the preferredServerList, the defaultServerList attribute MUST
384 be examined, as described in 5.1.2. The servers identified by
385 the preferredServerList MUST be contacted before attempting to
386 contact any of the servers specified by the defaultServerList.
393 Internet-Draft DUA Configuration Schema October 2002
398 serverList = host *(space [host])
402 The preferredServerList attribute does not have a default
403 value. Instead a DUA MUST examine the defaultServerList
406 Other attribute notes:
408 This attribute is used in conjunction with the defaultServer-
409 List attribute. Please see section 5.1.2 for additional
410 implementation notes. Determining how the DUA should query
411 the DSAs also depends on the additional configuration attri-
412 butes, credentialLevel, serviceCredentialLevel, bindTimeLimit,
413 serviceAuthenticationMethod and authenticationMethod. Please
414 review section 5.2 for details on how a Posix DUA should prop-
419 preferredServerList: 1.2.3.4 ldap1.mycorp.com ldap2:1389
420 [1080::8:800:200C:417A]:1389
422 5.1.2 Interpreting the defaultServerList attribute
426 The defaultServerList attribute MUST only be examined if the
427 preferredServerList attribute is not provided, or the DUA is
428 unable to establish a connection with one of the DSAs speci-
429 fied by the preferredServerList.
431 If more than one address is provided, the DUA may choose to
432 either accept the order provided, or choose to create its own
433 order, based on what the DUA determines is the "best" order of
434 servers to query. For example, the DUA may choose to examine
435 the server list and choose to query the DSAs in order based on
436 the "closest" server or the server with the least amount of
437 "load." Interpretation of the "best" server order is entirely
438 up to the DUA, and not part of this document.
440 Once the order of server addresses is determined, the DUA con-
441 tacts the DSA specified by the first server address in the
442 list. If that DSA is unavailable, the remaining DSAs SHOULD
443 be queried until an available DSA is found or no more DSAs are
449 Internet-Draft DUA Configuration Schema October 2002
452 available. If a server address or port is invalid, the DUA
453 SHOULD proceed to the next server address as described just
458 serverList = host *(space [host])
462 If a defaultServerList attribute is not provided, the DUA
463 should xxx attempt to contact the same DSA that provided the
464 configuration profile entry itself. The default DSA is con-
465 tacted only if the preferredServerList attribute is also not
468 Other attribute notes:
470 This attribute is used in conjunction with the preferredSer-
471 verList attribute. Please see section 5.1.1 for additional
472 implementation notes. Determining how the DUA should query
473 the DSAs also depends on the additional configuration attri-
474 butes, credentialLevel, serviceCredentialLevel, bindTimeLimit,
475 serviceAuthenticationMethod and authenticationMethod. Please
476 review section 5.2 for details on how a DUA should properly
481 defaultServerList: 1.2.3.4 ldap1.mycorp.com ldap2:1389
482 [1080::8:800:200C:417A]:1389
484 5.1.3 Interpreting the defaultSearchBase attribute
488 When a DUA needs to search the DSA for information, this
489 attribute provides the "base" for the search. This parameter
490 can be overridden or appended by the serviceSearchDescriptor
491 attribute. See section 5.1.6.
495 Defined by OID 1.3.6.1.4.1.1466.115.121.1.12
499 There is no default value for the defaultSearchBase. A DUA
505 Internet-Draft DUA Configuration Schema October 2002
508 MAY define its own method for determining the search base, if
509 the defaultSearchBase is not provided.
511 Other attribute notes:
513 This attribute is used in conjunction with the serviceSear-
514 chDescriptor attribute. See section 5.1.6.
518 defaultSearchBase: dc=mycompany,dc=com
520 5.1.4 Interpreting the authenticationMethod attribute
524 The authenticationMethod attribute defines an ordered list of
525 LDAP bind methods to be used when attempting to contact a
526 DSA[1]. The serviceAuthenticationMethod overrides this value
527 for a particular service (see 5.1.15.) Each method MUST be
528 attempted in the order provided by the attribute, until a suc-
529 cessful LDAP bind is performed ("none" is assumed to always be
530 successful.) However the DUA MAY skip over one or more
531 methods. See section 5.2 for more information.
533 none - The DUA does not perform an LDAP bind.
534 simple - The DUA performs an LDAP simple bind.
535 sasl - The DUA performs an LDAP SASL bind using the
536 specified SASL mechanism and options.
537 tls - The DUA performs an LDAP StartTLS operation
538 followed by the specified bind method (for more
539 information refer to section 5.1 of RFC 2830 [12]).
543 authMethod = method *(";" method)
544 method = none | simple | sasl | tls
547 sasl = "sasl/" saslmech [ ":" sasloption ]
548 sasloption = "auth-conf" | "auth-int"
549 tls = "tls:" (none | simple | sasl)
550 saslmech = SASL mechanism name as defined in
551 RFC 2222[7], section 3
553 Note: Although multiple authentication methods may be speci-
554 fied in the syntax, at most one of each type is allowed.
561 Internet-Draft DUA Configuration Schema October 2002
566 If the authenticationMethod or serviceAuthenticationMethod
567 (for that particular service) attributes are not provided, the
568 DUA MAY choose to bind to the DSA using any method defined by
569 the DUA. However, if either authenticationMethod or servi-
570 ceAuthenticationMethod are provided, the DUA MUST only use the
573 Other attribute notes:
575 When using TLS, the string "tls:sasl/EXTERNAL" implies that
576 two way authentication is to be performed. Any other TLS
577 authentication method implies one way (DSA side credential)
580 Determining how the DUA should bind to the DSAs also depends
581 on the additional configuration attributes, credentialLevel,
582 serviceCredentialLevel, serviceAuthenticationMethod and
583 bindTimeLimit. Please review section 5.2 for details on how
584 to properly bind to a DSA.
588 authenticationMethod: tls:simple;sasl/DIGEST-MD5
591 5.1.5 Interpreting the credentialLevel attribute
595 The credentialLevel attribute defines what type(s) of
596 credential(s) the DUA SHOULD use when contacting the DSA. The
597 serviceCredentialLevel overrides this value for a particular
598 service (5.1.16.) The credentialLevel can contain more than
599 one credential type, separated by white space.
601 anonymous - The DUA SHOULD NOT use a credential when binding
604 proxy - The DUA SHOULD use a known proxy identity when binding
605 to the DSA. A proxy identity is a specific credential that
606 was created to represent the DUA. This document does not
607 define how the proxy user should be created, or how the DUA
608 should determine what the proxy user's credential is. This
609 functionality is up to each implementation.
611 self - When the DUA is acting on behalf of a "real user" the
617 Internet-Draft DUA Configuration Schema October 2002
620 DUA SHOULD attempt to bind to the DSA as that user. The DUA
621 SHOULD map the user's identity to a credential used in the
624 If the credentialLevel contains more than one credential type,
625 the DUA MUST use the credential types in the order specified.
626 However, the DUA MAY skip over one or more credential types.
627 As soon as the DUA is able to successfully bind to the DSA,
628 the DUA SHOULD NOT attempt to bind using the remaining creden-
633 credentialLevel = level *(space level)
634 level = self | proxy | anonymous
637 anonymous = "anonymous"
639 Note: Although multiple credential levels may be specified in
640 the syntax, at most one of each type is allowed. Refer to
641 implementation notes in section 5.2 for additional syntax
642 requirements for the credentialLevel attribute.
646 If the credentialLevel attribute is not defined, the DUA
647 SHOULD NOT use a credential when binding to the DSA (also
650 Other attribute notes:
652 Determining how the DUA should bind to the DSAs also depends
653 on the additional configuration attributes, authentication-
654 Method, serviceAuthenticationMethod, serviceCredentialLevel
655 and bindTimeLimit. Please review section 5.2 for details on
656 how to properly bind to a DSA.
660 credentialLevel: proxy anonymous
662 5.1.6 Interpreting the serviceSearchDescriptor attribute
666 The serviceSearchDescriptor attribute defines how and where a
667 DUA SHOULD search for information for a particular service.
673 Internet-Draft DUA Configuration Schema October 2002
676 The serviceSearchDescriptor contains a serviceID, followed by
677 one or more base-scope-filter triples. These base-scope-
678 filter triples are used to define searches only for the
679 specific service. Multiple base-scope-filters allow the DUA
680 to search for data in multiple locations of the DIT. Although
681 this syntax is very similar to the LDAP URL[6], this draft
682 requires the ability to supply multiple hosts as part of the
683 configuration of the DSA. In addition, an ordered list of
684 search descritors is required, which can not be specified by
687 In addition to the triples, serviceSearchDescriptor might also
688 contain the DN of an entry that will contain an alternate pro-
689 file. The DSA SHOULD re-evaluate the alternate profile and
690 perform searches as specified by that profile.
692 If the base, as defined in the serviceSearchDescriptor, is
693 followed by the "," (ASCII 0x2C) character, this base is known
694 as a relative base. This relative base may be constructed of
695 one or more RDN components. The DUA MUST define the search
696 base by appending the relative base with the defaultSear-
701 serviceSearchList = serviceID ":" serviceSearchDesc
702 *(";" serviceSearchDesc)
703 serviceSearchDesc = confReferral | searchDescriptor
704 searchDescriptor = [base] ["?" [scope] ["?" [filter]]]
705 confReferral = "ref:" DistinguishedName
706 base = DistinguishedName |
708 RelativeBaseName = 1*(RelativeDistinguishedName ",")
709 filter = UTF-8 encoded string
711 If the base or filter contains the ";" (ASCII 0x3B) "?" (ASCII
712 0x3F) """ (ASCII 0x22) or "\" (ASCII 0x5C) characters, those
713 characters MUST be escaped (preceded with the "\" character.)
714 Alternately the DN may be surrounded by quotes (ASCII 0x22.)
715 Refer to RFC 2253, section 4. If the base or filter are sur-
716 rounded by quotes, only the """ character needs to be escaped.
717 Any character that is preceded by the "\" character, which
718 does not need to be escaped results in both "\" character and
719 the character itself.
721 The usage and syntax of the filter string MUST be defined by
722 the DUA service. A suggested syntax would be that as defined
729 Internet-Draft DUA Configuration Schema October 2002
732 If a DUA is performing a search for a particular service,
733 which has a serviceSearchDescriptor defined, the DUA MUST set
734 the base, scope and filter as defined. Each base-scope-filter
735 triple represents a single LDAP search operation. If multiple
736 base-scope-filter triples are provided in the serviceSear-
737 chDescriptor, the DUA SHOULD perform multiple search requests
738 and in that case it MUST be in the order specified by the ser-
739 viceSearchDescriptor.
741 FYI: Service search descriptors do not exactly follow the LDAP
742 URL syntax [5]. The reasoning for this difference is to
743 separate the host name(s) from the filter. This allows the
744 DUA to have a more flexible solution in choosing its provider.
748 If a serviceSearchDescriptor, or an element their-of, is not
749 defined for a particular service, the DUA SHOULD create the
750 base, scope and filter as follows:
752 base - Same as the defaultSearchBase or as
753 defined by the DUA service.
754 scope - Same as the defaultSearchScope or as
755 defined by the DUA service.
756 filter - Use defaults as defined by DUAs service.
758 If the defaultSearchBase or defaultSearchScope are not
759 defined, then the DUA service may use its own default.
762 Other attribute notes:
764 If a serviceSearchDescriptor exists for a given service, the
765 service MUST use at least one base-scope-filter triple in per-
766 forming searches. It SHOULD perform multiple searches per
767 service if multiple base-scope-filter triples are defined for
770 The details of how the "filter" is interpreted by each DUA's
771 service is defined by that service. This means the filter is
772 NOT REQUIRED to be a legal LDAP filter [4]. Furthermore,
773 determining how attribute and objectclass mapping affects that
774 search filter MUST be defined by the service. I.E. The DUA
775 SHOULD specify if the filter has been assumed to already have
776 been mapped, or if it is expected that mapping would be
777 applied to the filter. In general practice, implementation
778 and usability suggests that attribute and objectclass mapping
779 (sections 5.1.7 and 5.1.13) SHOULD NOT be applied to the
785 Internet-Draft DUA Configuration Schema October 2002
788 filter defined in the serviceSearchDescriptor.
790 It is assumed the serviceID is unique to a given service
791 within the scope of any DUA that might use the given profile.
795 defaultSearchBase: dc=mycompany,dc=com
797 serviceSearchDescriptor: email:ou=people,ou=org1,?
798 one;ou=contractor,?one;
799 ref:cn=profile,dc=mycompany,dc=com
801 In this example, the DUA MUST search in
802 "ou=people,ou=org1,dc=mycompany,dc=com" first. The DUA then
803 SHOULD search in "ou=contractor,dc=mycompany,dc=com", and
804 finally it SHOULD search other locations as specified in the
805 profile described at "cn=profile,dc=mycompany,dc=com". For
806 more examples, see section 9.
809 5.1.7 Interpreting the attributeMap attribute
813 A DUA SHOULD perform attribute mapping for all LDAP operations
814 performed for a service that has an attributeMap entry.
815 Because attribute mapping is specific to each service within
816 the DUA, a "serviceID" is required as part of the attributeMap
817 syntax. I.E. not all DUA services should necessarily perform
818 the same attribute mapping.
820 Attribute mapping in general is expected be used to map attri-
821 butes of similar syntaxes as specified by the service sup-
822 ported by the DUA. However, a DUA is NOT REQUIRED to verify
823 syntaxes of mapped attributes. If the DUA does discover that
824 the syntax of the mapped attribute does not match that of the
825 original attribute, the DUA MAY perform translation between
826 the original syntax and the new syntax. When DUAs do support
827 attribute value translation, the list of capabable transla-
828 tions SHOULD be documented in a description of the DUA ser-
833 attributeMap = serviceID ":" origAttribute "="
835 origAttribute = attribute
841 Internet-Draft DUA Configuration Schema October 2002
844 attributes = wattribute *( space wattribute )
845 wattribute = whsp newAttribute whsp
846 newAttribute = descr | "*NULL*"
849 Values of the origAttribute are defined by and SHOULD be docu-
850 mented for the DUA service, as a list of known supported
855 By default, attributes that are used by a DUA service are not
856 mapped unless mapped by the attributeMap attributes. The DUA
857 MUST NOT map an attribute unless it is explicitly defined by
858 an attributeMap attribute.
860 Other attribute notes:
862 When an attribute is mapped to the special keystring "*NULL*",
863 the DUA SHOULD NOT request that attribute from the DSA, when
864 performing a search or compare request. If the DUA is also
865 capable of performing modification on the DSA, the DUA SHOULD
866 NOT attempt to modify any attribute which has been mapped to
869 It is assumed the serviceID is unique to a given service
870 within the scope of the DSA.
872 A DUA SHOULD support attribute mapping. If it does, the fol-
873 lowing additional rules apply:
875 1) The list of attributes that are allowed to be mapped SHOULD
876 defined by and documented for the service.
878 2) Any supported translation of mapping from attributes of
879 dissimilar syntax SHOULD also be defined and documented.
881 3) If an attribute may be mapped to multiple attributes the
882 DSA SHOULD define a syntax or usage statement for how the new
883 attribute value will be evaluated. Furthermore, the resulting
884 translated syntax of the combined attributes MUST be the same
885 as the attribute being mapped.
887 4) A DUA MUST support mapping of attributes using the attri-
888 bute OID. It SHOULD support attribute mapping based on the
891 5) It is recommended that attribute mapping not be applied to
897 Internet-Draft DUA Configuration Schema October 2002
900 parents of the target entries.
902 6) Attribute mapping is not recursive. In other words, if an
903 attribute has been mapped to a target attribute, that new tar-
904 get attribute MUST NOT be mapped to a third attribute.
906 7) A given attribute MUST only be mapped once for a given ser-
912 Suppose a DUA is acting on behalf of an email service. By
913 default the "email" service uses the "mail", "cn" and "sn"
914 attributes to discover mail addresses. However, the email
915 service has been deployed in an environment that uses "employ-
916 eeName" instead of "cn." And also instead of using the "mail"
917 attribute for email addresses, the "email" attribute is used
918 for that purpose. In this case, the attribute "cn" can be
919 mapped to "employeeName," allowing the DUA to perform searches
920 using the "employeeName" attribute as part of the search
921 filter, instead of "cn". And "mail" can be mapped to "email"
922 when attempting to retrieve the email address. This mapping
923 is performed by adding the attributeMap attributes to the con-
924 figuration profile entry as follows (represented in LDIF[18]):
926 attributeMap: email:cn=employeeName
927 attributeMap: email:mail=email
929 As described above, the DUA MAY also map a single attribute to
930 multiple attributes. When mapping a single attribute to more
931 than one attribute, the new syntax or usage of the mapped
932 attribute must be intrinsically defined by the DUAs service.
934 attributeMap: email:cn=firstName lastName
936 In the above example, the DUA creates the new value by gen-
937 erating space separated string using the values of the mapped
938 attributes. In this case, a special mapping must be defined
939 so that a proper search filter can be created. For further
940 information on this example, please refer to section 9.
942 Another possibility for multiple attribute mapping might come
943 in when constructing returned attributes. For example,
944 perhaps all email addresses are of a guaranteed syntax of
945 "uid@domain". And in this example, the uid and domain are
946 separate attributes in the directory. The email service may
947 define that if the "mail" attribute is mapped to two different
953 Internet-Draft DUA Configuration Schema October 2002
956 attributes, it will construct the email address as a concate-
957 nation of the uid and domain attributes, placing the "@" char-
960 attributeMap: email:mail=uid domain
963 5.1.8 Interpreting the searchTimeLimit attribute
967 The searchTimeLimit attribute defines the maximum time, in
968 seconds, that a DUA SHOULD allow to perform a search request.
972 Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
976 If the searchTimeLimit attribute is not defined or is zero,
977 the search time limit is not enforced by the DUA.
979 Other attribute notes:
981 This time limit only includes the amount of time required to
982 perform the LDAP search operation. If other operations are
983 required, those operations do not need to be considered part
984 of the search time. See bindTimeLimit for the LDAP bind
987 5.1.9 Interpreting the bindTimeLimit attribute
991 The bindTimeLimit attribute defines the maximum time, in
992 seconds, that a DUA SHOULD allow to perform an LDAP bind
993 request against each server on the preferredServerList or
998 Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
1002 If the bindTimeLimit attribute is not defined or is zero, the
1003 bind time limit is not enforced by the DUA.
1009 Internet-Draft DUA Configuration Schema October 2002
1012 Other attribute notes:
1014 This time limit only includes the amount of time required to
1015 perform the LDAP bind operation. If other operations are
1016 required, those operations do not need to be considered part
1017 of the bind time. See searchTimeLimit for the LDAP search
1020 5.1.10 Interpreting the followReferrals attribute
1024 If set to TRUE, the DUA SHOULD follow any referrals if
1027 If set to FALSE, the DUA MUST NOT follow referrals.
1031 Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.
1035 If the followReferrals attribute is not set or set to an
1036 invalid value the default value is TRUE.
1038 5.1.11 Interpreting the dereferenceAliases attribute
1042 If set to TRUE, the DUA SHOULD enable alias dereferening.
1044 If set to FALSE, the DUA MUST NOT enable alias dereferencing.
1048 Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.
1052 If the dereferenceAliases attribute is not set or set to an
1053 invalid value the default value is TRUE.
1055 5.1.12 Interpreting the profileTTL attribute
1059 The profileTTL attribute defines how often the DUA SHOULD re-
1065 Internet-Draft DUA Configuration Schema October 2002
1068 load and reconfigure itself using the corresponding configura-
1069 tion profile entry. The value is represented in seconds.
1070 Once a DUA reloads the profile entry, it SHOULD re-configure
1071 itself with the new values.
1075 Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
1079 If not specified the DUA MAY use its own reconfiguration pol-
1082 Other attribute notes:
1084 If the profileTTL value is zero, the DUA SHOULD NOT automati-
1085 cally re-load the configuration profile.
1087 5.1.13 Interpreting the objectclassMap attribute
1091 A DUA MAY perform objectclass mapping for all LDAP operations
1092 performed for a service that has an objectclassMap entry.
1093 Because objectclass mapping is specific for each service
1094 within the DUA, a "serviceID" is required as part of the
1095 objectclassMap syntax. I.E. Not all DUA services should
1096 necessarily perform the same objectclass mapping.
1098 Objectclass mapping SHOULD be used in conjunction with attri-
1099 bute mapping to map the required schema by the service to an
1100 equivalent schema that is available in the directory.
1102 Objectclass mapping may or may not be required by a DUA. In
1103 general, the objectclass attribute is used primarily in search
1104 filters. If a service search descriptor is provided, it is
1105 expected that the search filter contains a "correct" search
1106 filter (though this is not a requirement,) which does not need
1107 to be re-mapped. However, when the service search descriptor
1108 is not provided, and the default search filter for that ser-
1109 vice contains the objectclass attribute, that search filter
1110 SHOULD be re-defined by objectclass mapping. If a default
1111 search filter is not used, it SHOULD be re-defined through the
1112 serviceSearchDescriptor. If a serviceSearchDescriptor is
1113 defined for a particular service, it SHOULD NOT be re-mapped
1114 by either the objectclassMap or attributeMap values.
1121 Internet-Draft DUA Configuration Schema October 2002
1124 One condition where the objectclassMap SHOULD be used is when
1125 the DUA is providing gateway functionality. In this case, the
1126 DUA is acting on behalf of another service, which may pass in
1127 a search filter itself. In this type of DUA, the DUA may
1128 alter the search filter according to the appropriate attribu-
1129 teMap and objectclassMap values. And in this case, it is also
1130 assumed that a serviceSearchDescriptor is not defined.
1134 objectclassMap = serviceID ":" origObjectclass "="
1136 origObjectclass = objectclass
1137 objectclass = keystring
1139 Values of the origObjectclass depend on the type of DUA Ser-
1140 vice using the objectclass mapping feature.
1144 The DUA MUST NOT remap an objectclass unless it is explicitly
1145 defined by an objectclassMap attribute.
1147 Other attribute notes:
1149 A DUA SHOULD support objectclass mapping. If it does, the DUA
1150 MUST support mapping of objectclasses using the objectclass
1151 OID. It SHOULD support objectclass mapping based on the
1154 It is assumed the serviceID is unique to a given service
1155 within the scope of the DSA.
1159 Suppose a DUA is acting on behalf of an email service. By
1160 default the "email" service uses the "mail", "cn" and "sn"
1161 attributes to discover mail addresses in entries created using
1162 inetOrgPerson objectclass [16]. However, the email service
1163 has been deployed in an environment that uses entries created
1164 using "employee" objectclass. In this case, the attribute
1165 "cn" can be mapped to "employeeName", and "inetOrgPerson" can
1166 be mapped to "employee", allowing the DUA to perform LDAP
1167 operations using the entries that exist in the directory.
1168 This mapping is performed by adding attributeMap and
1169 objectclassMap attributes to the configuration profile entry
1170 as follows (represented in LDIF[18]):
1177 Internet-Draft DUA Configuration Schema October 2002
1180 attributeMap: email:cn=employeeName
1181 objectclassMap: email:inetOrgPerson=employee
1184 5.1.14 Interpreting the defaultSearchScope attribute
1188 When a DUA needs to search the DSA for information, this
1189 attribute provides the "scope" for the search. This parameter
1190 can be overridden by the serviceSearchDescriptor attribute.
1195 scopeSyntax = "base" | "one" | "sub"
1199 The default value for the defaultSearchScope SHOULD be defined
1200 by the DUA service. If the default search scope for a service
1201 is not defined then the scope SHOULD be for the DUA to perform
1205 5.1.15 Interpreting the serviceAuthenticationMethod attribute
1209 The serviceAuthenticationMethod attribute defines an ordered
1210 list of LDAP bind methods to be used when attempting to con-
1211 tact a DSA for a particular service. Interpretation and use
1212 of this attribute is the same as 5.1.4, but specific for each
1217 svAuthMethod = service ":" method *(";" method)
1219 Note: Although multiple authentication methods may be speci-
1220 fied in the syntax, at most one of each type is allowed.
1224 If the serviceAuthenticationMethod attribute is not provided,
1225 the authenticationMethod SHOULD be followed, or its default.
1227 Other attribute notes:
1233 Internet-Draft DUA Configuration Schema October 2002
1236 Determining how the DUA should bind to the DSAs also depends
1237 on the additional configuration attributes, credentialLevel,
1238 serviceCredentialLevel and bindTimeLimit. Please review sec-
1239 tion 5.2 for details on how to properly bind to a DSA.
1243 serviceAuthenticationMethod: email:tls:simple;sasl/DIGEST-MD5
1246 5.1.16 Interpreting the serviceCredentialLevel attribute
1250 The serviceCredentialLevel attribute defines what type(s) of
1251 credential(s) the DUA SHOULD use when contacting the DSA for a
1252 particular service. Interpretation and used of this attribute
1253 are the same as 5.1.5.
1257 svCredentialLevel = service ":" level *(space level)
1259 Refer to implementation notes in section 5.2 for additional
1260 syntax requirements for the credentialLevel attribute.
1262 Note: Although multiple credential levels may be specified in
1263 the syntax, at most one of each type is allowed.
1267 If the serviceCredentialLevel attribute is not defined, the
1268 DUA MUST examine the credentialLevel attribute, or follow its
1269 default if not provided.
1271 Other attribute notes:
1273 Determining how the DUA should bind to the DSAs also depends
1274 on the additional configuration attributes, serviceAuthentica-
1275 tionMethod, authenticationMethod and bindTimeLimit. Please
1276 review section 5.2 for details on how to properly bind to a
1281 serviceCredentialLevel: email:proxy anonymous
1289 Internet-Draft DUA Configuration Schema October 2002
1292 5.2 Binding to the Directory Server
1294 The DUA SHOULD use the following algorithm when binding to the
1297 for (clevel in credLevel) [see note 1]
1298 if (clevel is "anonymous")
1299 for (host in hostnames) [see note 2]
1300 if (server is responding)
1304 for (amethod in authMethod) [see note 3]
1305 if (amethod is none)
1306 for (host in hostnames)
1307 if (server is responding)
1311 for (host in hostnames)
1312 authenticate using amethod and clevel
1313 if (authentication passed)
1317 Note 1: The credLevel is a list of credential levels as defined
1318 in serviceCredentialLevel (section 5.1.16) for a given
1319 service. If the serviceCredentialLevel is not defined,
1320 the DUA MUST examine the credentialLevel attribute.
1322 Note 2: hostnames is the list of servers to contact as defined
1325 Note 3: The authMethod a list of authentication methods as defined
1326 in serviceAuthenticationMethod (section 5.1.15) for a
1327 given service. If the serviceAuthenticationMethod is not
1328 defined, the DUA MUST examine the authenticationMethod
1333 6. Security Considerations
1335 The profile entries MUST be protected against unauthorized modifi-
1336 cation. Since the profile is most useful if its content is avail-
1337 able broadly, it is recommended that the profile entries will be
1338 readable anonymously. However, ultimately each service needs to
1339 consider implications of providing its service configuration as
1345 Internet-Draft DUA Configuration Schema October 2002
1348 part of this profile and limit access to the profile entries
1349 accordingly. Additionally, the management of the authentication
1350 credentials for the DUA is outside the scope of this document and
1351 needs to be handled by the DUA.
1353 The algorithm described by section 5.2 also has security considera-
1354 tions. Altering that design will alter the security aspectes of
1355 the configuration profile.
1360 There were several additional authors of this document. However we
1361 chose to represent only one author per company in the heading.
1362 From Sun we also would like to acknowledge Roberto Tam for his
1363 design work on Sun's first LDAP name service product and his input
1364 for this document. From Hewlett-Packard we'd like to acknowledge
1365 Dave Binder for his work architecting Hewlett-Packard's LDAP name
1366 service product as well as his design guidance on this document.
1367 We'd also like to acknowledge Grace Lu from HP, for her input and
1368 implementation of HP's configuration profile manager code.
1374 M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication
1375 Methods for LDAP", RFC 2828, May 2000
1378 M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
1379 Access Protocol (v3): Attribute Syntax Definitions", RFC 2252,
1383 M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
1384 (v3): UTF-8 String Representation of Distinguished Names", RFC
1385 2253, December 1997.
1388 T. Howes, "The String Representation of LDAP Search Filters", RFC
1389 2254, December 1997.
1392 T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December 1997.
1395 T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
1401 Internet-Draft DUA Configuration Schema October 2002
1404 Locators (URL)", RFC 1738, December 1994.
1407 J. Meyers, "Simple Authentication and Security Layer [SASL]", RFC
1411 M. Wahl, "A Summary of the X.500(96) User Schema for use with
1412 LDAPv3", RFC 2256, December 1997.
1415 T. Berners-Lee, R. Fielding, R. Fielding, "Uniform Resource Iden-
1416 tifiers (URI): Generic Syntax", RFC 2396, August 1998.
1419 R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6
1420 Addresses in URL's, RFC 2732, December 1999.
1423 P. Leach, C. Newman, "Using Digest Authentication as a SASL Mechan-
1424 ism", RFC 2831, May 2000
1427 J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto-
1428 col [v3]: Extension for Transport Layer Security", RFC 2830, May
1432 Microsoft Corporation, "Services for Unix 2.0",
1433 http://www.microsoft.com/WINDOWS2000/sfu/default.asp
1436 L. Howard, "An Approach for Using LDAP as a Network Information
1437 Service", RFC 2307, March 1998.
1440 S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
1441 els", RFC 2119, March 1997.
1444 M. Smith, "Definition of the inetOrgPerson LDAP Object Class", RFC
1448 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
1449 (v3)", RFC 2251, December 1997.
1457 Internet-Draft DUA Configuration Schema October 2002
1460 G. Good, "The LDAP Data Interchange Format (LDIF) - Technical
1461 Specification", RFC 2849, June 2000.
1466 In this section we will describe a fictional DUA which provides one
1467 service, called the "email" service. This service would be similar
1468 to an email client that uses an LDAP directory to discover email
1469 addresses based on a textual representation of the recipient's col-
1472 This email service is defined by default to expect that users with
1473 email addresses will be of the "inetOrgPerson" objectclass type
1474 [16]. And by default, the "email" service expects the colloquial
1475 name to be stored in the "cn" attribute, while it expects the email
1476 address to be stored in the "mail" attribute (as one would expect
1477 as defined by the inetOrgPerson objectclass.)
1479 As a special feature, the "email" service will perform a special
1480 type of attribute mapping, when performing searches. If the "cn"
1481 attribute has been mapped to two or more attributes, the "email"
1482 service will parse the requested search string and map each white-
1483 space separated token into the mapped attributes, respectively.
1485 The default search filter for the "email" service is
1486 "(objectclass=inetOrgPerson)". The email service also defines that
1487 when it performs a name to address discovery, it will wrap the
1488 search filter inside a complex search filter as follows:
1490 (&(<filter>)(cn~=<name string>)
1492 or if "cn" has been mapped to multiple attributes, that wrapping
1493 would appear as follows:
1495 (&(<filter>)(attr1~=<token1>)(attr2~=<token2>)...)
1497 The below examples show how the "email" service builds it search
1498 requests, based on the defined profile. In all cases, the
1499 defaultSearchBase is "o=airius.com" and the defaultSearchScope is
1502 In addition, for all examples, we assume that the "email" service
1503 has been requested to discover the email address for "Jane Hernan-
1513 Internet-Draft DUA Configuration Schema October 2002
1516 serviceSearchDescriptor: email:"ou=marketing,"
1518 base: ou=marketing,o=airius.com
1520 filter: (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))
1524 serviceSearchDescriptor: email:"ou=marketing,"?one?
1525 (&(objectclass=inetOrgPerson)(c=us))
1526 attributeMap: email:cn=2.5.4.42 sn
1528 Note: 2.5.4.42 is the OID that represents the "givenName"
1531 In this example, the email service performs <name string> parsing
1532 as described above to generate a complex search filter. The above
1533 example results in one search.
1535 base: ou=marketing,o=airius.com
1537 filter: (&(&(objectclass=inetOrgPerson)(c=us))
1538 (2.5.4.42~=Jane)(sn~=Hernandez))
1542 serviceSearchDescriptor: email:ou=marketing,"?base
1543 attributeMap: email:cn=name
1545 This example is invalid, because either the quote should have been
1546 escaped, or there should have been a leading quote.
1550 serviceSearchDescriptor: email:ou=\mar\\keting,\"?base
1551 attributeMap: email:cn=name
1553 base: ou=\mar\keting,"
1555 filter (&(objectclass=inetOrgPerson)(name~=Jane Hernandez))
1559 serviceSearchDescriptor: email:ou="marketing",o=supercom
1561 This example is invalid, since the quote was not a leading quote,
1562 and thus should have been escaped.
1569 Internet-Draft DUA Configuration Schema October 2002
1574 serviceSearchDescriptor: email:??(&(objectclass=person)
1575 (ou=Org1 \\(temporary\\)))
1579 filter: (&((&(objectclass=person)(ou=Org1 \(Temporary\)))
1580 (cn~=Jane Henderson)))
1584 serviceSearchDescriptor: email:"ou=funny?org,"
1586 base: ou=funny?org,o=airius.com
1588 filter (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))
1591 10. Author's Addresses
1594 PADL Software Pty. Ltd.
1596 Central Park Vic 3145
1599 EMail: lukeh@padl.com
1603 Hewlett-Packard Company
1604 19420 Homestead RD MS43-LF
1608 Phone: +1 408 447-3044
1609 EMail: bob_joslin@hp.com
1613 Sun Microsystems, Inc.
1614 901 San Antonio RD MS MPK17-203
1618 Phone: +1 650 786-6178
1619 EMail: morteza.ansari@sun.com
1625 Internet-Draft DUA Configuration Schema October 2002