draft-joslin-config-schema-xx.txt

          If the bindTimeLimit attribute is not defined or is zero, the
          bind time limit is not enforced by the DUA.



Joslin                                                        [Page 18]

Internet-Draft          DUA Configuration Schema            October 2002


     Other attribute notes:

          This time limit only includes the amount of time required to
          perform the LDAP bind operation.  If other operations are
          required, those operations do not need to be considered part
          of the bind time.  See searchTimeLimit for the LDAP search
          operation.

5.1.10 Interpreting the followReferrals attribute

     Interpretation:

          If set to TRUE, the DUA SHOULD follow any referrals if
          discovered.

          If set to FALSE, the DUA MUST NOT follow referrals.

     Syntax:

          Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.

     Default Value:

          If the followReferrals attribute is not set or set to an
          invalid value the default value is TRUE.

5.1.11 Interpreting the dereferenceAliases attribute

     Interpretation:

          If set to TRUE, the DUA SHOULD enable alias dereferening.

          If set to FALSE, the DUA MUST NOT enable alias dereferencing.

     Syntax:

          Defined by OID 1.3.6.1.4.1.1466.115.121.1.7.

     Default Value:

          If the dereferenceAliases attribute is not set or set to an
          invalid value the default value is TRUE.

5.1.12 Interpreting the profileTTL attribute

     Interpretation:

          The profileTTL attribute defines how often the DUA SHOULD re-



Joslin                                                        [Page 19]

Internet-Draft          DUA Configuration Schema            October 2002


          load and reconfigure itself using the corresponding configura-
          tion profile entry.  The value is represented in seconds.
          Once a DUA reloads the profile entry, it SHOULD re-configure
          itself with the new values.

     Syntax:

          Defined by OID 1.3.6.1.4.1.1466.115.121.1.27.

     Default Value:

          If not specified the DUA MAY use its own reconfiguration pol-
          icy.

     Other attribute notes:

          If the profileTTL value is zero, the DUA SHOULD NOT automati-
          cally re-load the configuration profile.

5.1.13 Interpreting the objectclassMap attribute

     Interpretation:

          A DUA MAY perform objectclass mapping for all LDAP operations
          performed for a service that has an objectclassMap entry.
          Because objectclass mapping is specific for each service
          within the DUA, a "serviceID" is required as part of the
          objectclassMap syntax.  I.E. Not all DUA services should
          necessarily perform the same objectclass mapping.

          Objectclass mapping SHOULD be used in conjunction with attri-
          bute mapping to map the required schema by the service to an
          equivalent schema that is available in the directory.

          Objectclass mapping may or may not be required by a DUA.  In
          general, the objectclass attribute is used primarily in search
          filters.  If a service search descriptor is provided, it is
          expected that the search filter contains a "correct" search
          filter (though this is not a requirement,) which does not need
          to be re-mapped.  However, when the service search descriptor
          is not provided, and the default search filter for that ser-
          vice contains the objectclass attribute, that search filter
          SHOULD be re-defined by objectclass mapping.  If a default
          search filter is not used, it SHOULD be re-defined through the
          serviceSearchDescriptor.  If a serviceSearchDescriptor is
          defined for a particular service, it SHOULD NOT be re-mapped
          by either the objectclassMap or attributeMap values.




Joslin                                                        [Page 20]

Internet-Draft          DUA Configuration Schema            October 2002


          One condition where the objectclassMap SHOULD be used is when
          the DUA is providing gateway functionality.  In this case, the
          DUA is acting on behalf of another service, which may pass in
          a search filter itself.  In this type of DUA, the DUA may
          alter the search filter according to the appropriate attribu-
          teMap and objectclassMap values.  And in this case, it is also
          assumed that a serviceSearchDescriptor is not defined.

     Syntax:

          objectclassMap    = serviceID ":" origObjectclass "="
                              objectclass
          origObjectclass   = objectclass
          objectclass       = keystring

          Values of the origObjectclass depend on the type of DUA Ser-
          vice using the objectclass mapping feature.

     Default Value:

          The DUA MUST NOT remap an objectclass unless it is explicitly
          defined by an objectclassMap attribute.

     Other attribute notes:

          A DUA SHOULD support objectclass mapping.  If it does, the DUA
          MUST support mapping of objectclasses using the objectclass
          OID.  It SHOULD support objectclass mapping based on the
          objectclass name.

          It is assumed the serviceID is unique to a given service
          within the scope of the DSA.

     Example:

          Suppose a DUA is acting on behalf of an email service.  By
          default the "email" service uses the "mail", "cn" and "sn"
          attributes to discover mail addresses in entries created using
          inetOrgPerson objectclass [16].  However, the email service
          has been deployed in an environment that uses entries created
          using "employee" objectclass.  In this case, the attribute
          "cn" can be mapped to "employeeName", and "inetOrgPerson" can
          be mapped to "employee", allowing the DUA to perform LDAP
          operations using the entries that exist in the directory.
          This mapping is performed by adding attributeMap and
          objectclassMap attributes to the configuration profile entry
          as follows (represented in LDIF[18]):




