git.sur5r.net Git - openldap/blob - doc/drafts/draft-joslin-config-schema-xx.txt

   1
   2 INTERNET-DRAFT                                                 M. Ansari
   3 draft-joslin-config-schema-10.txt                               Infoblox
   4 Category: Informational                                        L. Howard
   5 Expires: September 2005                          PADL Software Pty. Ltd.
   6                                                   B. Neal-Joslin, Editor
   7                                                  Hewlett-Packard Company
   8                                                            4 March, 2005
   9
  10
  11                  A Configuration Schema for LDAP Based
  12                          Directory User Agents
  13
  14
  15 Status of this Memo
  16
  17      Copyright (C) The Internet Society (2005). This document is subject
  18      to the rights, licenses and restrictions contained in BCP 78, and
  19      except as set forth therein, the authors retain all their rights.
  20
  21      This document and the information contained herein are provided on
  22      an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
  23      REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND
  24      THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
  25      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
  26      THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR
  27      ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
  28      PARTICULAR PURPOSE.
  29
  30      Internet-Drafts are working documents of the Internet Engineering
  31      Task Force (IETF), its areas, and its working groups.  Note that
  32      other groups may also distribute working documents as Internet-
  33      Drafts.
  34
  35      Internet-Drafts are draft documents valid for a maximum of six
  36      months and may be updated, replaced, or obsoleted by other
  37      documents at any time.  It is inappropriate to use Internet-Drafts
  38      as reference material or to cite them other than as "work in
  39      progress."
  40
  41      The list of current Internet-Drafts can be accessed at
  42      http://www.ietf.org/1id-abstracts.html
  43
  44      The list of Internet-Draft Shadow Directories can be accessed at
  45      http://www.ietf.org/shadow.html
  46
  47 IPR Statement
  48
  49      By submitting this Internet-Draft, I certify that any applicable
  50
  51
  52
  53 Neal-Joslin                                                    [Page 1]
  54 \f
  55 Internet-Draft          DUA Configuration Schema              March 2005
  56
  57
  58      patent or other IPR claims of which I am aware have been disclosed,
  59      or will be disclosed, and any of which I become aware will be
  60      disclosed, in accordance with RFC 3668.
  61
  62      The IETF takes no position regarding the validity or scope of any
  63      Intellectual Property Rights or other rights that might be claimed
  64      to pertain to the implementation or use of the technology described
  65      in this document or the extent to which any license under such
  66      rights might or might not be available; nor does it represent that
  67      it has made any independent effort to identify any such rights.
  68      Information on the procedures with respect to rights in RFC
  69      documents can be found in BCP 78 and BCP 79.
  70
  71      The IETF invites any interested party to bring to its attention any
  72      copyrights, patents or patent applications, or other proprietary
  73      rights that may cover technology that may be required to implement
  74      this standard.  Please address the information to the IETF at
  75      ietf-ipr@ietf.org.
  76
  77      Copies of IPR disclosures made to the IETF Secretariat and any
  78      assurances of licenses to be made available, or the result of an
  79      attempt made to obtain a general license or permission for the use
  80      of such proprietary rights by implementers or users of this
  81      specification can be obtained from the IETF on-line IPR repository
  82      at http://www.ietf.org/ipr.
  83
  84
  85
  86
  87
  88 Abstract
  89
  90      This document describes a mechanism for distributed configuration
  91      of similar directory user agents.  This document defines a schema
  92      for configuration of these DUAs that may be discovered using the
  93      Lightweight Directory Access Protocol in RFC 2251[1].  A set of
  94      attribute types and an objectclass are proposed, along with
  95      specific guidelines for interpreting them.  A proposal of using
  96      attribute and objectclass mapping allows DUAs to re-configure their
  97      schema to that of the end user's environment. This document is
  98      intended to be a skeleton for future documents that describe
  99      configuration of specific DUA services.
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109 Neal-Joslin                                                    [Page 2]
 110 \f
 111 Internet-Draft          DUA Configuration Schema              March 2005
 112
 113
 114                            Table of Contents
 115
 116  1.  Background & Motivation ......................................  4
 117  2.  General Issues ...............................................  5
 118  2.1 Terminology ..................................................  5
 119  2.2 Attributes ...................................................  5
 120  2.3 Object Classes ...............................................  6
 121  2.4 Syntax Definitions ...........................................  6
 122  3.  Attribute Definitions ........................................  6
 123  4.  Class Definition .............................................  8
 124  5.  Implementation Details .......................................  9
 125  5.1.1 Interpreting the preferredServerList attribute .............  9
 126  5.1.2 Interpreting the defaultServerList attribute ............... 10
 127  5.1.3 Interpreting the defaultSearchBase attribute ............... 11
 128  5.1.4 Interpreting the authenticationMethod attribute ............ 12
 129  5.1.5 Interpreting the credentialLevel attribute ................. 13
 130  5.1.6 Interpreting the serviceSearchDescriptor attribute ......... 14
 131  5.1.7 Interpreting the attributeMap attribute .................... 17
 132  5.1.8 Interpreting the searchTimeLimit attribute ................. 20
 133  5.1.9 Interpreting the bindTimeLimit attribute ................... 20
 134  5.1.10 Interpreting the followReferrals attribute ................ 21
 135  5.1.11 Interpreting the dereferenceAliases attribute ............. 21
 136  5.1.12 Interpreting the profileTTL attribute ..................... 21
 137  5.1.13 Interpreting the objectclassMap attribute ................. 22
 138  5.1.14 Interpreting the defaultSearchScope attribute ............. 24
 139  5.1.15 Interpreting the serviceAuthenticationMethod attribute .... 24
 140  5.1.16 Interpreting the serviceCredentialLevel attribute ......... 25
 141  5.2 Binding to the Directory Server .............................. 26
 142  6.  Security Considerations ...................................... 26
 143  7.  Acknowledgments .............................................. 27
 144  8.  References ................................................... 27
 145  8.1 Normative References ......................................... 27
 146  8.2 Informative References ....................................... 28
 147  9.  Examples ..................................................... 29
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165 Neal-Joslin                                                    [Page 3]
 166 \f
 167 Internet-Draft          DUA Configuration Schema              March 2005
 168
 169
 170 1.  Background & Motivation
 171
 172      The LDAP protocol has brought about a new and nearly ubiquitous
 173      acceptance of the directory server.  Many new client applications
 174      (DUAs) are being created that use LDAP directories for many
 175      different services.  And although the LDAP protocol has eased the
 176      development of these applications, some challenges still exist for
 177      both developers and directory administrators.
 178
 179      The authors of this document are implementers of DUAs described by
 180      RFC 2307 [2].  In developing these agents, we felt there are
 181      several issues that still need to be addressed to ease the
 182      deployment and configuration of a large network of these DUAs.
 183
 184      One of these challenges stems from the lack of a utopian schema.  A
 185      utopian schema would be one that every application developer could
 186      agree upon and that would support every application.  Unfortunately
 187      today, many DUAs define their own schema (like RFC 2307 vs.
 188      Microsoft's Services for Unix [3]) containing similar attributes,
 189      but with different attribute names.  This can lead to data
 190      redundancy within directory entries and give directory
 191      administrators unwanted challenges, updating schemas and
 192      synchronizing data.
 193
 194      So, one goal of this document is to eliminate data redundancy by
 195      having DUAs configure themselves to the schema of the deployed
 196      directory, instead of forcing its own schema on the directory.
 197
 198      Another goal of this document is to provide the DUA with enough
 199      configuration information so that it can discover how to retrieve
 200      its data in the directory, such as what locations to search in the
 201      directory tree.
 202
 203      Finally, this document intends to describe a configuration method
 204      for DUAs that can be shared among many DUAs, on various platforms,
 205      providing as such, a configuration profile, the purpose is to
 206      centralize and simplify management of DUAs.
 207
 208      This document is intended to provide the skeleton framework for
 209      future drafts, which will describe the individual implementation
 210      details for the particular services provided by that DUA.  The
 211      authors of this document plan to develop such a document for the
 212      Network Information Service DUA, described by RFC 2307 or its
 213      successor.
 214
 215      We expect that as DUAs take advantage of this configuration scheme,
 216      each DUA will require additional configuration parameters, not
 217      specified by this document.  Thus, we would expect that new
 218
 219
 220
 221 Neal-Joslin                                                    [Page 4]
 222 \f
 223 Internet-Draft          DUA Configuration Schema              March 2005
 224
 225
 226      auxiliary object classes, containing new configuration attributes
 227      will be created, and then joined with the structural class defined
 228      by this document to create a configuration profile for a particular
 229      DUA service.  And that by joining various auxiliary objectclasses
 230      for different DUA services, that configuration of various DUA
 231      services can be controlled by a single configuration profile entry.
 232
 233
 234 2.  General Issues
 235
 236      The schema defined by this document is defined under the "DUA
 237      Configuration Schema."  This schema is derived from the OID: iso
 238      (1) org (3) dod (6) internet (1) private (4) enterprises (1)
 239      Hewlett-Packard Company (11) directory (1) LDAP-UX Integration
 240      Project (3) DUA Configuration Schema (1).  This OID is represented
 241      in this document by the keystring "DUAConfSchemaOID"
 242      (1.3.6.1.4.1.11.1.3.1).
 243
 244 2.1 Terminology
 245
 246      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 247      "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in
 248      this document are to be interpreted as described in BCP 14 (RFC
 249      2119) [4].
 250
 251 2.2 Attributes
 252
 253      The attributes and classes defined in this document are summarized
 254      below.
 255
 256      The following attributes are defined in this document:
 257
 258           preferredServerList
 259           defaultServerList
 260           defaultSearchBase
 261           defaultSearchScope
 262           authenticationMethod
 263           credentialLevel
 264           serviceSearchDescriptor
 265           serviceCredentialLevel
 266           serviceAuthenticationMethod
 267           attributeMap
 268           objectclassMap
 269           searchTimeLimit
 270           bindTimeLimit
 271           followReferrals
 272           dereferenceAliases
 273           profileTTL
 274
 275
 276
 277 Neal-Joslin                                                    [Page 5]
 278 \f
 279 Internet-Draft          DUA Configuration Schema              March 2005
 280
 281
 282 2.3 Object Classes
 283
 284      The following object class is defined in this document:
 285
 286           DUAConfigProfile
 287
 288 2.4 Syntax Definitions
 289
 290      The following syntax definitions are used throughout this document.
 291      This document does not define new syntaxes that must be supported
 292      by the directory server.  The string encoding used by the
 293      attributes defined in this document can be found section 5.
 294
 295           keystring                 as defined by RFC 2252 [5]
 296           descr                     as defined by RFC 2252 section 4.1
 297           a                         as defined by RFC 2252 section 4.1
 298           d                         as defined by RFC 2252 section 4.1
 299           space                     as defined by RFC 2252 section 4.1
 300           whsp                      as defined by RFC 2252 section 4.1
 301           base                      as defined by RFC 2253 [6]
 302           DistinguishedName         as defined by RFC 2253 section 2
 303           RelativeDistinguishedName as defined by RFC 2253 section 2
 304           scope                     as defined by RFC 2255 [7]
 305           host                      as defined by RFC 3986
 306                                     section 3.2.2 [8]
 307           hostport                  host [":" port ]
 308           port                      as defined by RFC 3986
 309                                     section 3.2.3 [8]
 310           serviceID                 = keystring
 311
 312
 313 3.  Attribute Definitions
 314
 315      This section contains attribute definitions to be used by DUAs when
 316      discovering their configuration.
 317
 318           ( DUAConfSchemaOID.1.0 NAME 'defaultServerList'
 319             DESC 'Default LDAP server host addresses used by a DUA'
 320             EQUALITY caseIgnoreMatch
 321             SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
 322             SINGLE-VALUE )
 323
 324           ( DUAConfSchemaOID.1.1 NAME 'defaultSearchBase'
 325             DESC 'Default LDAP base DN used by a DUA'
 326             EQUALITY distinguishedNameMatch
 327             SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
 328             SINGLE-VALUE )
 329
 330
 331
 332
 333 Neal-Joslin                                                    [Page 6]
 334 \f
 335 Internet-Draft          DUA Configuration Schema              March 2005
 336
 337
 338           ( DUAConfSchemaOID.1.2 NAME 'preferredServerList'
 339             DESC 'Preferred LDAP server host addresses to be used by a
 340             DUA'
 341             EQUALITY caseIgnoreMatch
 342             SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
 343             SINGLE-VALUE )
 344
 345           ( DUAConfSchemaOID.1.3 NAME 'searchTimeLimit'
 346             DESC 'Maximum time in seconds a DUA should allow for a
 347             search to complete'
 348             EQUALITY integerMatch
 349             SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
 350             SINGLE-VALUE )
 351
 352           ( DUAConfSchemaOID.1.4 NAME 'bindTimeLimit'
 353             DESC 'Maximum time in seconds a DUA should allow for the
 354             bind operation to complete'
 355             EQUALITY integerMatch
 356             SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
 357             SINGLE-VALUE )
 358
 359           ( DUAConfSchemaOID.1.5 NAME 'followReferrals'
 360             DESC 'Tells DUA if it should follow referrals
 361             returned by a DSA result'
 362             EQUALITY booleanMatch
 363             SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
 364             SINGLE-VALUE )
 365
 366           ( DUAConfSchemaOID.1.6 NAME 'authenticationMethod'
 367             DESC 'A keystring which identifies the type of
 368             authentication methods used to contact the DSA'
 369             EQUALITY caseIgnoreMatch
 370             SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
 371             SINGLE-VALUE )
 372
 373           ( DUAConfSchemaOID.1.7 NAME 'profileTTL'
 374             DESC 'Time to live, in seconds, before a client DUA
 375             should re-read this configuration profile'
 376             EQUALITY integerMatch
 377             SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
 378             SINGLE-VALUE )
 379
 380           ( DUAConfSchemaOID.1.9 NAME 'attributeMap'
 381             DESC 'Attribute mappings used by a DUA'
 382             EQUALITY caseIgnoreIA5Match
 383             SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
 384
 385           ( DUAConfSchemaOID.1.10 NAME 'credentialLevel'
 386
 387
 388
 389 Neal-Joslin                                                    [Page 7]
 390 \f
 391 Internet-Draft          DUA Configuration Schema              March 2005
 392
 393
 394             DESC 'Identifies type of credentials a DUA should
 395             use when binding to the LDAP server'
 396             EQUALITY caseIgnoreIA5Match
 397             SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
 398             SINGLE-VALUE )
 399
 400           ( DUAConfSchemaOID.1.11 NAME 'objectclassMap'
 401             DESC 'Objectclass mappings used by a DUA'
 402             EQUALITY caseIgnoreIA5Match
 403             SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
 404
 405           ( DUAConfSchemaOID.1.12 NAME 'defaultSearchScope'
 406             DESC 'Default search scope used by a DUA'
 407             EQUALITY caseIgnoreIA5Match
 408             SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
 409             SINGLE-VALUE )
 410
 411           ( DUAConfSchemaOID.1.13 NAME 'serviceCredentialLevel'
 412             DESC 'Identifies type of credentials a DUA
 413             should use when binding to the LDAP server for a
 414             specific service'
 415             EQUALITY caseIgnoreIA5Match
 416             SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
 417
 418           ( DUAConfSchemaOID.1.14 NAME 'serviceSearchDescriptor'
 419             DESC 'LDAP search descriptor list used by a DUA'
 420             EQUALITY caseExactMatch
 421             SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
 422
 423           ( DUAConfSchemaOID.1.15 NAME 'serviceAuthenticationMethod'
 424             DESC 'Identifies type of authentication method a DUA
 425             should use when binding to the LDAP server for a
 426             specific service'
 427             EQUALITY caseIgnoreMatch
 428             SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
 429
 430           ( DUAConfSchemaOID.1.16 NAME 'dereferenceAliases'
 431             DESC 'Tells DUA if it should dereference aliases'
 432             EQUALITY booleanMatch
 433             SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
 434             SINGLE-VALUE )
 435
 436
 437 4.  Class Definition
 438
 439      The objectclass below is constructed from the attributes defined in
 440      3, with the exception of the cn attribute, which is defined in RFC
 441      2256 [9].  cn is used to represent the name of the DUA
 442
 443
 444
 445 Neal-Joslin                                                    [Page 8]
 446 \f
 447 Internet-Draft          DUA Configuration Schema              March 2005
 448
 449
 450      configuration profile.
 451
 452         ( DUAConfSchemaOID.2.5 NAME 'DUAConfigProfile'
 453           SUP top STRUCTURAL
 454           DESC 'Abstraction of a base configuration for a DUA'
 455           MUST ( cn )
 456           MAY ( defaultServerList $ preferredServerList $
 457                 defaultSearchBase $ defaultSearchScope $
 458                 searchTimeLimit $ bindTimeLimit $
 459                 credentialLevel $ authenticationMethod $
 460                 followReferrals $ dereferenceAliases $
 461                 serviceSearchDescriptor $ serviceCredentialLevel $
 462                 serviceAuthenticationMethod $ objectclassMap $
 463                 attributeMap $ profileTTL ) )
 464
 465
 466 5.  Implementation Details
 467
 468 5.1.1 Interpreting the preferredServerList attribute
 469
 470      Interpretation:
 471
 472           As described by the syntax, the preferredServerList parameter
 473           is a white-space separated list of server addresses and
 474           associated port numbers.  When the DUA needs to contact a DSA,
 475           the DUA MUST first attempt to contact one of the servers
 476           listed in the preferredServerList attribute.  The DUA MUST
 477           contact the DSA specified by the first server address in the
 478           list.  If that DSA is unavailable, the remaining DSAs MUST be
 479           queried in the order provided (left to right) until a
 480           connection is established with a DSA.  Once a connection with
 481           a DSA is established, the DUA SHOULD NOT attempt to establish
 482           a connection with the remaining DSAs.  The purpose of
 483           enumerating multiple DSAs is not for supplemental data, but
 484           for high availability of replicated data.  This is also the
 485           main reason why an LDAP URL[10] syntax was not selected for
 486           this document.
 487
 488           If the DUA is unable to contact any of the DSAs specified by
 489           the preferredServerList, the defaultServerList attribute MUST
 490           be examined, as described in 5.1.2.  The servers identified by
 491           the preferredServerList MUST be contacted before attempting to
 492           contact any of the servers specified by the defaultServerList.
 493
 494      Syntax:
 495
 496           serverList       = hostport *(space [hostport])
 497
 498
 499
 500
 501 Neal-Joslin                                                    [Page 9]
 502 \f
 503 Internet-Draft          DUA Configuration Schema              March 2005
 504
 505
 506      Default Value:
 507
 508           The preferredServerList attribute does not have a default
 509           value.  Instead a DUA MUST examine the defaultServerList
 510           attribute.
 511
 512      Other attribute notes:
 513
 514           This attribute is used in conjunction with the
 515           defaultServerList attribute.  Please see section 5.1.2 for
 516           additional implementation notes.  Determining how the DUA
 517           should query the DSAs also depends on the additional
 518           configuration attributes, credentialLevel,
 519           serviceCredentialLevel, bindTimeLimit,
 520           serviceAuthenticationMethod and authenticationMethod.  Please
 521           review section 5.2 for details on how a DUA should properly
 522           bind to a DSA.
 523
 524      Example:
 525
 526           preferredServerList: 192.168.169.170 ldap1.mycorp.com
 527             ldap2:1389 [1080::8:800:200C:417A]:389
 528
 529 5.1.2 Interpreting the defaultServerList attribute
 530
 531      Interpretation:
 532
 533           The defaultServerList attribute MUST only be examined if the
 534           preferredServerList attribute is not provided, or the DUA is
 535           unable to establish a connection with one of the DSAs
 536           specified by the preferredServerList.
 537
 538           If more than one address is provided, the DUA may choose to
 539           either accept the order provided, or choose to create its own
 540           order, based on what the DUA determines is the "best" order of
 541           servers to query.  For example, the DUA may choose to examine
 542           the server list and choose to query the DSAs in order based on
 543           the "closest" server or the server with the least amount of
 544           "load." Interpretation of the "best" server order is entirely
 545           up to the DUA, and not part of this document.
 546
 547           Once the order of server addresses is determined, the DUA
 548           contacts the DSA specified by the first server address in the
 549           list.  If that DSA is unavailable, the remaining DSAs SHOULD
 550           be queried until an available DSA is found or no more DSAs are
 551           available.  If a server address or port is invalid, the DUA
 552           SHOULD proceed to the next server address as described just
 553           above.
 554
 555
 556
 557 Neal-Joslin                                                   [Page 10]
 558 \f
 559 Internet-Draft          DUA Configuration Schema              March 2005
 560
 561
 562      Syntax:
 563
 564           serverList       = hostport *(space [hostport])
 565
 566      Default Value:
 567
 568           If a defaultServerList attribute is not provided, the DUA MAY
 569           attempt to contact the same DSA that provided the
 570           configuration profile entry itself.  The default DSA is
 571           contacted only if the preferredServerList attribute is also
 572           not provided.
 573
 574      Other attribute notes:
 575
 576           This attribute is used in conjunction with the
 577           preferredServerList attribute.  Please see section 5.1.1 for
 578           additional implementation notes.  Determining how the DUA
 579           should query the DSAs also depends on the additional
 580           configuration attributes, credentialLevel,
 581           serviceCredentialLevel, bindTimeLimit,
 582           serviceAuthenticationMethod and authenticationMethod.  Please
 583           review section 5.2 for details on how a DUA should properly
 584           contact a DSA.
 585
 586      Example:
 587
 588           defaultServerList: 192.168.169.170 ldap1.mycorp.com
 589             ldap2:1389 [1080::8:800:200C:417A]:5912
 590
 591 5.1.3 Interpreting the defaultSearchBase attribute
 592
 593      Interpretation:
 594
 595           When a DUA needs to search the DSA for information, this
 596           attribute provides the base for the search.  This parameter
 597           can be overridden or appended by the serviceSearchDescriptor
 598           attribute.  See section 5.1.6.
 599
 600      Syntax:
 601
 602           Defined by OID 1.3.6.1.4.1.1466.115.121.1.12 [5]
 603
 604      Default Value:
 605
 606           There is no default value for the defaultSearchBase.  A DUA
 607           MAY define its own method for determining the search base, if
 608           the defaultSearchBase is not provided.
 609
 610
 611
 612
 613 Neal-Joslin                                                   [Page 11]
 614 \f
 615 Internet-Draft          DUA Configuration Schema              March 2005
 616
 617
 618      Other attribute notes:
 619
 620           This attribute is used in conjunction with the
 621           serviceSearchDescriptor attribute.  See section 5.1.6.
 622
 623      Example:
 624
 625           defaultSearchBase: dc=mycompany,dc=com
 626
 627 5.1.4 Interpreting the authenticationMethod attribute
 628
 629      Interpretation:
 630
 631           The authenticationMethod attribute defines an ordered list of
 632           LDAP bind methods to be used when attempting to contact a
 633           DSA[11].   The serviceAuthenticationMethod overrides this
 634           value for a particular service (see 5.1.15.)  Each method MUST
 635           be attempted in the order provided by the attribute, until a
 636           successful LDAP bind is performed ("none" is assumed to always
 637           be successful.) However the DUA MAY skip over one or more
 638           methods.  See section 5.2 for more information.
 639
 640             none   - The DUA does not perform an LDAP bind.
 641             simple - The DUA performs an LDAP simple bind.
 642             sasl   - The DUA performs an LDAP SASL[12] bind using the
 643                      specified SASL mechanism and options.
 644             tls    - The DUA performs an LDAP StartTLS operation
 645                      followed by the specified bind method (for more
 646                      information refer to section 5.1 of RFC 2830 [13]).
 647
 648      Syntax:
 649
 650           authMethod  = method *(";" method)
 651           method      = none | simple | sasl | tls
 652           none        = "none"
 653           simple      = "simple"
 654           sasl        = "sasl/" saslmech [ ":" sasloption ]
 655           sasloption  = "auth-conf" | "auth-int"
 656           tls         = "tls:" (none | simple | sasl)
 657           saslmech    = SASL mechanism name as defined in [18]
 658
 659           Note: Although multiple authentication methods may be
 660           specified in the syntax, at most one of each type is allowed.
 661           I.E. "simple;simple" is invalid.
 662
 663      Default Value:
 664
 665           If the authenticationMethod or serviceAuthenticationMethod
 666
 667
 668
 669 Neal-Joslin                                                   [Page 12]
 670 \f
 671 Internet-Draft          DUA Configuration Schema              March 2005
 672
 673
 674           (for that particular service) attributes are not provided, the
 675           DUA MAY choose to bind to the DSA using any method defined by
 676           the DUA.  However, if either authenticationMethod or
 677           serviceAuthenticationMethod are provided, the DUA MUST only
 678           use the methods specified.
 679
 680      Other attribute notes:
 681
 682           When using TLS, the string "tls:sasl/EXTERNAL" implies that
 683           two way (DSA and DUA) authentication is to be performed.  Any
 684           other TLS authentication method implies one way (DSA side
 685           credential) authentication.
 686
 687           Determining how the DUA should bind to the DSAs also depends
 688           on the additional configuration attributes, credentialLevel,
 689           serviceCredentialLevel, serviceAuthenticationMethod and
 690           bindTimeLimit.  Please review section 5.2 for details on how
 691           to properly bind to a DSA.
 692
 693      Example:
 694
 695           authenticationMethod: tls:simple;sasl/DIGEST-MD5
 696           (see [14])
 697
 698 5.1.5 Interpreting the credentialLevel attribute
 699
 700      Interpretation:
 701
 702           The credentialLevel attribute defines what type(s) of
 703           credential(s) the DUA MUST use when contacting the DSA.  The
 704           serviceCredentialLevel overrides this value for a particular
 705           service (5.1.16.)  The credentialLevel can contain more than
 706           one credential type, separated by white space.
 707
 708           anonymous - The DUA SHOULD NOT use a credential when binding
 709           to the DSA.
 710
 711           proxy - The DUA SHOULD use a known proxy identity when binding
 712           to the DSA.  A proxy identity is a specific credential that
 713           was created to represent the DUA.  This document does not
 714           define how the proxy user should be created, or how the DUA
 715           should determine what the proxy user's credential is.  This
 716           functionality is up to each implementation.
 717
 718           self - When the DUA is acting on behalf of a known identity,
 719           the DUA MUST attempt to bind to the DSA as that identity.  The
 720           DUA should contain methods to determine the identity of the
 721           user such that that identity can be authenticated by the
 722
 723
 724
 725 Neal-Joslin                                                   [Page 13]
 726 \f
 727 Internet-Draft          DUA Configuration Schema              March 2005
 728
 729
 730           directory server using the defined authentication methods.
 731
 732           If the credentialLevel contains more than one credential type,
 733           the DUA MUST use the credential types in the order specified.
 734           However, the DUA MAY skip over one or more credential types.
 735           As soon as the DUA is able to successfully bind to the DSA,
 736           the DUA SHOULD NOT attempt to bind using the remaining
 737           credential types.
 738
 739      Syntax:
 740
 741           credentialLevel   = level *(space level)
 742           level             = self | proxy | anonymous
 743           self              = "self"
 744           proxy             = "proxy"
 745           anonymous         = "anonymous"
 746
 747           Note: Although multiple credential levels may be specified in
 748           the syntax, at most one of each type is allowed.  Refer to
 749           implementation notes in section 5.2 for additional syntax
 750           requirements for the credentialLevel attribute.
 751
 752      Default Value:
 753
 754           If the credentialLevel attribute is not defined, the DUA
 755           SHOULD NOT use a credential when binding to the DSA (also
 756           known as anonymous.)
 757
 758      Other attribute notes:
 759
 760           Determining how the DUA should bind to the DSAs also depends
 761           on the additional configuration attributes,
 762           authenticationMethod, serviceAuthenticationMethod,
 763           serviceCredentialLevel and bindTimeLimit.  Please review
 764           section 5.2 for details on how to properly bind to a DSA.
 765
 766      Example:
 767
 768           credentialLevel: proxy anonymous
 769
 770 5.1.6 Interpreting the serviceSearchDescriptor attribute
 771
 772      Interpretation:
 773
 774           The serviceSearchDescriptor attribute defines how and where a
 775           DUA SHOULD search for information for a particular service.
 776           The serviceSearchDescriptor contains a serviceID, followed by
 777           one or more base-scope-filter triples.  These base-scope-
 778
 779
 780
 781 Neal-Joslin                                                   [Page 14]
 782 \f
 783 Internet-Draft          DUA Configuration Schema              March 2005
 784
 785
 786           filter triples are used to define searches only for the
 787           specific service.  Multiple base-scope-filters allow the DUA
 788           to search for data in multiple locations of the DIT.  Although
 789           this syntax is very similar to the LDAP URL[8], this draft
 790           requires the ability to supply multiple hosts as part of the
 791           configuration of the DSA.  In addition, an ordered list of
 792           search descriptors is required, which can not be specified by
 793           the LDAP URL.
 794
 795           In addition to the triples, serviceSearchDescriptor might also
 796           contain the DN of an entry that will contain an alternate
 797           profile.  The DSA SHOULD re-evaluate the alternate profile and
 798           perform searches as specified by that profile.
 799
 800           If the base, as defined in the serviceSearchDescriptor, is
 801           followed by the "," (ASCII 0x2C) character, this base is known
 802           as a relative base.  This relative base may be constructed of
 803           one or more RDN components.  The DUA MUST define the search
 804           base by appending the relative base with the
 805           defaultSearchBase.
 806
 807      Syntax:
 808
 809           serviceSearchList = serviceID ":" serviceSearchDesc
 810                               *(";" serviceSearchDesc)
 811           serviceSearchDesc = confReferral | searchDescriptor
 812           searchDescriptor  = [base] ["?" [scope] ["?" [filter]]]
 813           confReferral      = "ref:" DistinguishedName
 814           base              = DistinguishedName |
 815                               RelativeBaseName
 816           RelativeBaseName  = 1*(RelativeDistinguishedName ",")
 817           filter            = UTF-8 encoded string
 818
 819           If the base or filter contains the ";" (ASCII 0x3B) "?" (ASCII
 820           0x3F) """ (ASCII 0x22) or "\" (ASCII 0x5C) characters, those
 821           characters MUST be escaped (preceded with the "\" character.)
 822           Alternately the DN may be surrounded by quotes (ASCII 0x22.)
 823           Refer to RFC 2253, section 4.  If the base or filter are
 824           surrounded by quotes, only the """ character needs to be
 825           escaped.  Any character that is preceded by the "\" character,
 826           which does not need to be escaped results in both "\"
 827           character and the character itself.
 828
 829           The usage and syntax of the filter string MUST be defined by
 830           the DUA service.  A suggested syntax would be that as defined
 831           by RFC 2254.
 832
 833           If a DUA is performing a search for a particular service,
 834
 835
 836
 837 Neal-Joslin                                                   [Page 15]
 838 \f
 839 Internet-Draft          DUA Configuration Schema              March 2005
 840
 841
 842           which has a serviceSearchDescriptor defined, the DUA MUST set
 843           the base, scope and filter as defined.  Each base-scope-filter
 844           triple represents a single LDAP search operation.  If multiple
 845           base-scope-filter triples are provided in the
 846           serviceSearchDescriptor, the DUA SHOULD perform multiple
 847           search requests and in that case it MUST be in the order
 848           specified by the serviceSearchDescriptor.
 849
 850           FYI: Service search descriptors do not exactly follow the LDAP
 851           URL syntax [7].  The reasoning for this difference is to
 852           separate the host name(s) from the filter.  This allows the
 853           DUA to have a more flexible solution in choosing its DSA.
 854
 855      Default Values:
 856
 857           If a serviceSearchDescriptor, or an element their-of, is not
 858           defined for a particular service, the DUA SHOULD create the
 859           base, scope and filter as follows:
 860
 861             base   - Same as the defaultSearchBase or as
 862                      defined by the DUA service.
 863             scope  - Same as the defaultSearchScope or as
 864                      defined by the DUA service.
 865             filter - Use defaults as defined by DUAs service.
 866
 867           If the defaultSearchBase or defaultSearchScope are not
 868           defined, then the DUA service may use its own default.
 869
 870
 871      Other attribute notes:
 872
 873           If a serviceSearchDescriptor exists for a given service, the
 874           service MUST use at least one base-scope-filter triple in
 875           performing searches.  It SHOULD perform multiple searches per
 876           service if multiple base-scope-filter triples are defined for
 877           that service.
 878
 879           The details of how the "filter" is interpreted by each DUA's
 880           service is defined by that service.  This means the filter is
 881           NOT REQUIRED to be a legal LDAP filter [15].  Furthermore,
 882           determining how attribute and objectclass mapping affects that
 883           search filter MUST be defined by the service.  I.E. The DUA
 884           SHOULD specify if the attributes in the filter have assumed to
 885           already have been mapped, or if it is expected that attribute
 886           mapping (see 5.1.7) would be applied to the filter.  In
 887           general practice, implementation and usability suggests that
 888           attribute and objectclass mapping (sections 5.1.7 and 5.1.13)
 889           SHOULD NOT be applied to the filter defined in the
 890
 891
 892
 893 Neal-Joslin                                                   [Page 16]
 894 \f
 895 Internet-Draft          DUA Configuration Schema              March 2005
 896
 897
 898           serviceSearchDescriptor.
 899
 900           It is assumed the serviceID is unique to a given service
 901           within the scope of any DUA that might use the given profile.
 902
 903      Example:
 904
 905           defaultSearchBase: dc=mycompany,dc=com
 906
 907           serviceSearchDescriptor: email:ou=people,ou=org1,?
 908            one;ou=contractor,?one;
 909            ref:cn=profile,dc=mycompany,dc=com
 910
 911           In this example, the DUA MUST search in
 912           "ou=people,ou=org1,dc=mycompany,dc=com" first.  The DUA then
 913           SHOULD search in "ou=contractor,dc=mycompany,dc=com", and
 914           finally it SHOULD search other locations as specified in the
 915           profile described at "cn=profile,dc=mycompany,dc=com".  For
 916           more examples, see section 9.
 917
 918
 919 5.1.7 Interpreting the attributeMap attribute
 920
 921      Interpretation:
 922
 923           A DUA SHOULD perform attribute mapping for all LDAP operations
 924           performed for a service that has an attributeMap entry.
 925           Because attribute mapping is specific to each service within
 926           the DUA, a "serviceID" is required as part of the attributeMap
 927           syntax.  I.E. not all DUA services should necessarily perform
 928           the same attribute mapping.
 929
 930           Attribute mapping in general is expected be used to map
 931           attributes of similar syntaxes as specified by the service
 932           supported by the DUA.  However, a DUA is NOT REQUIRED to
 933           verify syntaxes of mapped attributes.  If the DUA does
 934           discover that the syntax of the mapped attribute does not
 935           match that of the original attribute, the DUA MAY perform
 936           translation between the original syntax and the new syntax.
 937           When DUAs do support attribute value translation, the list of
 938           capable translations SHOULD be documented in a description of
 939           the DUA service.
 940
 941      Syntax:
 942
 943           attributeMap      = serviceID ":" origAttribute "="
 944                               attributes
 945           origAttribute     = attribute
 946
 947
 948
 949 Neal-Joslin                                                   [Page 17]
 950 \f
 951 Internet-Draft          DUA Configuration Schema              March 2005
 952
 953
 954           attributes        = wattribute *( space wattribute )
 955           wattribute        = whsp newAttribute whsp
 956           newAttribute      = descr | "*NULL*"
 957           attribute         = descr
 958
 959           Values of the origAttribute are defined by and SHOULD be
 960           documented for the DUA service, as a list of known supported
 961           attributes.
 962
 963      Default Value:
 964
 965           By default, attributes that are used by a DUA service are not
 966           mapped unless mapped by the attributeMap attributes.  The DUA
 967           MUST NOT map an attribute unless it is explicitly defined by
 968           an attributeMap attribute.
 969
 970      Other attribute notes:
 971
 972           When an attribute is mapped to the special keystring "*NULL*",
 973           the DUA SHOULD NOT request that attribute from the DSA, when
 974           performing a search or compare request.  If the DUA is also
 975           capable of performing modification on the DSA, the DUA SHOULD
 976           NOT attempt to modify any attribute which has been mapped to
 977           "*NULL*".
 978
 979           It is assumed the serviceID is unique to a given service
 980           within the scope of the DSA.
 981
 982           A DUA SHOULD support attribute mapping.  If it does, the
 983           following additional rules apply:
 984
 985           1) The list of attributes that are allowed to be mapped SHOULD
 986           defined by and documented for the service.
 987
 988           2) Any supported translation of mapping from attributes of
 989           dissimilar syntax SHOULD also be defined and documented.
 990
 991           3) If an attribute may be mapped to multiple attributes the
 992           DSA SHOULD define a syntax or usage statement for how the new
 993           attribute value will be constructed.  Furthermore, the
 994           resulting translated syntax of the combined attributes MUST be
 995           the same as the attribute being mapped.
 996
 997           4) A DUA MUST support mapping of attributes using the
 998           attribute OID.  It SHOULD support attribute mapping based on
 999           the attribute name.
1000
1001           5) It is recommended that attribute mapping not be applied to
1002
1003
1004
1005 Neal-Joslin                                                   [Page 18]
1006 \f
1007 Internet-Draft          DUA Configuration Schema              March 2005
1008
1009
1010           parents of the target entries.
1011
1012           6) Attribute mapping is not recursive.  In other words, if an
1013           attribute has been mapped to a target attribute, that new
1014           target attribute MUST NOT be mapped to a third attribute.
1015
1016           7) A given attribute MUST only be mapped once for a given
1017           service.
1018
1019
1020      Example:
1021
1022           Suppose a DUA is acting on behalf of an email service.  By
1023           default the "email" service uses the "mail", "cn" and "sn"
1024           attributes to discover mail addresses.  However, the email
1025           service has been deployed in an environment that uses
1026           "employeeName" instead of "cn."  And also instead of using the
1027           "mail" attribute for email addresses, the "email" attribute is
1028           used for that purpose.  In this case, the attribute "cn" can
1029           be mapped to "employeeName," allowing the DUA to perform
1030           searches using the "employeeName" attribute as part of the
1031           search filter, instead of "cn".  And "mail" can be mapped to
1032           "email" when attempting to retrieve the email address.  This
1033           mapping is performed by adding the attributeMap attributes to
1034           the configuration profile entry as follows (represented in
1035           LDIF[16]):
1036
1037           attributeMap: email:cn=employeeName
1038           attributeMap: email:mail=email
1039
1040           As described above, the DUA MAY also map a single attribute to
1041           multiple attributes.  When mapping a single attribute to more
1042           than one attribute, the new syntax or usage of the mapped
1043           attribute must be intrinsically defined by the DUAs service.
1044
1045           attributeMap: email:cn=firstName lastName
1046
1047           In the above example, the DUA creates the new value by
1048           generating space separated string using the values of the
1049           mapped attributes.  In this case, a special mapping must be
1050           defined so that a proper search filter can be created.  For
1051           further information on this example, please refer to section
1052           9.
1053
1054           Another possibility for multiple attribute mapping might come
1055           in when constructing returned attributes.  For example,
1056           perhaps all email addresses are of a guaranteed syntax of
1057           "uid@domain".  And in this example, the uid and domain are
1058
1059
1060
1061 Neal-Joslin                                                   [Page 19]
1062 \f
1063 Internet-Draft          DUA Configuration Schema              March 2005
1064
1065
1066           separate attributes in the directory.  The email service may
1067           define that if the "mail" attribute is mapped to two different
1068           attributes, it will construct the email address as a
1069           concatenation of the uid and domain attributes, placing the
1070           "@" character between them.
1071
1072           attributeMap: email:mail=uid domain
1073
1074
1075 5.1.8 Interpreting the searchTimeLimit attribute
1076
1077      Interpretation:
1078
1079           The searchTimeLimit attribute defines the maximum time, in
1080           seconds, that a DUA SHOULD allow to perform a search request.
1081
1082      Syntax:
1083
1084           Defined by OID 1.3.6.1.4.1.1466.115.121.1.27. [5]
1085
1086      Default Value:
1087
1088           If the searchTimeLimit attribute is not defined or is zero,
1089           the search time limit is not enforced by the DUA.
1090
1091      Other attribute notes:
1092
1093           This time limit only includes the amount of time required to
1094           perform the LDAP search operation.  If other operations are
1095           required, those operations do not need to be considered part
1096           of the search time.  See bindTimeLimit for the LDAP bind
1097           operation.
1098
1099 5.1.9 Interpreting the bindTimeLimit attribute
1100
1101      Interpretation:
1102
1103           The bindTimeLimit attribute defines the maximum time, in
1104           seconds, that a DUA SHOULD allow to perform an LDAP bind
1105           request against each server on the preferredServerList or
1106           defaultServerList.
1107
1108      Syntax:
1109
1110           Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
1111
1112      Default Value:
1113
1114
1115
1116
1117 Neal-Joslin                                                   [Page 20]
1118 \f
1119 Internet-Draft          DUA Configuration Schema              March 2005
1120
1121
1122           If the bindTimeLimit attribute is not defined or is zero, the
1123           bind time limit is not enforced by the DUA.
1124
1125      Other attribute notes:
1126
1127           This time limit only includes the amount of time required to
1128           perform the LDAP bind operation.  If other operations are
1129           required, those operations do not need to be considered part
1130           of the bind time.  See searchTimeLimit for the LDAP search
1131           operation.
1132
1133 5.1.10 Interpreting the followReferrals attribute
1134
1135      Interpretation:
1136
1137           If set to TRUE, the DUA SHOULD follow any referrals if
1138           discovered.
1139
1140           If set to FALSE, the DUA MUST NOT follow referrals.
1141
1142      Syntax:
1143
1144           Defined by OID 1.3.6.1.4.1.1466.115.121.1.7. [5]
1145
1146      Default Value:
1147
1148           If the followReferrals attribute is not set or set to an
1149           invalid value the default value is TRUE.
1150
1151 5.1.11 Interpreting the dereferenceAliases attribute
1152
1153      Interpretation:
1154
1155           If set to TRUE, the DUA SHOULD enable alias dereferencing.
1156
1157           If set to FALSE, the DUA MUST NOT enable alias dereferencing.
1158
1159      Syntax:
1160
1161           Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.
1162
1163      Default Value:
1164
1165           If the dereferenceAliases attribute is not set or set to an
1166           invalid value the default value is TRUE.
1167
1168 5.1.12 Interpreting the profileTTL attribute
1169
1170
1171
1172
1173 Neal-Joslin                                                   [Page 21]
1174 \f
1175 Internet-Draft          DUA Configuration Schema              March 2005
1176
1177
1178      Interpretation:
1179
1180           The profileTTL attribute defines how often the DUA SHOULD re-
1181           load and reconfigure itself using the corresponding
1182           configuration profile entry.  The value is represented in
1183           seconds.  Once a DUA reloads the profile entry, it SHOULD re-
1184           configure itself with the new values.
1185
1186      Syntax:
1187
1188           Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.
1189
1190      Default Value:
1191
1192           If not specified the DUA MAY use its own reconfiguration
1193           policy.
1194
1195      Other attribute notes:
1196
1197           If the profileTTL value is zero, the DUA SHOULD NOT
1198           automatically re-load the configuration profile.
1199
1200 5.1.13 Interpreting the objectclassMap attribute
1201
1202      Interpretation:
1203
1204           A DUA MAY perform objectclass mapping for all LDAP operations
1205           performed for a service that has an objectclassMap entry.
1206           Because objectclass mapping is specific for each service
1207           within the DUA, a "serviceID" is required as part of the
1208           objectclassMap syntax.  I.E. Not all DUA services should
1209           necessarily perform the same objectclass mapping.
1210
1211           Objectclass mapping SHOULD be used in conjunction with
1212           attribute mapping to map the required schema by the service to
1213           an equivalent schema that is available in the directory.
1214
1215           Objectclass mapping may or may not be required by a DUA.
1216           Often, the objectclass attribute is used in search filters.
1217           If a service search descriptor is provided, it is expected
1218           that the search filter contains a "correct" search filter
1219           (though this is not a requirement,) which does not need to be
1220           re-mapped.  However, when the service search descriptor is not
1221           provided, and the default search filter for that service
1222           contains the objectclass attribute, that search filter SHOULD
1223           be re-defined by objectclass mapping.  If a default search
1224           filter is not used, it SHOULD be re-defined through the
1225           serviceSearchDescriptor.  If a serviceSearchDescriptor is
1226
1227
1228
1229 Neal-Joslin                                                   [Page 22]
1230 \f
1231 Internet-Draft          DUA Configuration Schema              March 2005
1232
1233
1234           defined for a particular service, it SHOULD NOT be re-mapped
1235           by either the objectclassMap or attributeMap values.
1236
1237           One condition where the objectclassMap SHOULD be used is when
1238           the DUA is providing gateway functionality.  In this case, the
1239           DUA is acting on behalf of another service, which may pass in
1240           a search filter itself.  In this type of DUA, the DUA may
1241           alter the search filter according to the appropriate
1242           attributeMap and objectclassMap values.  And in this case, it
1243           is also assumed that a serviceSearchDescriptor is not defined.
1244
1245      Syntax:
1246
1247           objectclassMap    = serviceID ":" origObjectclass "="
1248                               objectclass
1249           origObjectclass   = objectclass
1250           objectclass       = keystring
1251
1252           Values of the origObjectclass depend on the type of DUA
1253           Service using the objectclass mapping feature.
1254
1255      Default Value:
1256
1257           The DUA MUST NOT remap an objectclass unless it is explicitly
1258           defined by an objectclassMap attribute.
1259
1260      Other attribute notes:
1261
1262           A DUA SHOULD support objectclass mapping.  If it does, the DUA
1263           MUST support mapping of objectclasses using the objectclass
1264           OID.  It SHOULD support objectclass mapping based on the
1265           objectclass name.
1266
1267           It is assumed the serviceID is unique to a given service
1268           within the scope of the DSA.
1269
1270      Example:
1271
1272           Suppose a DUA is acting on behalf of an email service.  By
1273           default the "email" service uses the "mail", "cn" and "sn"
1274           attributes to discover mail addresses in entries created using
1275           inetOrgPerson objectclass[17].  However, the email service has
1276           been deployed in an environment that uses entries created
1277           using "employee" objectclass.  In this case, the attribute
1278           "cn" can be mapped to "employeeName", and "inetOrgPerson" can
1279           be mapped to "employee", allowing the DUA to perform LDAP
1280           operations using the entries that exist in the directory.
1281           This mapping is performed by adding attributeMap and
1282
1283
1284
1285 Neal-Joslin                                                   [Page 23]
1286 \f
1287 Internet-Draft          DUA Configuration Schema              March 2005
1288
1289
1290           objectclassMap attributes to the configuration profile entry
1291           as follows (represented in LDIF[16]):
1292
1293           attributeMap: email:cn=employeeName
1294           objectclassMap: email:inetOrgPerson=employee
1295
1296
1297 5.1.14 Interpreting the defaultSearchScope attribute
1298
1299      Interpretation:
1300
1301           When a DUA needs to search the DSA for information, this
1302           attribute provides the "scope" for the search.  This parameter
1303           can be overridden by the serviceSearchDescriptor attribute.
1304           See section 5.1.6.
1305
1306      Syntax:
1307
1308           scopeSyntax   = "base" | "one" | "sub"
1309
1310      Default Value:
1311
1312           The default value for the defaultSearchScope SHOULD be defined
1313           by the DUA service.  If the default search scope for a service
1314           is not defined then the scope SHOULD be for the DUA to perform
1315           a subtree search.
1316
1317
1318 5.1.15 Interpreting the serviceAuthenticationMethod attribute
1319
1320      Interpretation:
1321
1322           The serviceAuthenticationMethod attribute defines an ordered
1323           list of LDAP bind methods to be used when attempting to
1324           contact a DSA for a particular service.  Interpretation and
1325           use of this attribute is the same as 5.1.4, but specific for
1326           each service.
1327
1328      Syntax:
1329
1330           svAuthMethod    = service ":" method *(";" method)
1331
1332           Note: Although multiple authentication methods may be
1333           specified in the syntax, at most one of each type is allowed.
1334
1335      Default Value:
1336
1337           If the serviceAuthenticationMethod attribute is not provided,
1338
1339
1340
1341 Neal-Joslin                                                   [Page 24]
1342 \f
1343 Internet-Draft          DUA Configuration Schema              March 2005
1344
1345
1346           the authenticationMethod SHOULD be followed, or its default.
1347
1348      Other attribute notes:
1349
1350           Determining how the DUA should bind to the DSAs also depends
1351           on the additional configuration attributes, credentialLevel,
1352           serviceCredentialLevel and bindTimeLimit.  Please review
1353           section 5.2 for details on how to properly bind to a DSA.
1354
1355      Example:
1356
1357           serviceAuthenticationMethod: email:tls:simple;sasl/DIGEST-MD5
1358
1359
1360 5.1.16 Interpreting the serviceCredentialLevel attribute
1361
1362      Interpretation:
1363
1364           The serviceCredentialLevel attribute defines what type(s) of
1365           credential(s) the DUA SHOULD use when contacting the DSA for a
1366           particular service.  Interpretation and used of this attribute
1367           are the same as 5.1.5.
1368
1369      Syntax:
1370
1371           svCredentialLevel = service ":" level *(space level)
1372
1373           Refer to implementation notes in section 5.2 for additional
1374           syntax requirements for the credentialLevel attribute.
1375
1376           Note: Although multiple credential levels may be specified in
1377           the syntax, at most one of each type is allowed.
1378
1379      Default Value:
1380
1381           If the serviceCredentialLevel attribute is not defined, the
1382           DUA MUST examine the credentialLevel attribute, or follow its
1383           default if not provided.
1384
1385      Other attribute notes:
1386
1387           Determining how the DUA should bind to the DSAs also depends
1388           on the additional configuration attributes,
1389           serviceAuthenticationMethod, authenticationMethod and
1390           bindTimeLimit.  Please review section 5.2 for details on how
1391           to properly bind to a DSA.
1392
1393      Example:
1394
1395
1396
1397 Neal-Joslin                                                   [Page 25]
1398 \f
1399 Internet-Draft          DUA Configuration Schema              March 2005
1400
1401
1402           serviceCredentialLevel: email:proxy anonymous
1403
1404
1405 5.2 Binding to the Directory Server
1406
1407      The DUA SHOULD use the following algorithm when binding to the
1408      server:
1409
1410      for (clevel in credLevel) [see note 1]
1411        if (clevel is "anonymous")
1412          for (host in hostnames) [see note 2]
1413            if (server is responding)
1414              return success
1415          return failure
1416        else
1417          for (amethod in authMethod) [see note 3]
1418            if (amethod is none)
1419              for (host in hostnames)
1420                if (server is responding)
1421                  return success
1422              return failure
1423            else
1424              for (host in hostnames)
1425                authenticate using amethod and clevel
1426                if (authentication passed)
1427                  return success
1428      return failure
1429
1430      Note 1: The credLevel is a list of credential levels as defined
1431              in serviceCredentialLevel (section 5.1.16) for a given
1432              service.  If the serviceCredentialLevel is not defined,
1433              the DUA MUST examine the credentialLevel attribute.
1434
1435      Note 2: hostnames is the list of servers to contact as defined
1436              in 5.1.1 & 5.1.2.
1437
1438      Note 3: The authMethod a list of authentication methods as defined
1439              in serviceAuthenticationMethod (section 5.1.15) for a
1440              given service.  If the serviceAuthenticationMethod is not
1441              defined, the DUA MUST examine the authenticationMethod
1442              attribute.
1443
1444
1445
1446 6.  Security Considerations
1447
1448      The profile entries MUST be protected against unauthorized
1449      modification.  Each service needs to consider implications of
1450
1451
1452
1453 Neal-Joslin                                                   [Page 26]
1454 \f
1455 Internet-Draft          DUA Configuration Schema              March 2005
1456
1457
1458      providing its service configuration as part of this profile and
1459      limit access to the profile entries accordingly.
1460
1461      The management of the authentication credentials for the DUA is
1462      outside the scope of this document and needs to be handled by the
1463      DUA.
1464
1465      Since the DUA needs to know how to properly bind to the directory
1466      server, the access control configuration of the DSA MUST assure
1467      that the DSA can view all the elements of the DUAConfigProfile
1468      attributes.  For example, if the credentialLevel attribute contains
1469      "Self" but the DSA is unable to access the credentialLevel
1470      attribute, the DUA will instead attempt an anonymous connection to
1471      the directory server.
1472
1473      The algorithm described by section 5.2 also has security
1474      considerations.  Altering that design will alter the security
1475      aspects of the configuration profile.
1476
1477
1478 7.  Acknowledgments
1479
1480      There were several additional authors of this document.  However we
1481      chose to represent only one author per company in the heading.
1482      From Sun we also would like to acknowledge Roberto Tam for his
1483      design work on Sun's first LDAP name service product and his input
1484      for this document.  From Hewlett-Packard we'd like to acknowledge
1485      Dave Binder for his work architecting Hewlett-Packard's LDAP name
1486      service product as well as his design guidance on this document.
1487      We'd also like to acknowledge Grace Lu from HP, for her input and
1488      implementation of HP's configuration profile manager code.
1489
1490
1491 8.  References
1492
1493 8.1 Normative References
1494
1495
1496 [4]  S. Bradner, "Key Words for use in RFCs to Indicate Requirement
1497      Levels", RFC 2119, March 1997.
1498
1499
1500 [5]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
1501      Access Protocol (v3): Attribute Syntax Definitions", RFC 2252,
1502      December 1997.
1503
1504
1505 [6]  M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
1506
1507
1508
1509 Neal-Joslin                                                   [Page 27]
1510 \f
1511 Internet-Draft          DUA Configuration Schema              March 2005
1512
1513
1514      (v3):  UTF-8 String Representation of Distinguished Names", RFC
1515      2253, December 1997.
1516
1517
1518 [7]  T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December 1997.
1519
1520
1521 [8]  R. Hinden, B. Carpenter, L. Masinter, "Uniform Resource Identifier
1522      (URI): Generic Syntax", RFC 3986, January 2005.
1523
1524
1525 [9]  M. Wahl, "A Summary of the X.500(96) User Schema for use with
1526      LDAPv3", RFC 2256, December 1997.
1527
1528
1529 [11] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication
1530      Methods for LDAP", RFC 2828, May 2000
1531
1532
1533 [13] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access
1534      Protocol [v3]: Extension for Transport Layer Security", RFC 2830,
1535      May 2000
1536
1537
1538 [18] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) MECHANISMS",
1539      http://www.iana.org/assignments/sasl-mechanisms, April 2004
1540
1541
1542 8.2 Informative References
1543
1544
1545 [1]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
1546      (v3)", RFC 2251, December 1997.
1547
1548
1549 [2]  L. Howard, "An Approach for Using LDAP as a Network Information
1550      Service", RFC 2307, March 1998.
1551
1552
1553 [3]  Microsoft Corporation, "Windows Services for Unix 3.5",
1554      http://www.microsoft.com/windows/sfu/default.asp
1555
1556
1557 [12] J. Meyers, "Simple Authentication and Security Layer [SASL]", RFC
1558      2222, October 1997
1559
1560
1561 [14] P. Leach, C. Newman, "Using Digest Authentication as a SASL
1562
1563
1564
1565 Neal-Joslin                                                   [Page 28]
1566 \f
1567 Internet-Draft          DUA Configuration Schema              March 2005
1568
1569
1570      Mechanism", RFC 2831, May 2000
1571
1572
1573 [15] T. Howes, "The String Representation of LDAP Search Filters", RFC
1574      2254, December 1997.
1575
1576
1577 [16] G. Good, "The LDAP Data Interchange Format (LDIF) - Technical
1578      Specification", RFC 2849, June 2000.
1579
1580
1581 [17] M. Smith, "Definition of the inetOrgPerson LDAP Object Class", RFC
1582      2789, April 2000
1583
1584
1585 9.  Examples
1586
1587      In this section we will describe a fictional DUA which provides one
1588      service, called the "email" service.  This service would be similar
1589      to an email client that uses an LDAP directory to discover email
1590      addresses based on a textual representation of the recipient's
1591      colloquial name.
1592
1593      This email service is defined by default to expect that users with
1594      email addresses will be of the "inetOrgPerson" objectclass type
1595      [17].  And by default, the "email" service expects the colloquial
1596      name to be stored in the "cn" attribute, while it expects the email
1597      address to be stored in the "mail" attribute (as one would expect
1598      as defined by the inetOrgPerson objectclass.)
1599
1600      As a special feature, the "email" service will perform a special
1601      type of attribute mapping, when performing searches.  If the "cn"
1602      attribute has been mapped to two or more attributes, the "email"
1603      service will parse the requested search string and map each white-
1604      space separated token into the mapped attributes, respectively.
1605
1606      The default search filter for the "email" service is
1607      "(objectclass=inetOrgPerson)".  The email service also defines that
1608      when it performs a name to address discovery, it will wrap the
1609      search filter inside a complex search filter as follows:
1610
1611      (&(<filter>)(cn~=<name string>)
1612
1613      or if "cn" has been mapped to multiple attributes, that wrapping
1614      would appear as follows:
1615
1616      (&(<filter>)(attr1~=<token1>)(attr2~=<token2>)...)
1617
1618
1619
1620
1621 Neal-Joslin                                                   [Page 29]
1622 \f
1623 Internet-Draft          DUA Configuration Schema              March 2005
1624
1625
1626      The below examples show how the "email" service builds it search
1627      requests, based on the defined profile.  In all cases, the
1628      defaultSearchBase is "o=airius.com" and the defaultSearchScope is
1629      undefined.
1630
1631      In addition, for all examples, we assume that the "email" service
1632      has been requested to discover the email address for "Jane
1633      Hernandez."
1634
1635
1636      Example 1:
1637
1638      serviceSearchDescriptor: email:"ou=marketing,"
1639
1640      base: ou=marketing,o=airius.com
1641      scope: sub
1642      filter: (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))
1643
1644      Example 2:
1645
1646      serviceSearchDescriptor: email:"ou=marketing,"?one?
1647       (&(objectclass=inetOrgPerson)(c=us))
1648      attributeMap: email:cn=2.5.4.42 sn
1649
1650      Note: 2.5.4.42 is the OID that represents the "givenName"
1651      attribute.
1652
1653      In this example, the email service performs <name string> parsing
1654      as described above to generate a complex search filter.  The above
1655      example results in one search.
1656
1657      base: ou=marketing,o=airius.com
1658      scope: one
1659      filter: (&(&(objectclass=inetOrgPerson)(c=us))
1660                  (2.5.4.42~=Jane)(sn~=Hernandez))
1661
1662      Example 3:
1663
1664      serviceSearchDescriptor: email:ou=marketing,"?base
1665      attributeMap: email:cn=name
1666
1667      This example is invalid, because either the quote should have been
1668      escaped, or there should have been a leading quote.
1669
1670      Example 4:
1671
1672      serviceSearchDescriptor: email:ou=\mar\\keting,\"?base
1673      attributeMap: email:cn=name
1674
1675
1676
1677 Neal-Joslin                                                   [Page 30]
1678 \f
1679 Internet-Draft          DUA Configuration Schema              March 2005
1680
1681
1682      base: ou=\mar\keting,"
1683      scope: base
1684      filter (&(objectclass=inetOrgPerson)(name~=Jane Hernandez))
1685
1686      Example 5:
1687
1688      serviceSearchDescriptor: email:ou="marketing",o=supercom
1689
1690      This example is invalid, since the quote was not a leading quote,
1691      and thus should have been escaped.
1692
1693      Example 6:
1694
1695      serviceSearchDescriptor: email:??(&(objectclass=person)
1696                                       (ou=Org1 \\(temporary\\)))
1697
1698      base: o=airius.com
1699      scope: sub
1700      filter: (&((&(objectclass=person)(ou=Org1 \(Temporary\)))
1701                (cn~=Jane Henderson)))
1702
1703      Example 7:
1704
1705      serviceSearchDescriptor: email:"ou=funny?org,"
1706
1707      base: ou=funny?org,o=airius.com
1708      scope: sub
1709      filter (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))
1710
1711
1712 Author's Addresses
1713
1714      Luke Howard
1715      PADL Software Pty. Ltd.
1716      PO Box 59
1717      Central Park Vic 3145
1718      Australia
1719
1720      EMail: lukeh@padl.com
1721
1722
1723      Bob Neal-Joslin
1724      Hewlett-Packard Company
1725      19420 Homestead RD  MS43-LF
1726      Cupertino, CA 95014
1727      USA
1728
1729      Phone: +1 408 447-3044
1730
1731
1732
1733 Neal-Joslin                                                   [Page 31]
1734 \f
1735 Internet-Draft          DUA Configuration Schema              March 2005
1736
1737
1738      EMail: bob_joslin@hp.com
1739
1740
1741      Morteza Ansari
1742      Infoblox
1743      475 Potrero Avenue
1744      Sunnyvale, CA 94085
1745      USA
1746
1747      Phone: +1 408-716-4300
1748      EMail: morteza@infoblox.com
1749
1750      Expires September 2005
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789 Neal-Joslin                                                   [Page 32]
1790 \f