From: http://www.ietf.org/internet-drafts/draft-sakimura-oauth-requrl-00.txt Title: Request by Reference ver.1.0 for OAuth 2.0 Reference: IETF Network Working Group, Internet Draft 'draft-sakimura-oauth-requrl' Date: June 17, 2010 Data Tracker: https://datatracker.ietf.org/doc/draft-sakimura-oauth-requrl/ Tracker Listing: http://ietfreport.isoc.org/idref/draft-sakimura-oauth-requrl/ Tools: http://tools.ietf.org/html/draft-sakimura-oauth-requrl-00 (HTML) Announced: http://www.ietf.org/mail-archive/web/i-d-announce/current/msg31486.html See also: IETF Open Authentication Protocol (OAuth) Working Group http://www.ietf.org/html.charters/oauth-charter.html IETF OAuth Working Group Status Pages http://tools.ietf.org/wg/oauth/ IETF OAuth Working Group Discussion List Archives http://www.ietf.org/mail-archive/web/oauth/current/maillist.html Bringing OAuth to the IETF (IETF Journal 5/1) http://xml.coverpages.org/newsletter/news2009-07-06.html#cite3 The OAuth Protocol: Authentication http://tools.ietf.org/html/draft-ietf-oauth-authentication The OAuth Protocol: Web Delegation http://tools.ietf.org/html/draft-ietf-oauth-web-delegation Evaluating OAUTH's Suitability for SIP Authentication http://tools.ietf.org/html/draft-beck-oauth-sip-eval Auth Access Tokens Using Credentials http://tools.ietf.org/html/draft-dehora-farrell-oauth-accesstoken-creds The OAuth 1.0 Protocol http://tools.ietf.org/html/draft-hammer-oauth OAuth Web Resource Authorization Profiles http://tools.ietf.org/html/draft-hardt-oauth Using OAuth for Recursive Delegation http://tools.ietf.org/html/draft-vrancken-oauth-redelegation ============================================================================== 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) , Nat Sakimura (NRI) , 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]