Joslin                                                        [Page 21]

Internet-Draft          DUA Configuration Schema            October 2002


          attributeMap: email:cn=employeeName
          objectclassMap: email:inetOrgPerson=employee


5.1.14 Interpreting the defaultSearchScope attribute

     Interpretation:

          When a DUA needs to search the DSA for information, this
          attribute provides the "scope" for the search.  This parameter
          can be overridden by the serviceSearchDescriptor attribute.
          See section 5.1.6.

     Syntax:

          scopeSyntax   = "base" | "one" | "sub"

     Default Value:

          The default value for the defaultSearchScope SHOULD be defined
          by the DUA service.  If the default search scope for a service
          is not defined then the scope SHOULD be for the DUA to perform
          a subtree search.


5.1.15 Interpreting the serviceAuthenticationMethod attribute

     Interpretation:

          The serviceAuthenticationMethod attribute defines an ordered
          list of LDAP bind methods to be used when attempting to con-
          tact a DSA for a particular service.  Interpretation and use
          of this attribute is the same as 5.1.4, but specific for each
          service.

     Syntax:

          svAuthMethod    = service ":" method *(";" method)

          Note: Although multiple authentication methods may be speci-
          fied in the syntax, at most one of each type is allowed.

     Default Value:

          If the serviceAuthenticationMethod attribute is not provided,
          the authenticationMethod SHOULD be followed, or its default.

     Other attribute notes:



Joslin                                                        [Page 22]

Internet-Draft          DUA Configuration Schema            October 2002


          Determining how the DUA should bind to the DSAs also depends
          on the additional configuration attributes, credentialLevel,
          serviceCredentialLevel and bindTimeLimit.  Please review sec-
          tion 5.2 for details on how to properly bind to a DSA.

     Example:

          serviceAuthenticationMethod: email:tls:simple;sasl/DIGEST-MD5


5.1.16 Interpreting the serviceCredentialLevel attribute

     Interpretation:

          The serviceCredentialLevel attribute defines what type(s) of
          credential(s) the DUA SHOULD use when contacting the DSA for a
          particular service.  Interpretation and used of this attribute
          are the same as 5.1.5.

     Syntax:

          svCredentialLevel = service ":" level *(space level)

          Refer to implementation notes in section 5.2 for additional
          syntax requirements for the credentialLevel attribute.

          Note: Although multiple credential levels may be specified in
          the syntax, at most one of each type is allowed.

     Default Value:

          If the serviceCredentialLevel attribute is not defined, the
          DUA MUST examine the credentialLevel attribute, or follow its
          default if not provided.

     Other attribute notes:

          Determining how the DUA should bind to the DSAs also depends
          on the additional configuration attributes, serviceAuthentica-
          tionMethod, authenticationMethod and bindTimeLimit.  Please
          review section 5.2 for details on how to properly bind to a
          DSA.

     Example:

          serviceCredentialLevel: email:proxy anonymous





Joslin                                                        [Page 23]

Internet-Draft          DUA Configuration Schema            October 2002


