OAuth 2.0 Multiple Response Type Encoding Practices - draft 10
Googlebreno@google.comhttp://stackoverflow.com/users/311376/brenoGooglemscurtescu@google.comhttps://twitter.com/mscurtescuFacebookpt@fb.comMicrosoftmbj@microsoft.comhttp://self-issued.info/OpenID Connect Working Group
This specification provides guidance on the proper encoding of responses to
OAuth 2.0 Authorization Requests in which the request uses a Response Type
value that includes space characters.
Furthermore, this specification registers several new Response Type values
in the OAuth Authorization Endpoint Response Types registry.
This specification also defines a
Response Mode Authorization Request parameter that
informs the Authorization Server of the mechanism to be used
for returning Authorization Response parameters from the Authorization Endpoint.
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.
In the .txt version of 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.
In the HTML version of this document,
values to be taken literally are indicated by
the use of this fixed-width font.
This specification uses the terms "Access Token", "Authorization Code",
"Authorization Endpoint", "Authorization Grant", "Authorization Server",
"Client", "Client Identifier", "Client Secret",
"Protected Resource", "Redirection URI", "Refresh Token",
"Resource Owner", "Resource Server", "Response Type", and "Token Endpoint"
defined by OAuth 2.0
and the term "User Agent" defined by RFC 2616.
This specification also defines the following terms:
The OAuth 2.0 specification allows
for registration of space-separated response_type parameter 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 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.
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
for returning Authorization Response 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.
This specification defines the following OAuth Authorization Request parameter:
OPTIONAL.
Informs the Authorization Server of the mechanism to be used
for returning Authorization Response 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 defines the following Response Modes, which are described
with their response_mode parameter values:
In this mode, Authorization Response parameters are encoded in
the query string added to the redirect_uri
when redirecting back to the Client.
In this mode, Authorization Response parameters are encoded in
the fragment added to the redirect_uri
when redirecting back to the Client.
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.
See OAuth 2.0 Form Post Response Mode
for an example of a specification that defines an additional Response Mode.
Note that it is expected that additional Response Modes 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 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.
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 Authorization 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
Authorization 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).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 Authorization 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
Authorization 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.
This section registers combinations of the values code, token, and id_token, which are each
individually registered Response Types.
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.
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.
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.
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
Authorization 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:
This specification registers the response_type
values defined by this specification in the IANA
OAuth Authorization Endpoint Response Types registry
defined in RFC 6749.
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
This specification registers the following parameter
in the IANA
OAuth Parameters registry
defined in RFC 6749.
Parameter name: response_modeParameter usage location: Authorization RequestChange controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.netSpecification document(s): of this documentRelated information: None
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 Authorization Response parameters whose default Response Mode
is the fragment encoding be encoded using the query encoding.
OAuth 2.0 Form Post Response ModeMicrosoftPing Identity
The OpenID Community would like to thank the following people for
their contributions to this specification:
Naveen Agarwal (naa@google.com), GoogleJohn Bradley (ve7jtb@ve7jtb.com), Ping IdentityBrian Campbell (bcampbell@pingidentity.com), Ping IdentityMichael B. Jones (mbj@microsoft.com), MicrosoftBreno de Medeiros (breno@google.com), GoogleNat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.David Recordon (dr@fb.com), FacebookMarius Scurtescu (mscurtescu@google.com), GooglePaul Tarjan (pt@fb.com), FacebookCopyright (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 ]]
-10
Fixed #889 - 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.
Fixed #890 - Defined the form_post Response Mode.
Added Security Considerations section.
Moved the
form_post Response Mode definition to the
OAuth 2.0 Form Post Response Mode specification.
-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 sectionReferenced 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