Providing User Authentication Information to OAuth 2.0 Clients
draft-hunt-oauth-v2-user-a4c-03

OAuth Working Group                                         P. Hunt, Ed.
Internet-Draft                                                    Oracle
Intended status: Informational                                T. Nadalin
Expires: November 29, 2014                                      M. Jones
                                                               Microsoft
                                                            May 28, 2014

     Providing User Authentication Information to OAuth 2.0 Clients
                    draft-hunt-oauth-v2-user-a4c-03

Abstract

   This specification defines a way for OAuth 2.0 clients to verify the
   identity of the End-User and obtain consent based upon the
   authentication performed by an Authorization Server.  The
   interactions defined by this specification are intentionally
   compatible with the OpenID Connect protocol.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on November 29, 2014.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of

Hunt, et al.            Expires November 29, 2014               [Page 1]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Requirements Notation and Conventions  . . . . . . . . . .  3
     1.2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Authentication Messages  . . . . . . . . . . . . . . . . . . .  4
     2.1.  Authentication Request . . . . . . . . . . . . . . . . . .  4
     2.2.  Authentication Response  . . . . . . . . . . . . . . . . .  7
       2.2.1.  Error Responses  . . . . . . . . . . . . . . . . . . .  7
     2.3.  Token Request  . . . . . . . . . . . . . . . . . . . . . .  7
     2.4.  Token Response . . . . . . . . . . . . . . . . . . . . . .  8
   3.  Privacy Considerations . . . . . . . . . . . . . . . . . . . . 11
   4.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
     4.1.  OAuth Authorization Endpoint Response Types
           Registration . . . . . . . . . . . . . . . . . . . . . . . 11
       4.1.1.  Registry Contents  . . . . . . . . . . . . . . . . . . 11
     4.2.  OAuth Parameters Registration  . . . . . . . . . . . . . . 11
       4.2.1.  Registry Contents  . . . . . . . . . . . . . . . . . . 11
   5.  Security Considerations  . . . . . . . . . . . . . . . . . . . 12
   6.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
     7.1.  Normative References . . . . . . . . . . . . . . . . . . . 12
     7.2.  Informative References . . . . . . . . . . . . . . . . . . 13
   Appendix A.  Document History  . . . . . . . . . . . . . . . . . . 13
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14

Hunt, et al.            Expires November 29, 2014               [Page 2]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

1.  Introduction

   Section 4.1 of the OAuth 2.0 Authorization Framework [RFC6749]
   defines the Authorization Code Grant flow which defines a redirect
   flow, typically via a web browser, that enables confidential clients
   to obtain access and refresh tokens.  As part of this flow, resource
   owners are authenticated via the user agent so that their consent may
   be obtained.

   This document extends the OAuth 2.0 authorization request and
   response messages for the Authorization Code flow to also request
   authentication of the End-User and to return information about the
   authentication performed.  The interactions defined by this
   specification are intentionally compatible with the OpenID Connect
   [OpenID.Core] protocol.

   This specification does not define a resource owner profile
   information API.  It is assumed that other APIs such as the SCIM API
   [I-D.ietf-scim-api] or the OpenID Connect [OpenID.Core] UserInfo
   Endpoint could be used for this purpose.

1.1.  Requirements Notation and Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

1.2.  Terminology

   This specification uses the terms "Access Token", "Authorization
   Code", "Authorization Endpoint", "Authorization Grant",
   "Authorization Server", "Client", "Client Authentication", "Client
   Identifier", "Client Secret", "Grant Type", "Protected Resource",
   "Redirection URI", "Refresh Token", "Resource Owner", "Resource
   Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0
   [RFC6749], the terms "Claim", "Claim Name", "Claim Value", and "JSON
   Web Token (JWT)" defined by JSON Web Token (JWT)
   [I-D.ietf-oauth-json-web-token], the term "User Agent" defined by RFC
   2616 [RFC2616].

   This specification also defines the following terms:

   Authentication Request
      OAuth 2.0 Authorization Request using extension parameters and
      scopes defined by this specification to request that the End-User
      be authenticated by the Authorization Server to the Client.