5.2 Binding to the Directory Server

     The DUA SHOULD use the following algorithm when binding to the
     server:

     for (clevel in credLevel) [see note 1]
       if (clevel is "anonymous")
         for (host in hostnames) [see note 2]
           if (server is responding)
             return success
         return failure
       else
         for (amethod in authMethod) [see note 3]
           if (amethod is none)
             for (host in hostnames)
               if (server is responding)
                 return success
             return failure
           else
             for (host in hostnames)
               authenticate using amethod and clevel
               if (authentication passed)
                 return success
     return failure

     Note 1: The credLevel is a list of credential levels as defined
             in serviceCredentialLevel (section 5.1.16) for a given
             service.  If the serviceCredentialLevel is not defined,
             the DUA MUST examine the credentialLevel attribute.

     Note 2: hostnames is the list of servers to contact as defined
             in 5.1.1 & 5.1.2.

     Note 3: The authMethod a list of authentication methods as defined
             in serviceAuthenticationMethod (section 5.1.15) for a
             given service.  If the serviceAuthenticationMethod is not
             defined, the DUA MUST examine the authenticationMethod
             attribute.



6.  Security Considerations

     The profile entries MUST be protected against unauthorized modifi-
     cation.  Since the profile is most useful if its content is avail-
     able broadly, it is recommended that the profile entries will be
     readable anonymously.  However, ultimately each service needs to
     consider implications of providing its service configuration as



Joslin                                                        [Page 24]

Internet-Draft          DUA Configuration Schema            October 2002


     part of this profile and limit access to the profile entries
     accordingly.  Additionally, the management of the authentication
     credentials for the DUA is outside the scope of this document and
     needs to be handled by the DUA.

     The algorithm described by section 5.2 also has security considera-
     tions.  Altering that design will alter the security aspectes of
     the configuration profile.


7.  Acknowledgments

     There were several additional authors of this document.  However we
     chose to represent only one author per company in the heading.
     From Sun we also would like to acknowledge Roberto Tam for his
     design work on Sun's first LDAP name service product and his input
     for this document.  From Hewlett-Packard we'd like to acknowledge
     Dave Binder for his work architecting Hewlett-Packard's LDAP name
     service product as well as his design guidance on this document.
     We'd also like to acknowledge Grace Lu from HP, for her input and
     implementation of HP's configuration profile manager code.


8.  References

[1]
     M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication
     Methods for LDAP", RFC 2828, May 2000

[2]
     M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
     Access Protocol (v3): Attribute Syntax Definitions", RFC 2252,
     December 1997.

[3]
     M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
     (v3):  UTF-8 String Representation of Distinguished Names", RFC
     2253, December 1997.

[4]
     T. Howes, "The String Representation of LDAP Search Filters", RFC
     2254, December 1997.

[5]
     T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December 1997.

[6]
     T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource



Joslin                                                        [Page 25]

Internet-Draft          DUA Configuration Schema            October 2002


     Locators (URL)", RFC 1738, December 1994.

[7]
     J. Meyers, "Simple Authentication and Security Layer [SASL]", RFC
     2222, October 1997

[8]
     M. Wahl, "A Summary of the X.500(96) User Schema for use with
     LDAPv3", RFC 2256, December 1997.

[9]
     T. Berners-Lee, R. Fielding, R. Fielding, "Uniform Resource Iden-
     tifiers (URI): Generic Syntax", RFC 2396, August 1998.

[10]
     R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6
     Addresses in URL's, RFC 2732, December 1999.

[11]
     P. Leach, C. Newman, "Using Digest Authentication as a SASL Mechan-
     ism", RFC 2831, May 2000

[12]
     J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto-
     col [v3]: Extension for Transport Layer Security", RFC 2830, May
     2000

[13]
     Microsoft Corporation, "Services for Unix 2.0",
     http://www.microsoft.com/WINDOWS2000/sfu/default.asp

[14]
     L. Howard, "An Approach for Using LDAP as a Network Information
     Service", RFC 2307, March 1998.

[15]
     S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
     els", RFC 2119, March 1997.

[16]
     M. Smith, "Definition of the inetOrgPerson LDAP Object Class", RFC
     2789, April 2000

[17]
     M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
     (v3)", RFC 2251, December 1997.

[18]



Joslin                                                        [Page 26]

Internet-Draft          DUA Configuration Schema            October 2002


     G. Good, "The LDAP Data Interchange Format (LDIF) - Technical
     Specification", RFC 2849, June 2000.


