source4/ldap_server/devdocs/rfc4532.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        K. Zeilenga
   8 Request for Comments: 4532                           OpenLDAP Foundation
   9 Category: Standards Track                                      June 2006
  10
  11
  12               Lightweight Directory Access Protocol (LDAP)
  13                          "Who am I?" Operation
  14
  15 Status of This Memo
  16
  17    This document specifies an Internet standards track protocol for the
  18    Internet community, and requests discussion and suggestions for
  19    improvements.  Please refer to the current edition of the "Internet
  20    Official Protocol Standards" (STD 1) for the standardization state
  21    and status of this protocol.  Distribution of this memo is unlimited.
  22
  23 Copyright Notice
  24
  25    Copyright (C) The Internet Society (2006).
  26
  27 Abstract
  28
  29    This specification provides a mechanism for Lightweight Directory
  30    Access Protocol (LDAP) clients to obtain the authorization identity
  31    the server has associated with the user or application entity.  This
  32    mechanism is specified as an LDAP extended operation called the LDAP
  33    "Who am I?" operation.
  34
  35 1.  Background and Intent of Use
  36
  37    This specification describes a Lightweight Directory Access Protocol
  38    (LDAP) [RFC4510] operation that clients can use to obtain the primary
  39    authorization identity, in its primary form, that the server has
  40    associated with the user or application entity.  The operation is
  41    called the "Who am I?" operation.
  42
  43    This specification is intended to replace the existing Authorization
  44    Identity Controls [RFC3829] mechanism, which uses Bind request and
  45    response controls to request and return the authorization identity.
  46    Bind controls are not protected by security layers established by the
  47    Bind operation that includes them.  While it is possible to establish
  48    security layers using StartTLS [RFC4511][RFC4513] prior to the Bind
  49    operation, it is often desirable to use security layers established
  50    by the Bind operation.  An extended operation sent after a Bind
  51    operation is protected by the security layers established by the Bind
  52    operation.
  53
  54
  55
  56
  57
  58 Zeilenga                    Standards Track                     [Page 1]
  59 \f
  60 RFC 4532               LDAP "Who am I?" Operation              June 2006
  61
  62
  63    There are other cases where it is desirable to request the
  64    authorization identity that the server associated with the client
  65    separately from the Bind operation.  For example, the "Who am I?"
  66    operation can be augmented with a Proxied Authorization Control
  67    [RFC4370] to determine the authorization identity that the server
  68    associates with the identity asserted in the Proxied Authorization
  69    Control.  The "Who am I?" operation can also be used prior to the
  70    Bind operation.
  71
  72    Servers often associate multiple authorization identities with the
  73    client, and each authorization identity may be represented by
  74    multiple authzId [RFC4513] strings.  This operation requests and
  75    returns the authzId that the server considers primary.  In the
  76    specification, the term "the authorization identity" and "the
  77    authzId" are generally to be read as "the primary authorization
  78    identity" and the "the primary authzId", respectively.
  79
  80 1.1.  Conventions Used in This Document
  81
  82    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  83    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  84    document are to be interpreted as described in BCP 14 [RFC2119].
  85
  86 2.  The "Who am I?" Operation
  87
  88    The "Who am I?" operation is defined as an LDAP Extended Operation
  89    [RFC4511] identified by the whoamiOID Object Identifier (OID).  This
  90    section details the syntax of the operation's whoami request and
  91    response messages.
  92
  93       whoamiOID ::= "1.3.6.1.4.1.4203.1.11.3"
  94
  95 2.1.  The whoami Request
  96
  97    The whoami request is an ExtendedRequest with a requestName field
  98    containing the whoamiOID OID and an absent requestValue field.  For
  99    example, a whoami request could be encoded as the sequence of octets
 100    (in hex):
 101
 102       30 1e 02 01 02 77 19 80  17 31 2e 33 2e 36 2e 31
 103       2e 34 2e 31 2e 34 32 30  33 2e 31 2e 31 31 2e 33
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114 Zeilenga                    Standards Track                     [Page 2]
 115 \f
 116 RFC 4532               LDAP "Who am I?" Operation              June 2006
 117
 118
 119 2.2.  The whoami Response
 120
 121    The whoami response is an ExtendedResponse where the responseName
 122    field is absent and the response field, if present, is empty or an
 123    authzId [RFC4513].  For example, a whoami response returning the
 124    authzId "u:xxyyz@EXAMPLE.NET" (in response to the example request)
 125    would be encoded as the sequence of octets (in hex):
 126
 127       30 21 02 01 02 78 1c 0a  01 00 04 00 04 00 8b 13
 128       75 3a 78 78 79 79 7a 40  45 58 41 4d 50 4c 45 2e
 129       4e 45 54
 130
 131 3.  Operational Semantics
 132
 133    The "Who am I?" operation provides a mechanism, a whoami Request, for
 134    the client to request that the server return the authorization
 135    identity it currently associates with the client.  It also provides a
 136    mechanism, a whoami Response, for the server to respond to that
 137    request.
 138
 139    Servers indicate their support for this extended operation by
 140    providing a whoamiOID object identifier as a value of the
 141    'supportedExtension' attribute type in their root DSE.  The server
 142    SHOULD advertise this extension only when the client is willing and
 143    able to perform this operation.
 144
 145    If the server is willing and able to provide the authorization
 146    identity it associates with the client, the server SHALL return a
 147    whoami Response with a success resultCode.  If the server is treating
 148    the client as an anonymous entity, the response field is present but
 149    empty.  Otherwise, the server provides the authzId [RFC4513]
 150    representing the authorization identity it currently associates with
 151    the client in the response field.
 152
 153    If the server is unwilling or unable to provide the authorization
 154    identity it associates with the client, the server SHALL return a
 155    whoami Response with an appropriate non-success resultCode (such as
 156    operationsError, protocolError, confidentialityRequired,
 157    insufficientAccessRights, busy, unavailable, unwillingToPerform, or
 158    other) and an absent response field.
 159
 160    As described in [RFC4511] and [RFC4513], an LDAP session has an
 161    "anonymous" association until the client has been successfully
 162    authenticated using the Bind operation.  Clients MUST NOT invoke the
 163    "Who am I?" operation while any Bind operation is in progress,
 164    including between two Bind requests made as part of a multi-stage
 165
 166
 167
 168
 169
 170 Zeilenga                    Standards Track                     [Page 3]
 171 \f
 172 RFC 4532               LDAP "Who am I?" Operation              June 2006
 173
 174
 175    Bind operation.  Where a whoami Request is received in violation of
 176    this absolute prohibition, the server should return a whoami Response
 177    with an operationsError resultCode.
 178
 179 4.  Extending the "Who am I?" Operation with Controls
 180
 181    Future specifications may extend the "Who am I?" operation using the
 182    control mechanism [RFC4511].  When extended by controls, the "Who am
 183    I?" operation requests and returns the authorization identity the
 184    server associates with the client in a particular context indicated
 185    by the controls.
 186
 187 4.1.  Proxied Authorization Control
 188
 189    The Proxied Authorization Control [RFC4370] is used by clients to
 190    request that the operation it is attached to operate under the
 191    authorization of an assumed identity.  The client provides the
 192    identity to assume in the Proxied Authorization request control.  If
 193    the client is authorized to assume the requested identity, the server
 194    executes the operation as if the requested identity had issued the
 195    operation.
 196
 197    As servers often map the asserted authzId to another identity
 198    [RFC4513], it is desirable to request that the server provide the
 199    authzId it associates with the assumed identity.
 200
 201    When a Proxied Authorization Control is be attached to the "Who am
 202    I?"  operation, the operation requests the return of the authzId the
 203    server associates with the identity asserted in the Proxied
 204    Authorization Control.  The authorizationDenied (123) result code is
 205    used to indicate that the server does not allow the client to assume
 206    the asserted identity.
 207
 208 5.  Security Considerations
 209
 210    Identities associated with users may be sensitive information.  When
 211    they are, security layers [RFC4511][RFC4513] should be established to
 212    protect this information.  This mechanism is specifically designed to
 213    allow security layers established by a Bind operation to protect the
 214    integrity and/or confidentiality of the authorization identity.
 215
 216    Servers may place access control or other restrictions upon the use
 217    of this operation.  As stated in Section 3, the server SHOULD
 218    advertise this extension when it is willing and able to perform the
 219    operation.
 220
 221    As with any other extended operations, general LDAP security
 222    considerations [RFC4510] apply.
 223
 224
 225
 226 Zeilenga                    Standards Track                     [Page 4]
 227 \f
 228 RFC 4532               LDAP "Who am I?" Operation              June 2006
 229
 230
 231 6.  IANA Considerations
 232
 233    The OID 1.3.6.1.4.1.4203.1.11.3 is used to identify the LDAP "Who am
 234    I?" extended operation.  This OID was assigned [ASSIGN] by the
 235    OpenLDAP Foundation, under its IANA-assigned private enterprise
 236    allocation [PRIVATE], for use in this specification.
 237
 238    Registration of this protocol mechanism [RFC4520] has been completed
 239    by the IANA.
 240
 241    Subject: Request for LDAP Protocol Mechanism Registration
 242    Object Identifier: 1.3.6.1.4.1.4203.1.11.3
 243    Description: Who am I?
 244    Person & email address to contact for further information:
 245         Kurt Zeilenga <kurt@openldap.org>
 246    Usage: Extended Operation
 247    Specification: RFC 4532
 248    Author/Change Controller: IESG
 249    Comments: none
 250
 251 7.  Acknowledgement
 252
 253    This document borrows from prior work in this area, including
 254    "Authentication Response Control" [RFC3829] by Rob Weltman, Mark
 255    Smith, and Mark Wahl.
 256
 257    The LDAP "Who am I?" operation takes it's name from the UNIX
 258    whoami(1) command.  The whoami(1) command displays the effective user
 259    ID.
 260
 261 8.  References
 262
 263 8.1.  Normative References
 264
 265    [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
 266              Requirement Levels", BCP 14, RFC 2119, March 1997.
 267
 268    [RFC4370] Weltman, R., "Lightweight Directory Access Protocol (LDAP)
 269              Proxied Authorization Control", RFC 4370, February 2006.
 270
 271    [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol
 272              (LDAP): Technical Specification Road Map", RFC 4510, June
 273              2006.
 274
 275    [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access
 276              Protocol (LDAP): The Protocol", RFC 4511, June 2006.
 277
 278
 279
 280
 281
 282 Zeilenga                    Standards Track                     [Page 5]
 283 \f
 284 RFC 4532               LDAP "Who am I?" Operation              June 2006
 285
 286
 287    [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol
 288              (LDAP): Authentication Methods and Security Mechanisms",
 289              RFC 4513, June 2006.
 290
 291 8.2.  Informative References
 292
 293    [RFC3829] Weltman, R., Smith, M., and M. Wahl, "Lightweight Directory
 294              Access Protocol (LDAP) Authorization Identity Request and
 295              Response Controls", RFC 3829, July 2004.
 296
 297    [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
 298              Considerations for the Lightweight Directory Access
 299              Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
 300
 301    [ASSIGN]  OpenLDAP Foundation, "OpenLDAP OID Delegations",
 302              http://www.openldap.org/foundation/oid-delegate.txt.
 303
 304    [PRIVATE] IANA, "Private Enterprise Numbers",
 305              http://www.iana.org/assignments/enterprise-numbers.
 306
 307 Author's Address
 308
 309    Kurt D. Zeilenga
 310    OpenLDAP Foundation
 311
 312    EMail: Kurt@OpenLDAP.org
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338 Zeilenga                    Standards Track                     [Page 6]
 339 \f
 340 RFC 4532               LDAP "Who am I?" Operation              June 2006
 341
 342
 343 Full Copyright Statement
 344
 345    Copyright (C) The Internet Society (2006).
 346
 347    This document is subject to the rights, licenses and restrictions
 348    contained in BCP 78, and except as set forth therein, the authors
 349    retain all their rights.
 350
 351    This document and the information contained herein are provided on an
 352    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 353    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 354    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 355    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 356    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 357    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 358
 359 Intellectual Property
 360
 361    The IETF takes no position regarding the validity or scope of any
 362    Intellectual Property Rights or other rights that might be claimed to
 363    pertain to the implementation or use of the technology described in
 364    this document or the extent to which any license under such rights
 365    might or might not be available; nor does it represent that it has
 366    made any independent effort to identify any such rights.  Information
 367    on the procedures with respect to rights in RFC documents can be
 368    found in BCP 78 and BCP 79.
 369
 370    Copies of IPR disclosures made to the IETF Secretariat and any
 371    assurances of licenses to be made available, or the result of an
 372    attempt made to obtain a general license or permission for the use of
 373    such proprietary rights by implementers or users of this
 374    specification can be obtained from the IETF on-line IPR repository at
 375    http://www.ietf.org/ipr.
 376
 377    The IETF invites any interested party to bring to its attention any
 378    copyrights, patents or patent applications, or other proprietary
 379    rights that may cover technology that may be required to implement
 380    this standard.  Please address the information to the IETF at
 381    ietf-ipr@ietf.org.
 382
 383 Acknowledgement
 384
 385    Funding for the RFC Editor function is provided by the IETF
 386    Administrative Support Activity (IASA).
 387
 388
 389
 390
 391
 392
 393
 394 Zeilenga                    Standards Track                     [Page 7]
 395 \f