Hunt, et al.            Expires November 29, 2014               [Page 3]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   Authentication Context
      Information that the Relying Party can require before it makes an
      entitlement decision with respect to an authentication response.
      Such context can include, but is not limited to, the actual
      authentication method used or level of assurance such as ISO/IEC
      29115 [ISO29115] entity authentication assurance level.

   Authentication Context Class
      Set of authentication methods or procedures that are considered to
      be equivalent to each other in a particular context.

   Authentication Context Class Reference
      Identifier for an Authentication Context Class.

   Authentication Method
      Specific means by which authentication is performed.  In some
      cases, more than one authentication method may be used for a
      single authentication event.

   Authentication Method Reference
      Identifier for an Authentication Method.

   End-User
      Human participant.

   ID Token
      JSON Web Token (JWT) [I-D.ietf-oauth-json-web-token] that contains
      Claims about the Authentication event.  It MAY contain other
      Claims.

   Issuer
      Entity that issues a set of Claims.

2.  Authentication Messages

   The Authorization Code Grant type is used in the same manner as
   defined in Section 4.1 of [RFC6749].  This specification extends the
   features available by making it possible for clients to request
   authentication as well as to obtain information about the
   authentication performed via the Authorization Code flow.

2.1.  Authentication Request

   In addition to the parameters defined in Section 4.1.1 of [RFC6749],
   the following additional parameters and parameter values are defined:

Hunt, et al.            Expires November 29, 2014               [Page 4]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   response_type
      REQUIRED.  OAuth 2.0 Response Type value that determines the
      authentication processing flow to be used, including what
      parameters are returned from the endpoints used.  Two
      "response_type" values are defined for use with this
      specification:

      code
         Use of this response type results in both an access token and
         an ID Token being returned from the token endpoint in exchange
         for an authorization code.

      code_id_token
         Use of this response type results in an ID Token but no access
         token being returned from the token endpoint in exchange for an
         authorization code.

   prompt
      OPTIONAL.  Space delimited, case sensitive list of ASCII string
      values that specifies whether the Authorization Server prompts the
      End-User for reauthentication and consent.  The defined values
      are:

      none
         The authorization server MUST NOT display any authentication or
         consent user interface pages.  An error is returned if the End-
         User is not already authenticated or the Client does not have
         pre-configured consent for the requested Claims or does not
         fulfill other conditions for processing.  This can be used as a
         method to check for existing authentication and/or consent.

      login
         Regardless of the current user authentication state, the
         Authorization Server SHOULD prompt the End-User for
         reauthentication.  If it cannot prompt the End-User, it MUST
         return an error.

      select_account
         The Authorization Server SHOULD prompt the End-User to select a
         user account.  This allows an End-User who has multiple
         accounts at the Authorization Server to select amongst the
         multiple accounts that they might have current sessions for.
         If it cannot prompt the End-User, it MUST return an error.

Hunt, et al.            Expires November 29, 2014               [Page 5]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   acr_values
      OPTIONAL.  Requested Authentication Context Class Reference
      values.  Space-separated string that specifies the "acr" values
      that the Authorization Server is being requested to use for
      processing this Authentication Request, with the values appearing
      in order of preference.  The Authentication Context Class
      satisfied by the authentication performed is returned as the "acr"
      Claim Value.

   amr_values
      OPTIONAL.  Requested Authentication Method Reference values.
      Space-separated string that specifies the "amr" values that the
      Authorization Server is being requested to use for processing this
      Authentication Request, with the values appearing in order of
      preference.  The Authentication Methods used for the
      authentication performed are returned as the "amr" Claim Value.

   min_alv
      OPTIONAL.  A value of "1", "2", "3", or "4".  The minimum
      requested authentication assurance level as defined by [ISO29115]
      (see also [NIST_SP-800-63-2]).  The value actually achieved is
      returned as the "acr" claim value, or if no defined authentication
      assurance level is achieved, either an "acr" claim SHOULD NOT be
      returned or it MAY be returned with the value "0".  When the
      "min_alv" request parameter is not used and the "acr_values"
      request parameter is not used, the authorization server MAY choose
      any authentication assurance level or use none.  The "min_alv" and
      "acr_values" request parameters MUST NOT both be used in the same
      request.

   ui_hint
      OPTIONAL.  A helpful text message that should be displayed to the
      End-User during the authentication process. [[ NOTE: It's not
      clear what the use case for this is or how internationalization of
      the string would be performed. ]]

   id_token_hint
      OPTIONAL.  ID Token previously issued by the Authorization Server
      being passed as a hint about the End-User's current or past
      authenticated session with the Client.  If the End-User identified
      by the ID Token is logged in or is logged in by the request, then
      the Authorization Server returns a positive response; otherwise,
      it SHOULD return an error, such as "login_required".  When
      possible, an "id_token_hint" SHOULD be present when "prompt=none"
      is used and an "invalid_request" error MAY be returned if it is
      not; however, the server SHOULD respond successfully when
      possible, even if it is not present.  The Authorization Server
      need not be listed as an audience of the ID Token when it is used

