[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 04 05 draft-ietf-oauth-jwsreq

Network Working Group                                        N. Sakimura
Internet-Draft                                 Nomura Research Institute
Intended status: Standards Track                           June 17, 2010
Expires: December 19, 2010


               Request by Reference ver.1.0 for OAuth 2.0
                     draft-sakimura-oauth-requrl-00

Abstract

   This document defines a simple mechanism of making request by
   reference in OAuth 2.0.  The reference is given as URL and request
   parameters are defined as JSON object which is pointed by the URL.

Requirements Language

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

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 December 19, 2010.

Copyright Notice

   Copyright (c) 2010 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



Sakimura                Expires December 19, 2010               [Page 1]


Internet-Draft              oauth-request_url                  June 2010


   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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3
   3.  Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
     3.1.  JSON OAuth Request  . . . . . . . . . . . . . . . . . . . . 4
     3.2.  Signed JSON OAuth Request . . . . . . . . . . . . . . . . . 4
     3.3.  Encrypted Format  . . . . . . . . . . . . . . . . . . . . . 5
   4.  Obtaining End-User Authorization  . . . . . . . . . . . . . . . 6
     4.1.  Authorization Server Response . . . . . . . . . . . . . . . 6
   5.  IANA  Considerations  . . . . . . . . . . . . . . . . . . . . . 7
   6.  Security Considerations . . . . . . . . . . . . . . . . . . . . 7
   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 7
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . 7
     8.1.  Normative References  . . . . . . . . . . . . . . . . . . . 7
     8.2.  Informative References  . . . . . . . . . . . . . . . . . . 8
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 8




























Sakimura                Expires December 19, 2010               [Page 2]


Internet-Draft              oauth-request_url                  June 2010


1.  Introduction

   An additional parameter 'request_url' is introduced as one of the
   request parameter of the flows of OAuth 2.0 [oauth2].

   There are a few cases that this is useful such as:

   1.  When the User Agent looks like it would not like long URLs - It
       is entirely possible that some extension makes a long URL.  For
       example, the client might want to send a public key with the
       request.

   2.  When the server wants the request non-repudiation - The server
       might want the request to be non-repudiable.  It is possible to
       sign the request dynamically, but a simpler way of doing it is to
       make a signed request file and put it on the client.  It can just
       be done by a client utility or something, so that the private key
       does not even have to reside on the server nor the client needs
       to program anything.

   3.  When the server wants the requests to be cacheable - If the
       request_url comes with sha256 hash as defined in FIPS180-2
       [FIPS180-2]of the file, the server knows if the file has changed
       without fetching it, so it does not have to re-fetch a same file,
       which is a win as well.

   4.  When the client wants to simplify the implementation without
       compromising the security If the request parameters go through
       the Browser, it may be tampered at the browser even if TLS was
       used.  This implies we need to have signature on the request as
       well.  However, if HTTPS request_url was used, it is not going to
       be tampered, thus we now do not have to sign the request.  This
       simplifies the implementation.


2.  Terminology

   Following parameter is defined as a request and response parameter.

   request_url  The absolute URL from which request parameters are
      obtained.

   Request File  This is a physical or logical file that the
      'request_url' points to.  It is in JSON format.  It MAY include
      all the potential variables including extension and non-oauth
      variables.  Request File can optionally be digitally signed.  To
      sign the request file, magic signatures [magic_signatures] is
      used.



Sakimura                Expires December 19, 2010               [Page 3]


Internet-Draft              oauth-request_url                  June 2010


3.  Formats

   There are several format that this document defines.

3.1.  JSON OAuth Request

   The OAuth authorization request parameters are included in the entity
   body of the HTTP response using the "application/json" media type as
   defined by JSON [RFC4627].  It MAY include any other parameters as
   well.  The parameters are serialized into a JSON structure by adding
   each parameter at the highest structure level.  Parameter names and
   string values are included as JSON strings.  Numerical values are
   included as JSON numbers.

   For example:

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
       "redirect_url":"https://example.com/rp/endpoint_url",
       "cliend_id":"http://example.com/rp/",
       "state":"ab890f0d"
   }

3.2.  Signed JSON OAuth Request

   To achieve non-repudiation and ascertained provenance of the JSON
   OAuth Request when it was obtained through unprotected channel, one
   MAY use asymmetric signature as in [magic_signatures] where
   parameters are as follows.

      "data_type":"application/json"

      "encoding":"base64url"

      "alg":"RSA-SHA256"

      "data":base64url encoded JSON representation of the assertion.

   This specification defines an additional parameter.

   o  certs_url

         Value: A URL from which one can retrieve PEM format X.509
         certificate.  It is used as the replacement of "keyhash".  Only
         either of the keyhash or certs_url MAY be used.  When certs_url
         was used, the processor MUST obtain the certificate from this



Sakimura                Expires December 19, 2010               [Page 4]


Internet-Draft              oauth-request_url                  June 2010


         URL and use public key contained in it to verify the signature.
         In addition, the processor MUST verify the domain of the
         "request_url" against the CN of the certificate.

   Any other variables can be included in any level of the JSON
   structure.  The processor MUST ignore the parameter that it does not
   understand.

   Following is the non-normative illustration of a signed response.
   (Note: Line wraps in the values are only for the display purpose.
   New lines MUST be escaped in JSON values.)
 {
   "data_type":"application/json",
   "encoding":"base64url",
   "alg":"RSA-SHA256",
   "data":"base64url encoded data without padding",
   "sigs": [
     {
     "value": "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76
     up8w63i2fWHvLKJzeGLKfyHg8ZomQ",
     "certs_url": "https://rp.example.com/certs.pem"
     }
   ]
 }

