OpenID Connect - Part 4: JSON based Request 1.0 - draft 00

Abstract

While OAuth 2.0's Form Encoded requests are simple to code, it has a disadvantage that it is not being signed and thus pronte to the tampering. Also, no method to encrypt the payload is defined so the confidentiality of the request is not warranted.

This specification defines an alternative request format based on JSON Web Token. It can be signed and encrypted to achieve integrity, non-repudiation, and confidentiality. Since such requests are largely static, such a request can be created once and used many times.

Further, it defines a method that passes such request via reference. In this case, the signed request can be created once and registered to the server and the client can chose from one of them by specifying the URI of the request, making the request small as well as allowing the serverside optimization.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
2.  Terminology
3.  Authorization Request by JSON
    3.1.  Passing the Request Object by value
    3.2.  Passing the Request Object by Reference
        3.2.1.  "request_uri" Rationale
4.  Validation
    4.1.  Authorization Request Validation
        4.1.1.  Encrypted Request Object
        4.1.2.  Signed Request Object
        4.1.3.  Parameter Validation
5.  Authorization Error Response
6.  Security Considerations
7.  Privacy Considerations
8.  IANA Considerations
    8.1.  OAuth Parameters Registry
        8.1.1.  Registry Contents
    8.2.  OAuth Extensions Error Registry
        8.2.1.  Registry Contents
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

1.  Introduction

Once the Client obtained the Access Token through OpenID Connect Authentication, it MAY use it against a OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] Protected Resource called UserInfo Endpoint to obtain the information about the End-User.

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.

All uses of JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and JSON Web Encryption (JWE) (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.

2.  Terminology

This specification strives to make itself readable without constantly referring to the term definitions. Defined terms are shown with its first letters capitalized. When in doubt, refer to OpenID Connect Messages 1.0 for the authoritative definition of the defined terms.

3.  Authorization Request by JSON

This specification defines following OAuth 2.0 extension parameters to send the Authorization Request by JWT encoded JSON by value and by reference. If one of them is used, the other MUST NOT be used in the same request.

request

This parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be signed and optionally encrypted. The parameter value is a Request Object value, as specified in Section 3.1 (Passing the Request Object by value). It represents the request as a JWT whose Claims are the request parameters above.

When the request parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. Even if a scope parameter is present in the Request Object value, a scope parameter MUST always be passed using the OAuth 2.0 request syntax containing the openid scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request.

request_uri

This parameter enables OpenID Connect requests to be passed by reference, rather than by value. The request_uri value is a URL using the https scheme referencing a resource containing a Request Object value, which is a JWT containing the request parameters. This parameter is used identically to the request parameter, other than that the Request Object value is retrieved from the specified URL, rather than passed by value. See Section 3.2 (Passing the Request Object by Reference) for more information on using the request_uri parameter.

3.1.  Passing the Request Object by value

The request parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be signed and optionally encrypted. It represents the request as a JWT whose Claims are the request parameters to the Authorization Endpoint. This JWT is called a Request Object.

Support for the request parameter is OPTIONAL. The request_parameter_supported Discovery result indicates whether the OP supports this parameter. Should an OP not support this parameter and an RP uses it, the OP MUST return the request_not_supported error.

When the request parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. However, some parameters MAY be passed using the OAuth 2.0 request syntax even when a Request Object is used; this would typically be done to enable a cached, pre-signed (and possibly pre-encrypted) Request Object value to be used containing the fixed request parameters, while parameters that can vary with each request, such as state and nonce, are passed as OAuth 2.0 parameters.

Even if a scope parameter is present in the Request Object value, a scope parameter MUST always be passed using the OAuth 2.0 request syntax containing the openid scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request.

The Request Object MAY be signed or unsigned (plaintext). When it is plaintext, this is indicated by use of the none algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) in the JWS header. If signed, the Request Object SHOULD contain the Claims iss (issuer) and aud (audience) as members, with their semantics being as defined in the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification.

The Request Object MAY also be encrypted using JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE], with nested signing and encryption performed as described in the JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) specification.

request and request_uri parameters MUST NOT be included in Request Objects.

