OAuth Transient Client Secret Extension for
Public Clients
Nomura Research Institute
sakimura@gmail.com
Ping Identity
jbradley@pingidentity.com
Google
naa@google.com
Security
OAuth Working Group
The OAuth 2.0 public client utilizing code flow is susceptible to the
code interception attack. This specification describe a mechanism that
acts as a control against this threat.
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.
Public clients in OAuth 2.0 is
suseptible to the code interception attack.
The code interception attack is an attack
that a malicious client intercepts the code
returned from the authorization endpoint and uses it to obtain the
access token. This is possible on a public client as there is no client
secret associated for it to be sent to the token endpoint. This is
especially true on some smartphone platform in which the code is returned to a redirect URI with a custom
scheme as there can be multiple apps that can register the same
scheme.
To mitigate this attack, this extension utilizes dynamically created
client secret called transient client secret whose left hash is sent as
a new authorization request parameter. The code
obtained is then sent to the token endpoint with the transient client
secret and the server compairs it with the previously received left hash
of it so that it can perfom the proof of posession by the client.
In addition to the terms defined in OAuth
2.0, this specification defines the following terms.
a cryptographically random string with big enough entropy that is
used to correlate the authorization request to the token request
base64url encoding of the left most 128bit of SHA256 hash of
transient client secret
Before starting the authorization process, the client MUST make
sure that the server supports this specification. It may be obtained
out-of-band or some other mechanisms such as the discovery document in
OpenID Connect Discovery. The
exact mechanism on how the client obtains this information is out of
scope of this specification.
The client that wishes to use this specification MUST stop
proceeding if the server does not support this extension.
The client then creates a transient client secret, tcs, in the following manner.
tcs = high entropy cryptographic random string
NOTE: transient client secret MUST have high enough entropy to make
it inpractical to guess the value.
Then, the client calculates a transient client secret hash, tcsh, the salted left hash of the tcs as follows where L is a function that
calcualtes the base64url encoded left-most 128 bits of the binary
input, and H is a SHA256 function.
tcsh = L (H ( tcs) )
The client sends the transient client secret hash with the
following parameter with the OAuth 2.0
Authorization Request:
REQUIRED. transient client secret hash
When the server issues code, it MUST
associate the tcsh value with the code so that it can be used later.
Typically, the tcsh value is stored in
encrypted form in the code, but it could
as well be just stored in the server in association with the code. The
server MUST NOT include the tcsh value in
the form that any entity but itself can extract it.
Unpon receipt of the code, the client
sends the request to the token endpoint. In addition to the parameters
defined in OAuth 2.0, it sends the
following parameter:
REQUIRED. transient client secret
Upon receipt of the request at the token endpoint, the server
verifies it by calculating the transient client secret hash from
tcs value and tcsh
and comparing it with the previously associated tcsh.
If they are equal, then the successful response SHOULD be returned. If
the values are not equal, an error response indicating invalid_grant as described in section 5.2 of
OAuth 2.0 SHOULD be returned.
This specification makes a registration request as follows:
This specification registers the following parameters in the IANA
OAuth Parameters registry defined in OAuth
2.0.
Parameter name: tcs
Parameter usage location: Access Token Request
Change controller: OpenID Foundation Artifact Binding Working
Group - openid-specs-ab@lists.openid.net
Specification document(s): this document
Related information: None
Parameter name: tcsh
Parameter usage location: Authorization Request
Change controller: OpenID Foundation Artifact Binding Working
Group - openid-specs-ab@lists.openid.net
Specification document(s): this document
Related information: None
The security model relies on the fact that the transient client
secret is not being disclosed in the front channel. It is vitally
important to adhear to this principle. As such, the transient client
secret has to be created in such a manner that it is cryptographically
random and has high entropy that it is not practical for the attacker to
guess, and if it is to be returned inside code,
it has to be encrypted in such a manner that only the server can decrypt
and extract it.
The initial draft of this specification was created by the OpenID
AB/Connect Working Group of the OpenID Foundation, by most notably of
the following people:
Naveen Agarwal, Google
Dirk Belfanz, Google
John Bradley, Ping Identity
Brian Campbell, Ping Identity
Ryo Ito, mixi
Michael B. Jones, Microsoft
Torsten Lodderstadt, Deutsche Telekom
Breno de Madeiros, Google
Anthony Nadalin, Microsoft
Nat Sakimura, Nomura Research Institute
OpenID Connect Discovery 1.0
Nomura Research Institute,
Ltd.
Ping Identity
Microsoft
Illumila