9.  Examples

     In this section we will describe a fictional DUA which provides one
     service, called the "email" service.  This service would be similar
     to an email client that uses an LDAP directory to discover email
     addresses based on a textual representation of the recipient's col-
     loquial name.

     This email service is defined by default to expect that users with
     email addresses will be of the "inetOrgPerson" objectclass type
     [16].  And by default, the "email" service expects the colloquial
     name to be stored in the "cn" attribute, while it expects the email
     address to be stored in the "mail" attribute (as one would expect
     as defined by the inetOrgPerson objectclass.)

     As a special feature, the "email" service will perform a special
     type of attribute mapping, when performing searches.  If the "cn"
     attribute has been mapped to two or more attributes, the "email"
     service will parse the requested search string and map each white-
     space separated token into the mapped attributes, respectively.

     The default search filter for the "email" service is
     "(objectclass=inetOrgPerson)".  The email service also defines that
     when it performs a name to address discovery, it will wrap the
     search filter inside a complex search filter as follows:

     (&(<filter>)(cn~=<name string>)

     or if "cn" has been mapped to multiple attributes, that wrapping
     would appear as follows:

     (&(<filter>)(attr1~=<token1>)(attr2~=<token2>)...)

     The below examples show how the "email" service builds it search
     requests, based on the defined profile.  In all cases, the
     defaultSearchBase is "o=airius.com" and the defaultSearchScope is
     undefined.

     In addition, for all examples, we assume that the "email" service
     has been requested to discover the email address for "Jane Hernan-
     dez."


     Example 1:



Joslin                                                        [Page 27]

Internet-Draft          DUA Configuration Schema            October 2002


     serviceSearchDescriptor: email:"ou=marketing,"

     base: ou=marketing,o=airius.com
     scope: sub
     filter: (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))

     Example 2:

     serviceSearchDescriptor: email:"ou=marketing,"?one?
      (&(objectclass=inetOrgPerson)(c=us))
     attributeMap: email:cn=2.5.4.42 sn

     Note: 2.5.4.42 is the OID that represents the "givenName"
     attribute.

     In this example, the email service performs <name string> parsing
     as described above to generate a complex search filter.  The above
     example results in one search.

     base: ou=marketing,o=airius.com
     scope: one
     filter: (&(&(objectclass=inetOrgPerson)(c=us))
                 (2.5.4.42~=Jane)(sn~=Hernandez))

     Example 3:

     serviceSearchDescriptor: email:ou=marketing,"?base
     attributeMap: email:cn=name

     This example is invalid, because either the quote should have been
     escaped, or there should have been a leading quote.

     Example 4:

     serviceSearchDescriptor: email:ou=\mar\\keting,\"?base
     attributeMap: email:cn=name

     base: ou=\mar\keting,"
     scope: base
     filter (&(objectclass=inetOrgPerson)(name~=Jane Hernandez))

     Example 5:

     serviceSearchDescriptor: email:ou="marketing",o=supercom

     This example is invalid, since the quote was not a leading quote,
     and thus should have been escaped.




Joslin                                                        [Page 28]

Internet-Draft          DUA Configuration Schema            October 2002


     Example 6:

     serviceSearchDescriptor: email:??(&(objectclass=person)
                                      (ou=Org1 \\(temporary\\)))

     base: o=airius.com
     scope: sub
     filter: (&((&(objectclass=person)(ou=Org1 \(Temporary\)))
               (cn~=Jane Henderson)))

     Example 7:

     serviceSearchDescriptor: email:"ou=funny?org,"

     base: ou=funny?org,o=airius.com
     scope: sub
     filter (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez))


10.  Author's Addresses

     Luke Howard
     PADL Software Pty. Ltd.
     PO Box 59
     Central Park Vic 3145
     Australia

     EMail: lukeh@padl.com


     Bob Joslin
     Hewlett-Packard Company
     19420 Homestead RD  MS43-LF
     Cupertino, CA 95014
     USA

     Phone: +1 408 447-3044
     EMail: bob_joslin@hp.com


     Morteza Ansari
     Sun Microsystems, Inc.
     901 San Antonio RD  MS MPK17-203
     Palo Alto, CA 94303
     USA

     Phone: +1 650 786-6178
     EMail: morteza.ansari@sun.com



Joslin                                                        [Page 29]

Internet-Draft          DUA Configuration Schema            October 2002





















































Joslin                                                        [Page 30]