An example set of Request Object Claims before base64url encoding and JWS signing is as follows:

  {
   "response_type": "code id_token",
   "client_id": "s6BhdRkqt3",
   "redirect_uri": "https://client.example.org/cb",
   "scope": "openid",
   "state": "af0ifjsldkj",
   "login_hint": "janedoe@example.org",
   "max_age": 86400,
   "claims":
    {
     "userinfo":
      {
       "given_name": {"essential": true},
       "nickname": null,
       "email": {"essential": true},
       "email_verified": {"essential": true},
       "picture": null
      },
     "id_token":
      {
       "auth_time": {"essential": true},
       "acr": { "values":["urn:mace:incommon:iap:silver"] }
      }
    }
  }

3.2.  Passing the Request Object by Reference

The request_uri parameter enables OpenID Connect requests to be passed by reference, rather than by value. This parameter is used identically to the request parameter, other than that the Request Object value is retrieved from the resource at the specified URL, rather than passed by value.

The request_uri_parameter_supported Discovery result indicates whether the OP supports this parameter. Should an OP not support this parameter and an RP uses it, the OP MUST return the request_uri_not_supported error.

When the request_uri parameter is used, the OpenID Connect request parameter values contained in the referenced JWT supersede those passed using the OAuth 2.0 request syntax. However, some parameters MAY be passed using the OAuth 2.0 request syntax even when a request_uri is used; this would typically be done to enable a cached, pre-signed (and possibly pre-encrypted) Request Object value to be used containing the fixed request parameters, while parameters that can vary with each request, such as state and nonce, are passed as OAuth 2.0 parameters.

Even if a scope parameter is present in the referenced Request Object, a scope parameter MUST always be passed using the OAuth 2.0 request syntax containing the openid scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request.

Servers MAY cache the contents of the resources referenced by request URIs. If the contents of the referenced resource could ever change, the URI SHOULD include the base64url encoded SHA-256 hash of the referenced resource contents as the fragment component of the URI. If the fragment value used for a URI changes, that signals the server that any cached value for that URI with the old fragment value is no longer valid.

Note that Clients MAY pre-register request_uri values using the request_uris parameter defined in Section 2 of the OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2013.) [OpenID.Registration] specification.

3.2.1.  "request_uri" Rationale

There are several reasons that one might choose to use the request_uri parameter:

1. The set of request parameters can become large, and can exceed browser URI size limitations. Passing the request parameters by reference can solve this problem.
2. Passing a request_uri value, rather than a complete request by value, can reduce request latency.
3. Most requests for Claims from an RP are constant. The request_uri is a way of creating and sometimes also signing and encrypting a constant set of request parameters in advance. (The request_uri value becomes an "artifact" representing a particular fixed set of request parameters.)
4. Pre-registering a fixed set of request parameters at registration time enables OPs to cache and pre-validate the request parameters at registration time, meaning they need not be retrieved at request time.
5. Pre-registering a fixed set of request parameters at registration time enables OPs to vet the contents of the request from consumer protection and other points of views, either itself or by utilizing a third party.

4.  Validation

If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used.

4.1.  Authorization Request Validation

Authorization Request Validation consists of two main steps: (1) decryption and signature validation of the value of request or the content of request_uri, and (2) parameter validation. If a Request Object value was sent in the request parameter or by reference in the request_uri parameter, the Request Object MUST validate as JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] or JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] encoded objects, for which nested encryption and signing can be utilized in the manner described in the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification.

4.1.1.  Encrypted Request Object

If the Authorization Server has advertised JWE encryption algorithms in the request_object_encryption_alg_values_supported and request_object_encryption_enc_values_supported elements of its Discovery Document, these are used by the Client to encrypt the JWT.

The Authorization Server MUST decode the JWT in accordance with the JSON Web Encryption (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] specification. The result MAY be either a signed or unsigned (plaintext) Request Object. In the former case, signature validation MUST be performed as defined in Section 4.1.2 (Signed Request Object).

The Authorization Server MUST return the error if there is a decryption error.

4.1.2.  Signed Request Object

To perform Signature Validation, the alg parameter in the JWS header MUST match the value of the request_object_signing_alg set during Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2013.) [OpenID.Registration] or a value that was pre-registered by other means.

