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.
1.1. Requirements Notation and Conventions
2. Response Types and Response Encodings
2.1. Response Encodings
3. Multiple-Valued Response Types
4. ID Token Response Type
5. None Response Type
6. Registration of Some Multiple-Valued Response Type Combinations
7. IANA Considerations
7.1. OAuth Authorization Endpoint Response Types Registration
7.1.1. Registry Contents
7.2. OAuth Parameters Registration
7.2.1. Registry Contents
8. Security Considerations
9. Normative References
Appendix A. POST Response Encoding Example
Appendix B. Acknowledgements
Appendix C. Notices
Appendix D. Document History
§ Authors' Addresses
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.
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 Client informs the Authorization Server of the desired authorization processing flow using the response_type request parameter. This determines what parameters are returned from the endpoints used.
- Response Encoding
- The Client informs the Authorization Server of how parameters are to be returned from the Authorization Endpoint. Non-default encodings are specified using the response_encoding request parameter. If response_encoding is not present in a request, the default Response Encoding mechanism specified by the Response Type is used.
- Authorization Endpoint Response Type 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.
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 Encoding request parameter response_encoding 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 Authorization Encoding mechanism to be used, if no Authorization Encoding is specified using the request parameter.
This specification defines the following OAuth Authorization Request parameter:
- 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 Encoding that would be requested is the default encoding specified by the Response Type.
This specification uses the following Response Encodings and defines the associated response_encoding values:
- In this encoding, response parameters are encoded in the query string added to the redirect_uri when redirecting back to the Client.
- In this encoding, response parameters are encoded in the fragment added to the redirect_uri when redirecting back to the Client.
- In this encoding, 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. 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 Encoding for the OAuth 2.0 code response_type is the query encoding. For purposes of this specification, the default Response Encoding for the OAuth 2.0 token response_type is the fragment encoding.
Note that it is expected that additional Response Encodings may be defined by other specifications in the future, including possibly postMessage and CORS.
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 Encoding. 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.
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.
- 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 by adding it to the redirect_uri when issuing either a successful response or an error response. The default Response Encoding for this Response Type is the fragment encoding and the query encoding MUST NOT be used. This applies to both successful responses and error responses.
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).
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.
- 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 by adding it to the redirect_uri when issuing either a successful response or an error response. The default Response Encoding for this Response Type is the query encoding. This applies to both successful responses and error responses.
The response type none SHOULD NOT be combined with other response types.
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 Encoding for this Response Type is the fragment encoding and the query encoding MUST NOT be used. This applies to both successful responses and error responses.
- 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 Encoding for this Response Type is the fragment encoding and the query encoding MUST NOT be used. This applies to both successful responses and error responses.
- 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 Encoding for this Response Type is the fragment encoding and the query encoding MUST NOT be used. This applies to both successful responses and error responses.
- 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 Encoding for this Response Type is the fragment encoding and the query encoding MUST NOT be used. This applies to both successful responses and error responses.
For all these Response Types, the request MAY include a state parameter, and if so, the server MUST echo its value by adding it to the redirect_uri 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
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.).
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].
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 Encoding is the fragment encoding be encoded using the query encoding. However, it is safe to encode response parameters whose default Response Encoding using the POST encoding.
|[RFC2119]||Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).|
|[RFC6749]||Hardt, D., “The OAuth 2.0 Authorization Framework,” RFC 6749, October 2012 (TXT).|
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 POST encoded response:
Authorization Request to the Authorization Endpoint:
GET /authorize? response_type=id_token &response_encoding=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:
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
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 (firstname.lastname@example.org), Google
John Bradley (email@example.com), Ping Identity
Brian Campbell (firstname.lastname@example.org), Ping Identity
Michael B. Jones (email@example.com), Microsoft
Breno de Medeiros (firstname.lastname@example.org), Google
Nat Sakimura (email@example.com), Nomura Research Institute, Ltd.
David Recordon (firstname.lastname@example.org), Facebook
Marius Scurtescu (email@example.com), Google
Paul Tarjan (firstname.lastname@example.org), Facebook
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.
[[ To be removed from the final specification ]]
|Breno de Medeiros (editor)|
|Michael B. Jones|