OAuth                                                 H. Tschofenig, Ed.
Internet-Draft                                    Nokia Siemens Networks
Updates:  6750 (if approved)                           February 18, 2013
Intended status:  Standards Track
Expires:  August 22, 2013


                    OAuth 2.0: Audience Information
                 draft-tschofenig-oauth-audience-00.txt

Abstract

   The OAuth 2.0 Bearer Token specification allows any party in
   possession of a bearer token to get access to the associated
   resources (without demonstrating possession of a cryptographic key).
   To prevent misuse, two important security assumptions must hold:
   bearer tokens must be protected from disclosure in storage and in
   transport and the access token must only be valid for use with a
   specific resource server (the audience) and with a specific scope.

   This document defines a new header that is used by the client to
   indicate what resource server, as the intended recipient, it wants to
   access.  This information is subsequently also communicated by the
   authorization server securely to the resource server, for example
   within the audience field of the access token.

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 August 22, 2013.

Copyright Notice

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




Tschofenig               Expires August 22, 2013                [Page 1]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


   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
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  Audience Parameter . . . . . . . . . . . . . . . . . . . . . .  5
   4.  Processing Instructions  . . . . . . . . . . . . . . . . . . .  6
   5.  Security Considerations  . . . . . . . . . . . . . . . . . . .  8
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  9
   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 10
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 11
     8.2.  Informative References . . . . . . . . . . . . . . . . . . 11
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12



























Tschofenig               Expires August 22, 2013                [Page 2]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


1.  Introduction

   The OAuth 2.0 Bearer Token specification [1] allows any party in
   possession of a bearer token to get access to the associated
   resources (without demonstrating possession of a cryptographic key).
   To prevent misuse, two important security assumptions must hold:
   bearer tokens must be protected from disclosure in storage and in
   transport and the access token must only be valid for use with a
   specific resource server with a specific scope.

   [1] describes this requirement in the following way:

      "To deal with token redirect, it is important for the
      authorization server to include the identity of the intended
      recipients (the audience), typically a single resource server (or
      a list of resource servers), in the token.  Restricting the use of
      the token to a specific scope is also RECOMMENDED."

   In general, if there is an authorization restriction then the
   respective parties must be aware of this restriction.  In our case,
   the respective parties are authorization server (who has a trust
   relationship with the resource owner to accept for reject requests
   for data sharing and creates the access token), the client (who
   initiates the access to the protected resource), and the resource
   server (who protects the access to the resource and grants only
   access to those clients who have been approved by the authorization
   server).

   Unfortunately, at the time of writing of [1] the access token format
   was still in early stages of the design and more details about how to
   communicate the audience information between the different parties
   was left unspecified.  This document defines a new field for usage
   with OAuth 2.0.  Note that it is not only useful for OAuth 2.0 bearer
   tokens but also for MAC tokens [5]:  the authorization server needs
   to be told which resource server has to obtain the session key
   securely in order for the security properties to hold.

   Restricting the usage of access tokens is important for several
   reasons:  First, a stolen access token cannot be used with resource
   servers it has not been created for.  Second, if the scope is
   included it cannot be used for requesting access to resources that
   exceed the indicated permissions.  A resource server, who obtains an
   access token legitimately, cannot access resources on behalf of the
   resource owner at other resource servers.







Tschofenig               Expires August 22, 2013                [Page 3]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


2.  Terminology

   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 [2].














































Tschofenig               Expires August 22, 2013                [Page 4]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


3.  Audience Parameter

   When the client interacts with the resource server it constructs the
   access token request to the token endpoint by adding the audience
   parameter using the "application/x-www-form-urlencoded" format with a
   character encoding of UTF-8 in the HTTP request entity-body.

   The audience URI MUST be an absolute URI as defined by Section 4.3 of
   [3].  It MAY include an "application/x-www-form-urlencoded" formatted
   query component (Section 3.4 of [3] ).  The URI MUST NOT include a
   fragment component.

   The ABNF syntax is defined as follows where by the "URI-reference"
   definition is taken from [3]:

   audience = URI-reference

      [QUESTION:  Is it OK to just assume a URI here as the audience
      identifier?]
































