| Internet-Draft | Abbreviated-Title | May 2015 |
| Bradley, et al. | Expires 22 November 2015 | [Page] |
This draft provides a method for a client to encode one or more elements encoding
information about the session into the OAuth 2 state parameter.¶
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].¶
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 22 November 2015.¶
Copyright (c) 2015 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 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.¶
In the OAuth 2.0 Authorization protocol [RFC6749] , the Authorization server SHOULD
perform an exact string comparison of the redirect_uri
parameter with the redirect_uri parameter registered by
by the client. This is essential for preventing token leakage to third parties in
the OAuth implicit flow.¶
As a result of this clients can not safely add extra query parameters to the
redirect_uri parameter that encode additional client state
information.¶
The Client MUST use the state parameter to encode
both Cross Site Request Forgery protection and any other state information it wishes
to preserve for itself regarding the authorization request.¶
This draft proposes a mechanism whereby multiple state attributes can be
encoded into a JSON Web Token JWT [RFC7519] for use as the value of the state parameter.¶
The JWT may be sent without integrity protection, with integrity protection
JWS [RFC7515],
or with both integrity and confidentiality protection JWE [RFC7516].
The client is free
to choose the appropriate protection for its use-case as the state parameter is treated as opaque by the
Authorization Server (AS).¶
The OAuth Authorization request state parameter
consists of a JWT [RFC7519], optionally
signed with JWS [RFC7515] or encrypted with
JWE [RFC7516], whose payload contains claims as defined
here.¶
exp (expiration time)
claim identifies the expiration time on or after which the
JWT MUST NOT be accepted for processing. The processing
of the exp claim requires that
the current date/time MUST be before the expiration
date/time listed in the exp
claim. Implementers MAY provide for some small leeway,
usually no more than a few minutes, to account for clock skew.
Its value MUST be a number containing an IntDate value.
Use of this claim is OPTIONAL. This is RECOMMENDED if
the JWT [RFC7519] state token is being produced by the AS.¶
jti (JWT ID) claim
provides a unique identifier for the JWT. The identifier
value MUST be assigned in a manner that ensures that there
is a negligible probability that the same value will be
accidentally assigned to a different data object. The
jti claim can be used to
prevent the JWT from being replayed.
The jti value is a case-sensitive string.
Use of this claim is OPTIONAL.¶
access_token value,
where the hash algorithm used is the hash algorithm
used in the alg parameter
of the State Token's JWS [RFC7515] header.
For instance, if the alg is
RS256, hash the
access_token value
with SHA-256, then take the left-most 128 bits and base64url encode them.
The at_hash value is a case sensitive string.
This is REQUIRED if
the JWT [RFC7519] state token is being produced by the AS and
issued with a access_token in the authorization
response.¶
code value,
where the hash algorithm used is the hash algorithm
used in the alg header parameter
of the State Token's JWS [RFC7515] header.
For instance, if the alg is
HS512, hash the
code value
with SHA-512, then take the left-most 256 bits and base64url encode them.
The c_hash value is a case sensitive string.
This is REQUIRED if
the JWT [RFC7519] state token is being produced by the AS and
issued with a code in the authorization
response.¶
The issuer may add additional claims to the token. The producer and the consumer of the JWT are the same or closely related entities so collision resistance of claim names should not be a concern.¶
The issuer SHOULD sign the JWT [RFC7519] with JWS [RFC7515] in such a way that it can verify the signature. The JWA [RFC7518] algorithm HS256 with a key of 256bits is recommended.¶
The issuer MAY sign the JWT [RFC7519] with JWS [RFC7515]
using JWA [RFC7518] algorithm none if integrity protecting the
contents of the state parameter is not required.¶
If the state parameter contains information the client
doesn't want to disclose to the Authorization server or user, the issuer MAY encrypt
the JWT [RFC7519] with JWE [RFC7516].
The JWA [RFC7518]
algorithm ("alg") of "dir" and encryption algorithm ("enc")
of "A128CBC-HS256" are recommended for symmetric encryption.¶
In the case of the state value being created
by the Issuer the iss and
aud claims MUST be included in the JWT. The jwt
MUST also be signed with JWT [RFC7515]. If the State token
is issued with a code c_hash MUST be included.
If the State Token is issued with a Access Token
at_hash MUST be included.¶
Upon receiving a state parameter the client must validate its integrity. The client parses it as a JWT. It then verifies the signature of the JWT (if signed) using JWS [RFC7515]. The key used to sign the JWT [RFC7519] MAY be indicated by the kid field. The client MAY use other means to validate the JWT and determine its authenticity.¶
The client then reads the fields inside the JWT [RFC7519] and uses these to configure the user experience and security parameters of the authorization.¶
The rfp claim MUST be validated by the client by
comparing it to the secret
information that it used to create the rfp value.¶
The client MUST create a value that cannot be guessed by a third party attacker and used to forge requests. There are many possible ways to create this value. For reference two common ways will be listed.¶
It is completely up to the purview of the particular client which generation methods, and which claims, they will accept.¶
Many clients that are web servers maintain session state for browsers in a server side store.¶
These clients can generate a random value with sufficient entropy
that an attacker cannot guess future values. This value can be stored in
the server side store and used directly as the value of
rfp.¶
Some clients that are web servers maintain session state for browsers using browser stored cookies or HTML5 local storage.¶
These clients can generate a hash value based on a HTTPS: bound session cookie or other browser side information that is not accessible to third parties. This hash value can directly as the value of "xsrf".¶
While OAuth strongly recommends that clients use TLS to secure their endpoints,
if a client is not using TLS it MUST produce the value of
rfp by using
a HMAC algorithm with a secret known only to itself over the browser stored
information.¶
Some clients may be willing to rely on the Authorization server providing
protection for Cross Site Request Forgery. In Cases where the Authorization
server and the client have a pre-established relationship, and the client is
willing to accept flows initiated by the Authorization server, the string "iss"
may be used as the value of rfp.¶
[ maybe we register the "rfp" claim above? ]¶
This document makes no request of IANA.¶
Note to RFC Editor: this section may be removed on publication as an RFC.¶
Some information in the state JWT such as target_link_uri value for redirecting the user to the application might have some security impact is the user modifies them intentionally or unintentionally. To prevent tampering with the "state" value the client may integrity protect the contents of the JWT.¶
The client may have information that it wants to protect from disclosure to the Authorization server, in logs, to proxies, or to the user. In this case encrypting the JWT as a JWE is required to protect the confidentiality of the state information.¶
[[ to be removed by the RFC editor before publication as an RFC ]]¶
-04¶