The signature MUST be validated against the key registered for that client_id and algorithm, in accordance with the JSON Web Signature (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] specification.

The Authorization Server MUST return the Authorization Error Response if there is a signature validation error.

4.1.3.  Parameter Validation

The Authorization Server MUST construct the Authorization Request Message from the Request Object value and the OAuth 2.0 Authorization Request parameters. If the same parameter exists both in the Request Object and the OAuth Authorization Request parameters, the parameter in the Request Object is used. Using this Authorization Request Message, the Authorization Server performs the following steps of the request validation:

1. The Authorization Server MUST validate all the OAuth 2.0 parameters according to the OAuth 2.0 specification.
2. The Authorization Server MUST verify that all the REQUIRED parameters are present.
3. If the sub (subject) Claim as a member of id_token element is requested with a specific value, the Authorization Server MUST only send a positive response if that user has an active session with the Authorization Server. The Authorization Server MUST NOT reply with an ID Token or Access Token for a different user, even if they have an active session with the Authorization Server.
4. If the acr Claim is requested as an Essential Claim for the ID Token with a values parameter requesting specific Authentication Context Class Reference values, then the Authorization Server MUST return an acr Claim Value that matches one of the requested values. The Authorization Server MAY ask the End-User to re-authenticate with additional factors to meet this requirement. If this is an Essential Claim and the requirement cannot be met, then the Authorization Server MUST treat that outcome as a failed authentication attempt.
5. The Client MAY request this Claim as a Voluntary Claim by using the acr_values request parameter or by not including "essential": true in the individual acr Claim request. If the Claim is not Essential and the requested value cannot be provided, the Authorization Server SHOULD return the session's current acr as the value of the acr Claim. If the Claim is not Essential, the Authorization Server is not required to provide this Claim in its response.

If the Authorization Server encounters any error, it MUST return the error response.

5.  Authorization Error Response

If the End-User denies the access request or if the request fails, the OP (Authorization Server) informs the RP (Client) by using the Error Response parameters defined in Sections 4.1.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

In addition to the error codes defined in Sections 4.1.2.1 and 4.2.2.1 of OAuth 2.0 and that of OpenID Connect Authentication Core 1.0, this specification also defines the following error codes:

invalid_request_uri

The request_uri in the Authorization Request returns an error or contains invalid data.

invalid_request_object

The request parameter contains an invalid Request Object.

request_not_supported

The OP does not support use of the request parameter.

request_uri_not_supported

The OP does not support use of the request_uri parameter.

6.  Security Considerations

For Security Considerations, refer to OpenID Connect Consolidated Security and Privacy Considerations document.

7.  Privacy Considerations

For Privacy Considerations, refer to OpenID Connect Consolidated Security and Privacy Considerations document.

8.  IANA Considerations

8.1.  OAuth Parameters Registry

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

8.1.1.  Registry Contents

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

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

8.2.  OAuth Extensions Error Registry

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

8.2.1.  Registry Contents

• Error name: invalid_request_uri
• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 5 (Authorization Error Response) of this document

• Error name: invalid_request_object
• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 5 (Authorization Error Response) of this document

• Error name: request_not_supported

• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 5 (Authorization Error Response) of this document

• Error name: request_uri_not_supported

• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 5 (Authorization Error Response) of this document

9.  References

9.1. Normative References

9.2. Informative References

Appendix A.  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

Amanda Anganes (aanganes@mitre.org), Mitre

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

Tim Bray (tbray@textuality.com), Google

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

Blaine Cook (romeda@gmail.com), Independent

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

Vladimir Dzhuvinov (vladimir@nimbusds.com), Nimbus Directory Services

George Fletcher (gffletch@aol.com), AOL

Roland Hedberg (roland.hedberg@adm.umu.se), University of Umea

Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.

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

Torsten Lodderstedt (t.lodderstedt@telecom.de), Deutsche Telekom

Hideki Nara (hdknr@ic-tact.co.jp), Tact Communications

Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom

Justin Richer (jricher@mitre.org), Mitre

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

Appendix B.  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 C.  Document History

[[ To be removed from the final specification ]]

00-

• Initial Refactored version.

Authors' Addresses