Tschofenig               Expires August 22, 2013                [Page 5]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


4.  Processing Instructions

      Step (0):  As an initial step the client typically determines the
      resource server it wants to interact with, for example, as part of
      a discovery procedure.

         [QUESTION:  Should we talk about WebFinger or SWD to be more
         specific?]

      Step (1):  The client starts the OAuth 2.0 protocol interaction
      based on the selected grant type.

      Step (2):  When the client interacts with the token endpoint to
      obtain an access token it MUST populate the newly defined
      'audience' parameter with the information obtained in step (0).

      Step (2):  The resource server who obtains the request needs to
      parse it to determine whether the provided audience value matches
      any of the authorized resource servers it has a relationship with.
      If the authorization server fails to parse the provided value it
      MUST reject the request using an error response with the error
      code "invalid_request".  If the authorization server does not
      consider the resource server acceptable then it MUST return an
      error response with the error code "access_denied".  In both cases
      additional error information may be provided via the
      error_description, and the error_uri parameters.  If the request
      has, however, been verified successfully then the authorization
      server MUST include the audience claim into the access token with
      the value copied from the audience field provided by the client.
      In case the access token is encoded using the JSON Web Token
      format [6] the "aud" claim MUST be used.  The access token MUST be
      protected against modification by protecting it with either a
      digital signature or a keyed message digest.  The authorization
      server returns the access token to the client, as specified in
      [4].

         [QUESTION:  Should we just focus on a JSON-based encoding of
         the access token since it is the only specified format?]

      Step (3):  The client follows the OAuth 2.0 specification [4] and
      the specification relevant for the selected token type (e.g., the
      bearer token specification) to interact with the resource server
      to make a request to the protected resource with the attached
      access token.

      Step (4):  When the resource server receives the access token it
      verifies it according to chosen access token encoding.  For
      example, in case the JSON Web Token format is used then it must



Tschofenig               Expires August 22, 2013                [Page 6]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


      adhere to the guidance in [6].  In any case, the resource server
      MUST verify whether the URI contained in the "aud" claim matches
      it's own.  If the comparison fails the resource server MUST return
      an error to the client.

         [NOTE:  More guidance is required in [6] regarding the matching
         procedure.]












































Tschofenig               Expires August 22, 2013                [Page 7]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


5.  Security Considerations

   The sole purpose of this document is to extend the OAuth 2.0 protocol
   to improve security.















































Tschofenig               Expires August 22, 2013                [Page 8]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


6.  IANA Considerations

   This document requires IANA to add a new value to the OAuth
   parameters registry:

   o  Parameter name:  audience

   o  Parameter usage location:  token request

   o  Change controller:  IETF

   o  Specification document(s):  [[This document.]







































Tschofenig               Expires August 22, 2013                [Page 9]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


7.  Acknowledgments

   The author would like to thank Leif Johansson, and Eve Maler for
   their feedback.















































Tschofenig               Expires August 22, 2013               [Page 10]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


8.  References

8.1.  Normative References

   [1]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework:
        Bearer Token Usage", RFC 6750, October 2012.

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

   [3]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
        Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
        January 2005.

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

8.2.  Informative References

   [5]  Richer, J., Mills, W., and H. Tschofenig, "OAuth 2.0 Message
        Authentication Code (MAC) Tokens",
        draft-ietf-oauth-v2-http-mac-02 (work in progress),
        November 2012.

   [6]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)",
        draft-ietf-oauth-json-web-token-06 (work in progress),
        December 2012.
























Tschofenig               Expires August 22, 2013               [Page 11]


Internet-Draft       OAuth 2.0: Audience Information       February 2013


Author's Address

   Hannes Tschofenig (editor)
   Nokia Siemens Networks
   Linnoitustie 6
   Espoo  02600
   Finland

   Phone:  +358 (50) 4871445
   Email:  Hannes.Tschofenig@gmx.net
   URI:    http://www.tschofenig.priv.at








































Tschofenig               Expires August 22, 2013               [Page 12]