3.3.  Encrypted Format

   The HTTP response may be encrypted by the receiving party's public
   key for audience restriction and confidentiality.  If it is
   encrypted, the data is formatted as JSON Encryption Envelope
   [json_enc].  The following parameter MUST be set as follows:

   o  data_type - "http://openid.net/specs/ab/1.0#openid2json-enc"

   Following is a non-normative example of encrypted payload.

   {
       "class_id":"http://jsonenc.info/json-encryption/1.0/",
       "data_type":"http://openid.net/specs/ab/1.0#openid2json-enc",
       "enc_data":"b5guwzFgvrIUd7XcXI0bAFrg-....O69VKhY",
       "enc_type_asy":"http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p",
       "enc_type":"http://www.w3.org/2001/04/xmlenc#aes256-cbc",
       "enc_key":"mHM2ongmZlPVexe....2lsBNdw",
       "enc_iv":"_b4INfYIRwLPZdxB2L7wJg",
       "enc_ref":"https://rp.example.com/rpf_ax.json",
       "enc_thumbprint":"511e7a9cfe5eda16fa70f553c2dfa3c473e06423"
   }




Sakimura                Expires December 19, 2010               [Page 5]


Internet-Draft              oauth-request_url                  June 2010


4.  Obtaining End-User Authorization

   When the client is obtaining End-User Authorization as in Section 3
   of OAuth 2.0 [oauth2] , the client MAY use request_url instead of any
   but 'state' parameter.  The corresponding Request File MUST have all
   the necessary parameters which was to be queried in this request.
   When sending the request_url, the client MAY provide the sha256 hash
   as defined in FIPS180-2 [FIPS180-2]of the Request File as a fragment
   to it to assist the cache utilization decision of the Authorization
   Server.

   For example, the client directs the end-user's user-agent to make the
   following HTTPS request (line breaks are for display purposes only):

GET /authorize?request_url=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

   The Request File MAY be signed AND/OR encrypted.

   Upon receipt of 'requst_url' in the request, the authorization server
   MUST send a GET request to the 'request_url' to retrieve the content
   of the Request File unless it is already cached at the Authorization
   Server.

   If the response was signed AND/OR encrypted, it has to be decoded
   accordingly before being processed.

   Then, the Authorization Server MUST reconstruct the complete client
   request from the original HTTP request and the content of the Request
   File.  Then, the process continues as described in Section 3 of OAuth
   2.0 [oauth2] .

4.1.  Authorization Server Response

   Authorization Server Response is created and sent to the client as in
   Section 3.1 of OAuth 2.0 [oauth2] .

   In addition, this document defines additional 'error' values as
   follows:

   o  "invalid_request_url" - The provided request_url was not
      available.

   o  "invalid_request_file_format" - The Request File format was
      invalid.

   o  "invalid_request_params" - The parameter set provided in the
      Request File was invalid.



Sakimura                Expires December 19, 2010               [Page 6]


Internet-Draft              oauth-request_url                  June 2010


5.  IANA  Considerations

   This document makes no request of IANA.


6.  Security Considerations

   When obtaining the Request FIle, the Authorization Server SHOULD use
   either HTTP over TLS 1.2 as defined in RFC5246 [RFC5246] AND/OR
   Signed JSON Request.

   If the Request File contains personally identifiable or sensitive
   information, the "request_url" MUST be of one-time use and MUST have
   large enough entropy deemed necessary with applicable security
   policy.  For higher security requirement, using Encryption described
   in (Section 3.3) is strongly recommended.

   [[ToDo]]


7.  Acknowledgements

   Following people contributed to creating this document through the
   OpenID Artifact Binding 1.0 [openid_ab] .

   Breno de Medeiros (Google), Hideki Nara (TACT), John Bradley (Wingaa)
   <author>, Nat Sakimura (NRI) <author/editor>, Ryo Itou (Yahoo!
   Japan)

   Many people joined the discussion of the above at IIW and other
   occasions including Allen Tom (Yahoo!), George Fletcher (AOL), Dick
   Hardt (Independent) [[ToDo]]

   In addition following people contributed to this and previous
   versions through The OAuth Working Group.

   David Recordon (Facebook), Luke Shepard (Facebook), James H. Manger
   (Telstra), Marius Scurtescu (Google), John Panzer (Google), Dirk
   Balfanz (Google).


8.  References

8.1.  Normative References

   [FIPS180-2]
              U.S. Department of Commerce and National Institute of
              Standards and Technology, "Secure Hash Signature



Sakimura                Expires December 19, 2010               [Page 7]


Internet-Draft              oauth-request_url                  June 2010


              Standard", FIPS 180-2.

              Defines Secure Hash Algorithm 256 (SHA256)

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

   [RFC4627]  Crockford, D., "The application/json Media Type for
              JavaScript Object Notation (JSON)", RFC 4627, July 2006.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

   [json_enc]
              Bradeley, J. and N. Sakimura, "JSON Encryption Envelope",
              February 2010.

   [magic_signatures]
              Panzer, J. and B. Laurie, "Magic Signatures",
              February 2010.

   [oauth2]   Hammer-Lahav, E., "The OAuth 2.0 Protocol", June 2010.

8.2.  Informative References

   [openid_ab]
              openid-specs-ab@openid.net, "OpenID Artifact Binding 1.0",
              June 2010.


Author's Address

   Nat Sakimura
   Nomura Research Institute
   1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg.
   Chiyoda-ku, Tokyo  100-0005
   Japan

   Phone: +81-3-5533-2111
   Email: n-sakimura@nri.co.jp











Sakimura                Expires December 19, 2010               [Page 8]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/