Hunt, et al.            Expires November 29, 2014               [Page 6]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

      as an "id_token_hint" value.

   For example, the client directs the User Agent to make the following
   HTTP request using TLS (with extra line breaks for display purposes
   only):

     GET /authenticate?
       response_type=code
       &client_id=s6BhdRkqt3
       &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
       &state=af0ifjsldkj
       &prompt=login
     Host: server.example.com

   The authorization server MUST:

   o  Perform the normal OAuth 2.0 authorization process,

   o  MAY elect not to request consent if no access token is to be
      issued (i.e. this is an authentication only request),

   o  MUST re-authenticate the End-User if "prompt" contains the
      parameter "login",

   o  MUST obtain consent from the End-User if "prompt" contains the
      parameter "consent", and

   o  MUST return an error if "prompt" contains "none" and the End-User
      is not currently authenticated.

2.2.  Authentication Response

   The response is identical to the one described in Section 4.1.2 of
   [RFC6749].

2.2.1.  Error Responses

   In addition to those defined in Section 4.1.2.1 of [RFC6749], an
   additional "error" type is defined.  The error value "login_required"
   MUST be returned after an authentication request parameter "prompt"
   is provided containing value "none" and the End-User is found to be
   currently unauthenticated.

2.3.  Token Request

   The token request is identical to the one described in Section 4.1.3
   of [RFC6749].  In cases where there is no associated resource API and
   an access token is not to be issued, the normal OAuth 2.0 token

Hunt, et al.            Expires November 29, 2014               [Page 7]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   request is still made.

2.4.  Token Response

   If the token request is valid and authorized, the authorization
   server issues an access token and optional refresh token as described
   in Section 5.1 of [RFC6749] when the "code" response type is used, or
   omits the access token and refresh token from the response when the
   "code_id_token" response type is used.  If the request client
   authentication failed or is invalid, the authorization server returns
   an error response as described in Section 5.2.

   In addition to the response parameters described in Section 5, a JSON
   Web Token (JWT) [I-D.ietf-oauth-json-web-token] known as an ID Token
   is returned using the "id_token" parameter containing the following
   claims:

   iss
      REQUIRED.  An identifier representing the issuer of the
      authentication.  This MAY be the authorization endpoint URL.

   sub
      REQUIRED.  An identifier for the authenticated subject.  The same
      identifier MUST be returned for the same authenticated End-User on
      the same Client ID.  The authenticated End-User's "sub" value MAY
      change for different Client ID values.

   aud
      REQUIRED.  Contains the Client ID of the client receiving the
      assertion as an audience value.  Other audience values MAY also be
      present.

   auth_time
      REQUIRED.  The time at which the End-User was authenticated,
      expressed in number of seconds from 1970-01-01T0:0:0Z as measured
      in UTC until the date/time.  See [RFC3339] for details regarding
      date/times in general and UTC in particular. "auth_time" MAY be a
      time earlier than when the ID Token was issued, as defined by
      "iat".

   iat
      REQUIRED.  The time at which the ID Token was issued, expressed in
      number of seconds from 1970-01-01T0:0:0Z as measured in UTC until
      the date/time.  See [RFC3339] for details regarding date/times in
      general and UTC in particular.

