OAuth 2.0 Multiple Response Type Encoding Practices - draft 10

Abstract

This specification aims to provide guidance on proper encoding of responses to OAuth 2.0 Authorization Requests, where the request specifies a response type that includes space characters.

This specification also serves as the registration document for several specific new response types, in accordance with the stipulations of the OAuth Parameters Registry.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
    1.2.  Terminology
2.  Response Types and Response Modes
    2.1.  Response Modes
    2.2.  Multiple-Valued Response Types
3.  ID Token Response Type
4.  None Response Type
5.  Registration of Some Multiple-Valued Response Type Combinations
6.  IANA Considerations
    6.1.  OAuth Authorization Endpoint Response Types Registration
        6.1.1.  Registry Contents
    6.2.  OAuth Parameters Registration
        6.2.1.  Registry Contents
7.  Security Considerations
8.  Normative References
Appendix A.  "form_post" Response Mode Example
Appendix B.  Acknowledgements
Appendix C.  Notices
Appendix D.  Document History
§  Authors' Addresses

1.  Introduction

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 [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value.

1.2.  Terminology

This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. This specification also defines the following terms:

Client and Server

In the traditional client-server authentication model, the client requests an access restricted resource (Protected Resource) on the server by authenticating with the server using the Resource Owner's credentials.

Response Type

The Response Type determines what parameters are returned from the endpoints used. The Client informs the Authorization Server of the desired authorization processing flow using the response_type request parameter.

Response Mode

The Response Mode determines how the Authorization Server returns result parameters from the Authorization Endpoint. Non-default modes are specified using the response_mode request parameter. If response_mode is not present in a request, the default Response Mode mechanism specified by the Response Type is used.

Authorization Endpoint Response Types Registry

Process established by the OAuth 2.0 specification for the registration of new response_type parameters.

Multiple-Valued Response Types

The OAuth 2.0 specification allows for registration of space-separated response_type values. If a response type contains one of more space characters (%20), it is compared as a space-delimited list of values in which the order of values does not matter.

2.  Response Types and Response Modes

The Response Type request parameter response_type informs the Authorization Server of the desired authorization processing flow, including what parameters are returned from the endpoints used. The Response Mode request parameter response_mode informs the Authorization Server of the mechanism to be used when returning parameters from the Authorization Endpoint. Each Response Type value also defines a default Response Mode mechanism to be used, if no Response Mode is specified using the request parameter.

2.1.  Response Modes

This specification defines the following OAuth Authorization Request parameter:

response_mode

OPTIONAL. Informs the Authorization Server of the mechanism to be used when returning parameters from the Authorization Endpoint. This use of this parameter is NOT RECOMMENDED when the Response Mode that would be requested is the default mode specified by the Response Type.

This specification uses the following Response Modes and defines the associated response_mode values:

query

In this mode, response parameters are encoded in the query string added to the redirect_uri when redirecting back to the Client.

fragment

In this mode, response parameters are encoded in the fragment added to the redirect_uri when redirecting back to the Client.

form_post

In this mode, response parameters are encoded as HTML form values that are auto-submitted in the user-agent, and thus are transmitted via the HTTP POST method to the client, with the result parameters being encoded in the response body using the "application/x-www-form-urlencoded" format. The action attribute of the form MUST be the client's redirect URI. The method of the form attribute MUST be POST.

Any technique supported by the user agent MAY be used to cause the submission of the form, and any form content necessary to support this MAY be included, such as submit controls and client-side scripting commands. However, the client MUST be able to process the message without regard for the mechanism by which the form submission is initiated.

For purposes of this specification, the default Response Mode for the OAuth 2.0 code response_type is the query encoding. For purposes of this specification, the default Response Mode for the OAuth 2.0 token response_type is the fragment encoding.

Note that it is expected that additional Response Modes may be defined by other specifications in the future, including possibly postMessage and CORS.

2.2.  Multiple-Valued Response Types

When a multiple-valued response type is defined, it is RECOMMENDED that the following encoding rules be applied for the issued response from the Authorization Endpoint.

The all parameters returned from the Authorization Endpoint SHOULD use the same Response Mode. This recommendation applies to both success and error responses.

Rationale: This significantly simplifies Client parameter processing. It also can have positive performance benefits, as described below.

For instance, if a response includes fragment encoded parts, a User-Agent Client component must be involved to complete processing of the response. If a new query parameter is added to the Client URI, it will cause the User-Agent to re-fetch the Client URI, causing discontinuity of operation of the User-Agent based Client components. If only fragment encoding is used, the User-Agent will simply reactivate the Client component, which can then process the fragment and also convey any parameters to a Client host as necessary, e.g., via XmlHttpRequest. Therefore, full fragment encoding always results in lower latency for response processing.

3.  ID Token Response Type

This section registers a new response type, the id_token, in accordance with the stipulations in the OAuth 2.0 specification, Section 8.4. The intended purpose of the id_token is that it MUST provide an assertion of the identity of the Resource Owner as understood by the server. The assertion MUST specify a targeted audience, e.g. the requesting Client. However, the specific semantics of the assertion and how it can be validated are not specified in this document.

id_token

When supplied as the response_type parameter in an OAuth 2.0 Authorization Request, a successful response MUST include the parameter id_token. The Authorization Server SHOULD NOT return an OAuth 2.0 Authorization Code, Access Token, or Access Token Type in a successful response to the grant request. If a redirect_uri is supplied, the User-Agent SHOULD be redirected there after granting or denying access. The request MAY include a state parameter, and if so, the server MUST echo its value as a response parameter when issuing either a successful response or an error response. The default Response Mode for this Response Type is the fragment encoding and the query encoding MUST NOT be used. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

Returning the id_token in a fragment reduces the likelihood that the id_token leaks during transport and mitigates the associated risks to the privacy of the user (Resource Owner).

4.  None Response Type

This section registers the response type none, in accordance with the stipulations in the OAuth 2.0 specification, Section 8.4. The intended purpose is to enable use cases where a party requests the server to register a grant of access to a Protected Resource on behalf of a Client but requires no access credentials to be returned to the Client at that time. The means by which the Client eventually obtains the access credentials is left unspecified here.

One scenario is where a user wishes to purchase an application from a market, and desires to authorize application installation and grant the application access to Protected Resources in a single step. However, since the user is not presently interacting with the (not yet active) application, it is not appropriate to return access credentials simultaneously in the authorization step.

none

When supplied as the response_type parameter in an OAuth 2.0 Authorization Request, the Authorization Server SHOULD NOT return an OAuth 2.0 Authorization Code, Access Token, Access Token Type, or ID Token in a successful response to the grant request. If a redirect_uri is supplied, the User-Agent SHOULD be redirected there after granting or denying access. The request MAY include a state parameter, and if so, the server MUST echo its value as a response parameter when issuing either a successful response or an error response. The default Response Mode for this Response Type is the query encoding. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

The response type none SHOULD NOT be combined with other response types.

5.  Registration of Some Multiple-Valued Response Type Combinations

This section registers combinations of the values code, token, and id_token, which are each individually registered response types.

code token

When supplied as the value for the response_type parameter, a successful response MUST include an Access Token, an Access Token Type, and an Authorization Code. The default Response Mode for this Response Type is the fragment encoding and the query encoding MUST NOT be used. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

code id_token

When supplied as the value for the response_type parameter, a successful response MUST include both an Authorization Code and an id_token. The default Response Mode for this Response Type is the fragment encoding and the query encoding MUST NOT be used. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

id_token token

When supplied as the value for the response_type parameter, a successful response MUST include an Access Token, an Access Token Type, and an id_token. The default Response Mode for this Response Type is the fragment encoding and the query encoding MUST NOT be used. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

code id_token token

When supplied as the value for the response_type parameter, a successful response MUST include an Authorization Code, an id_token, an Access Token, and an Access Token Type. The default Response Mode for this Response Type is the fragment encoding and the query encoding MUST NOT be used. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

For all these Response Types, the request MAY include a state parameter, and if so, the server MUST echo its value as a response parameter when issuing either a successful response or an error response.

A non-normative request/response example as issued/received by the User-Agent (with extra line breaks for display purposes only) is:

  GET /authorize?
    response_type=id_token%20token
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &state=af0ifjsldkj HTTP/1.1
  Host: server.example.com

  HTTP/1.1 302 Found
  Location: https://client.example.org/cb#
  access_token=SlAV32hkKG
  &token_type=bearer
  &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
  &expires_in=3600
  &state=af0ifjsldkj

6.  IANA Considerations

6.1.  OAuth Authorization Endpoint Response Types Registration

This specification registers the response_type values defined by this specification in the IANA OAuth Authorization Endpoint Response Types registry [RFC6749] (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.).

6.1.1.  Registry Contents

• Response Type Name: id_token
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

• Response Type Name: none
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

• Response Type Name: code token
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

• Response Type Name: code id_token
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

• Response Type Name: id_token token
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

• Response Type Name: code id_token token
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

6.2.  OAuth Parameters Registration

This specification registers the following parameter in the IANA OAuth Parameters registry defined in RFC 6749 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

6.2.1.  Registry Contents

• Parameter name: response_mode
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 2.1 (Response Modes) of this document
• Related information: None

7.  Security Considerations

There are security implications to encoding response values in the query string. The HTTP Referer header includes query parameters, and so any values encoded in query parameters will leak to third parties. Thus, while it is safe to encode an Authorization Code as a query parameter when using a Confidential Client (because it can't be used without the Client Secret, which third parties won't have), more sensitive information such as Access Tokens and ID Tokens MUST NOT be encoded in the query string. In no case should a set of response parameters whose default Response Mode is the fragment encoding be encoded using the query encoding. However, it is safe to return response parameters whose default Response Mode is the fragment encoding using the form_post Response Mode.

8. Normative References

Appendix A.  "form_post" Response Mode Example

Below is a non-normative request/response/request example as issued/received/issued by the User-Agent (with extra line breaks for display purposes only) demonstrating an auto-submitted form_post encoded response:

Authorization Request to the Authorization Endpoint:

  GET /authorize?
   response_type=id_token
   &response_mode=form_post
   &client_id=some_client
   &scope=openid
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback
   &state=DcP7csa3hMlvybERqcieLHrRzKBra
   &nonce=2T1AgaeRTGTMAJyeDMN9IJbgiUG HTTP/1.1
  Host: server.example.com

After authentication and approval by the End-User, the Authorization Server issues the Authorization Response:

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

  <html>
   <head><title>Submit This Form</title></head>
   <body onload="javascript:document.forms[0].submit()">
    <form method="post" action="https://client.example.org/callback">
      <input type="hidden" name="state"
       value="DcP7csa3hMlvybERqcieLHrRzKBra"/>
      <input type="hidden" name="id_token"
       value="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiw
         iYXVkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLC
         Jpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjkwMzEiLCJpYXQiOjEzNjM5M
         DMxMTMsImV4cCI6MTM2MzkwMzcxMywibm9uY2UiOiIyVDFBZ2FlUlRHVE1B
         SnllRE1OOUlKYmdpVUciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0F
         NTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImF1dGhfdGltZSI6MTM2Mz
         kwMDg5NH0.c9emvFayy-YJnO0kxUNQqeAoYu7sjlyulRSNrru1ySZs2qwqq
         wwq-Qk7LFd3iGYeUWrfjZkmyXeKKs_OtZ2tI2QQqJpcfrpAuiNuEHII-_fk
         IufbGNT_rfHUcY3tGGKxcvZO9uvgKgX9Vs1v04UaCOUfxRjSVlumE6fWGcq
         XVEKhtPadj1elk3r4zkoNt9vjUQt9NGdm1OvaZ2ONprCErBbXf1eJb4NW_h
         nrQ5IKXuNsQ1g9ccT5DMtZSwgDFwsHMDWMPFGax5Lw6ogjwJ4AQDrhzNCFc
         0uVAwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA"/>
    </form>
   </body>
  </html>

Which results in an HTTP POST to the client:

  POST /callback HTTP/1.1
  Host: client.example.org
  Content-Type: application/x-www-form-urlencoded

  id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiwiYX
         VkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLCJpc
         3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjkwMzEiLCJpYXQiOjEzNjM5MDMx
         MTMsImV4cCI6MTM2MzkwMzcxMywibm9uY2UiOiIyVDFBZ2FlUlRHVE1BSnl
         lRE1OOUlKYmdpVUciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTD
         oyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImF1dGhfdGltZSI6MTM2MzkwM
         Dg5NH0.c9emvFayy-YJnO0kxUNQqeAoYu7sjlyulRSNrru1ySZs2qwqqwwq
         -Qk7LFd3iGYeUWrfjZkmyXeKKs_OtZ2tI2QQqJpcfrpAuiNuEHII-_fkIuf
         bGNT_rfHUcY3tGGKxcvZO9uvgKgX9Vs1v04UaCOUfxRjSVlumE6fWGcqXVE
         KhtPadj1elk3r4zkoNt9vjUQt9NGdm1OvaZ2ONprCErBbXf1eJb4NW_hnrQ
         5IKXuNsQ1g9ccT5DMtZSwgDFwsHMDWMPFGax5Lw6ogjwJ4AQDrhzNCFc0uV
         AwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA&
  state=DcP7csa3hMlvybERqcieLHrRzKBra

Appendix B.  Acknowledgements

The OpenID Community would like to thank the following people for the work they've done in the drafting and editing of this specification.

Naveen Agarwal (naa@google.com), Google

John Bradley (ve7jtb@ve7jtb.com), Ping Identity

Brian Campbell (bcampbell@pingidentity.com), Ping Identity

Michael B. Jones (mbj@microsoft.com), Microsoft

Breno de Medeiros (breno@google.com), Google

Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.

David Recordon (dr@fb.com), Facebook

Marius Scurtescu (mscurtescu@google.com), Google

Paul Tarjan (pt@fb.com), Facebook

Appendix C.  Notices

Copyright (c) 2013 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

Appendix D.  Document History

[[ To be removed from the final specification ]]

-10

• Differentiated between Response Types, which specify what is returned, and Response Modes, which specify how it is returned. Defined the response_mode request parameter for specifying non-default Response Modes.
• Defined the form_post Response Mode.
• Added Security Considerations section.

-09

• Clarified that the response types none and id_token do not return Authorization Code, Access Token, or Access Token Type values.
• Clarified that an Access Token Type value MUST be returned in the same cases that an Access Token is.
• Clarified that the state value must be included in both successful responses and error responses, when present in the request.
• Fixed #887 - Clarified the reasons that some parameters are described as "SHOULD be fragment encoded" and stated that these "MUST NOT be query encoded".

-08

• Corrected RFC 2119 keyword usage.

-07

• Fixed #817 - Removed duplicate definition of "Authorization Endpoint".
• Fixed #818 - Corrected HTTP GET example.

-06

• Added registry contents to IANA Considerations section
• Referenced OAuth 2.0 RFC -- RFC 6749

-05

• Changed client.example.com to client.example.org, per issue #251

-04

• Updated Notices

-03

• Use same section number structure as the OpenID Connect specs

-02

• Editorial corrections

-01

• Initial draft

Authors' Addresses