Encoding claims in the OAuth 2 state paramater using a JWT
Ping Identity
ve7jtb@ve7jtb.com
http://www.thread-safe.com/
Deutsche Telekom AG
torsten@lodderstedt.net
JOSE
JSON Web Signature
JWS
JSON Web Encryption
JWE
JSON Web Key
JWK
JSON Web Algorithms
JWA
JWT
This draft provides a method for a client to encode one or more elements encoding
information about the session into the OAuth 2 state paramater.
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 OAuth 2.0 Authorization protocol , the Authorization server SHOULD
perform an exact string comparison of the redirect_uri
paramater with the redirect_uri paramater registered by
by the client. This is essential for stopping token leakage to third parties in
the OAuth implicit flow.
As a result of this clients can not safely add extra query paramaters to the
redirect_uri paramater that encode additional client state
information.
The Client MUST use the state paramater 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 for use as the value of the state paramater.
The JWT may be sent without integrity protection, with integrity protection
,
or with both integrity and confidentiality protection .
The client is free
to choose the appropriate protection for it's use-case as the state paramater is treated as opaque by the
Authorization Server (AS).
The OAuth Authorization request state paramater
consists of a , optionally
signed with or encrypted with
, whose payload contains claims as defined
here.
REQUIRED. string containing a verifiable identifier for the
browser session, that cannot be guessed by a third party. The verification of
this element by the client protects it from accepting authorization responses
generated in response to forged requests generated by third parities.
RECOMMENDED if signed. Identifier of the key used
to sign this client identifier at the issuer.
OPTIONAL. Timestamp of when this Authorization Request
was issued.
OPTIONAL. string identifying the party that issued
this state value.
OPTIONAL. string identifying the client that
this state value is intended for.
OPTIONAL. URI containing the location the user agent
is to be redirected to after authorization.
OPTIONAL. string identifying the authorization server that
this request was sent to.
OPTIONAL.
Access Token hash value.
Its value is the base64url encoding of the left-most half of the
hash of the octets of the ASCII representation of the
access_token value,
where the hash algorithm used is the hash algorithm
used in the alg parameter
of the State Token's JWS 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.
OPTIONAL.
Code hash value.
Its value is the base64url encoding of the left-most half of the
hash of the octets of the ASCII representation of the
code value,
where the hash algorithm used is the hash algorithm
used in the alg header parameter
of the State Token's JWS 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.
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 with
in such a way that it can verify the
signature. The algorithm HS256 with a key of 256bits
is recommended.
The issuer MAY sign the with
algorithm none if integrity protecting the
contents of the state paramater is not required.
If the state paramater contains information the client
dosen't want to disclose to the Authorization server or user, the issuer MAY encrypt
the JWT with JWE. The JWA
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 . 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 paramater the client must validate its integrity.
The client parses it as a JWT. It then verifies the
signature if the JWT (if signed) using . T
he key used to sign the
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
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 there 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 uri for redirecting the user to
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 loggs. 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.
JSON Web Algorithms (JWA)
Microsoft
mbj@microsoft.com
http://self-issued.info/
JSON Web Signature (JWS)
Microsoft
mbj@microsoft.com
http://self-issued.info/
Ping Identity
ve7jtb@ve7jtb.com
Nomura Research Institute
n-sakimura@nri.co.jp
JSON Web Encryption (JWE)
Microsoft
mbj@microsoft.com
http://self-issued.info/
Cisco Systems, Inc.
jhildebr@cisco.com
JSON Web Token (JWT)
Microsoft
mbj@microsoft.com
http://self-issued.info/
Ping Identity
ve7jtb@ve7jtb.com
Nomura Research Institute
n-sakimura@nri.co.jp