Hunt, et al.            Expires November 29, 2014               [Page 8]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   exp
      REQUIRED.  The time at which the ID Token expires, expressed in
      number of seconds from 1970-01-01T0:0:0Z as measured in UTC until
      the date/time.  See [RFC3339] for details regarding date/times in
      general and UTC in particular.  Note that "expires_in" refers to
      the access token lifespan whereas "exp" refers to the ID Token
      lifespan.

   acr
      OPTIONAL.  Authentication Context Class Reference.  String
      specifying an Authentication Context Class Reference value that
      identifies the Authentication Context Class that the
      authentication performed satisfied.  The value "0" indicates the
      End-User authentication did not meet the requirements of ISO/IEC
      29115 [ISO29115] level 1.  Authentication using a long-lived
      browser cookie, for instance, is one example where the use of
      "level 0" is appropriate.  An absolute URI or an RFC 6711
      [RFC6711] registered name SHOULD be used as the "acr" value.
      Parties using this claim will need to agree upon the meanings of
      the values used, which may be context-specific.  The "acr" value
      is a case sensitive string.

   amr
      OPTIONAL.  Authentication Methods References.  JSON array of
      strings that are identifiers for Authentication Methods used in
      the authentication.  For instance, values might indicate that both
      password and OTP authentication methods were used.  The definition
      of particular values to be used in the amr Claim is beyond the
      scope of this specification.  Parties using this claim will need
      to agree upon the meanings of the values used, which may be
      context-specific.  The "amr" value is an array of case sensitive
      strings.  The following is a list of defined Authentication Method
      Reference values:

      pwd
         Password authentication, either by user or service if
         client_secret is used.

      rsa
         If authentication was based on the proof of an rsa key.  This
         includes if authentication was performed by a self-signed JWT
         with a service owned x509 certificate.

      otp
         One time password.

Hunt, et al.            Expires November 29, 2014               [Page 9]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

      mfa
         Multiple factor authentication was used.  When this is used the
         other authentication methods will also be included.

      fed
         A federated authentication assertion (e.g.  JWT or SAML) was
         used.

   A non-normative example successful response with an ID Token follows
   (with line breaks within lines for readability):

    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Cache-Control: no-store
    Pragma: no-cache

    {
     "access_token":"2YotnFZFEjr1zCsicMWpAA",
     "token_type":"example",
     "expires_in":3600,
     "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
     "id_token":"eyJhbGciOiJub25lIn0.
      eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjVkZWRjYz
      hiLTczNWMtNDA1Zi1lMDI5ZiIsImF1ZCI6InM2QmhkUmtxdDMiLCJhdXRoX3RpbWUi
      OjEzNjc5NTYwOTYsImlhdCI6MTM2Nzk1NjA5OCwiZXhwIjoxMzY4MDQyNDk2LCJhY3
      IiOiIyIiwiZXhhbXBsZV9leHRlbnNpb25fcGFyYW1ldGVyIjoiZXhhbXBsZV92YWx1
      ZSJ9."
    }

   As per the JWT specification, the encoded ID Token is separated into
   parts by the "." character.  The first part ("eyJhbGciOiJub25lIn0")
   contains the signature algorithm and in this case decodes as:
   {"alg":"none"}

   The claim set is then decoded as:

     {
      "iss":"https://server.example.com",
      "sub":"5dedcc8b-735c-405f-e029f",
      "aud":"s6BhdRkqt3",
      "auth_time":1367956096,
      "iat":1367956098,
      "exp":1368042496,
      "acr":"2",
      "example_extension_parameter":"example_value"
     }

   If the ID Token contains the claim "acr" and its value represents an

Hunt, et al.            Expires November 29, 2014              [Page 10]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   authentication level greater than "2", the ID Token MUST be signed
   (have a signature "alg" value other than "none") and its signature
   MUST be validated.

   All claims defined above MUST be understood before proceeding.
   Additional claims/parameters that are not understood MAY be ignored.

   The client MUST verify that the "auth_time" value is not future dated
   and "exp" is not a date currently in the past.

3.  Privacy Considerations

   Profile URL values issued in the ID Token and MAY be directed
   identifiers.  In other words, the identifier/URL returned is valid
   only for the "aud" indicated.  This prevents multiple clients and
   non-OAuth clients from being able to gather and correlate information
   about individuals authenticated by the OAuth Authorization Server.

4.  IANA Considerations

4.1.  OAuth Authorization Endpoint Response Types Registration

   This section registers the "response_type" values defined by this
   specification in the IANA OAuth Authorization Endpoint Response Types
   registry defined in RFC 6749 [RFC6749].

4.1.1.  Registry Contents

   o  Response Type Name: "code_id_token"
   o  Change Controller: IESG
   o  Specification Document(s): [[ this document ]]

4.2.  OAuth Parameters Registration

   This section registers the following parameters in the IANA OAuth
   Parameters registry defined in RFC 6749 [RFC6749].

4.2.1.  Registry Contents

   o  Parameter name: "amr_values"
   o  Parameter usage location: Authorization Request
   o  Change controller: IESG
   o  Specification document(s): [[ this document ]]
   o  Related information: None

Hunt, et al.            Expires November 29, 2014              [Page 11]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   o  Parameter name: "min_alv"
   o  Parameter usage location: Authorization Request
   o  Change controller: IESG
   o  Specification document(s): [[ this document ]]
   o  Related information: None

   o  Parameter name: "ui_hint"
   o  Parameter usage location: Authorization Request
   o  Change controller: IESG
   o  Specification document(s): [[ this document ]]
   o  Related information: None

5.  Security Considerations

   This draft carries the same risk profiles as those outlined in the
   Security Considerations for [RFC6749] and OAuth 2.0 Threat Model
   [RFC6819].

6.  Acknowledgements

   The authors wish to thank the members of the OAuth working group for
   their contributions and comments.

7.  References

7.1.  Normative References

   [I-D.ietf-oauth-json-web-token]
              Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", draft-ietf-oauth-json-web-token-20 (work in
              progress), April 2014.

   [ISO29115]
              Brackney, D., Ed. and E. NIST, Ed., "ISO/IEC 29115:2013
              Information technology -- Security techniques -- Entity
              authentication assurance framework", March 2013.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the

Hunt, et al.            Expires November 29, 2014              [Page 12]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

              Internet: Timestamps", RFC 3339, July 2002.

   [RFC6711]  Johansson, L., "An IANA Registry for Level of Assurance
              (LoA) Profiles", RFC 6711, August 2012.

   [RFC6749]  Hardt, D., "The OAuth 2.0 Authorization Framework",
              RFC 6749, October 2012.

7.2.  Informative References

   [I-D.ietf-scim-api]
              Hunt, P., Grizzle, K., Ansari, M., Wahlstroem, E., and C.
              Mortimore, "System for Cross-Domain Identity Management:
              Protocol", draft-ietf-scim-api-05 (work in progress),
              May 2014.

   [NIST_SP-800-63-2]
              Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, W.,
              Newton, S., and E. Nabbus, "DRAFT NIST Special Publication
              800-63-2: Electronic Authentication Guideline",
              August 2013.

   [OpenID.Core]
              Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
              C. Mortimore, "OpenID Connect Core 1.0", February 2014.

   [RFC6819]  Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
              Threat Model and Security Considerations", RFC 6819,
              January 2013.

Appendix A.  Document History

   [[ to be removed by the RFC editor before publication as an RFC ]]

   -03

   o  Defined the "code_id_token" response type value, which returns an
      ID Token from the token endpoint but returns no access token.

   o  Added the "id_token_hint" request parameter to enable
      reauthentication use cases.

   o  Unified the authentication level and authentication context class
      reference parameters.

   o  Requested the registration of new OAuth response type and
      parameter names with IANA.

Hunt, et al.            Expires November 29, 2014              [Page 13]
Internet-Draft        OAuth 2.0 User Authentication             May 2014

   -02

   o  Added the "amr_values" request parameter.

   o  Added the "acr" claim and the "acr_values" request parameter.

   o  Added terminology section.

   -01 - PJH 2013-08-15

   o  Added iat to contrast/clarify relation with lat attribute.

   o  Now returning session information as id_token.  Removed "display"
      parameter as not needed for authn only.  Added "min_alv"
      parameter.

   -00 - PJH 2013-04-09

   o  Initial version

Authors' Addresses

   Phil Hunt (editor)
   Oracle

   Email: phil.hunt@yahoo.com

   Tony Nadalin
   Microsoft

   Email: tonynad@microsoft.com

   Michael B. Jones
   Microsoft

   Email: mbj@microsoft.com
   URI:   http://self-issued.info/

Hunt, et al.            Expires November 29, 2014              [Page 14]