OAuth 2.0 Proof-of-Possession: Authorization Server to Client Key Distribution

The work on proof-of-possession tokens, an extended token security mechanisms for OAuth 2.0, is motivated in . This document defines the ability for the client request and to obtain PoP tokens from the authorization server. After successfully completing the exchange the client is in possession of a PoP token and the keying material bound to it. Clients that access protected resources then need to demonstrate knowledge of the secret key that is bound to the PoP token. To best describe the scope of this specification, the OAuth 2.0 protocol exchange sequence is shown in . The extension defined in this document piggybacks on the message exchange marked with (C) and (D). To demonstrate possession of the private/secret key to the resource server protocol mechanisms outside the scope of this document are used.

| Resource | | | | Owner | | |<-(B)-- Authorization Grant ---| | | | +---------------+ | | | | +---------------+ | |--(C)-- Authorization Grant -->| | | Client | (aud, cnf) | Authorization | | | | Server | | |<-(D)-- PoP Access Token ------| | | | (profile, cnf, rs_cnf, +---------------+ | | token_type) | | +---------------+ | |--(E)-- PoP Access Token ----->| | | | (with proof of private key) | Resource | | | | Server | | |<-(F)--- Protected Resource ---| | +--------+ +---------------+ ]]> In OAuth 2.0 access tokens can be obtained via authorization grants and using refresh tokens. The core OAuth specification defines four authorization grants, see Section 1.3 of , and adds an assertion-based authorization grant to that list. The token endpoint, which is described in Section 3.2 of , is used with every authorization grant except for the implicit grant type. In the implicit grant type the access token is issued directly. This document extends the functionality of the token endpoint, i.e., the protocol exchange between the client and the authorization server, to allow keying material to be bound to an access token. Two types of keying material can be bound to an access token, namely symmetric keys and asymmetric keys. Conveying symmetric keys from the authorization server to the client is described in and the procedure for dealing with asymmetric keys is described in .

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this specification are to be interpreted as described in . In the context of this specification 'session key' refers to fresh and unique keying material established between the client and the resource server. This session key has a lifetime that corresponds to the lifetime of the access token, is generated by the authorization server and bound to the access token. This document uses the following abbreviations: JSON Web Algorithms JSON Web Token JSON Web Signature JSON Web Key JSON Web Encryption CBOR Web Token CBOR Object Signing and Encryption

Step (0): As an initial step the client typically determines the resource server it wants to interact with. This may, for example, happen as part of a discovery procedure or via manual configuration. Step (1): The client starts the OAuth 2.0 protocol interaction based on the selected grant type. Step (2): When the client interacts with the token endpoint to obtain an access token it MUST follow the processing steps for the HTTPS-based transport described in Section 5.6.1 of . This includes determining whether to use the 'aud' and the 'cnf' parameters. Step (3): The authorization server parses the request from the server and determines the suitable response based on the description in Section 5.6.2 of . In case of an error the procedure in Section 5.6.3 of is applicable. Note that PoP access tokens may be encoded in a variety of ways. In case the access token is encoded using the JSON Web Token (JWT) format it MUST be protected against modification by either using a digital signature or a keyed message digest, as described in . The JWT may also be encrypted using . defines an alternative token format based on CBOR. The proof-of-possession token functionality is defined in . Finally, access tokens can also be passed by reference, which then requires the token introspection endpoint (or a similiar, proprietary protocol mechanism) to be used. This specification does not mandate a specific PoP token format. Subsequent steps for the interaction between the client and the resource server are beyond the scope of this document.

This section provides a number of examples.

The client starts with a request to the authorization server indicating that it is interested to obtain a token for example-server.

If the access token request has been successfully verified by the authorization server and the client is authorized to obtain a PoP token for the indicated resource server, the authorization server issues an access token and optionally a refresh token. shows a response containing a token and a "cnf" parameter with a symmetric proof-of-possession key.

Note that the cnf payload in is not encrypted at the application layer since Transport Layer Security is used between the AS and the client and the content of the cnf payload is consumed by the client itself. Alternatively, a JWE could be used to encrypt the key distribution, as shown in .

The content of the key parameter, which is a JWK in our example, is shown in .

The content of the 'access_token' in JWT format contains the 'cnf' (confirmation) claim, as shown in . The confirmation claim is defined in . The digital signature or the keyed message digest offering integrity protection is not shown in this example but has to be present in a real deployment to mitigate a number of security threats. The JWK in the key element of the response from the authorization server, as shown in , contains the same session key as the JWK inside the access token, as shown in . It is, in this example, protected by TLS and transmitted from the authorization server to the client (for processing by the client).

Note: When the JWK inside the access token contains a symmetric key it must be confidentiality protected using a JWE to maintain the security goals of the PoP architecture, as described in since content is meant for consumption by the selected resource server only. Note: This document does not impose requirements on the encoding of the access token. The examples used in this document make use of the JWT structure but the CWT format is an equally appropriate format to use. If the access token is only a reference then a look-up by the resource server is needed, as described in the token introspection specification .

This example illustrates the case where an asymmetric key shall be bound to an access token. The client makes the following HTTPS request shown in . Extra line breaks are for display purposes only.

As shown in the content of the 'cnf' parameter contains the ECC public key the client would like to associate with the access token.

If the access token request is valid and authorized, the authorization server issues an access token and optionally a refresh token. The authorization server also places information about the public key used by the client into the access token to create the binding between the two. The new token type "public_key" is placed into the 'token_type' parameter. An example of a successful response is shown in .

The content of the 'access_token' field contains an encoded JWT, as shown in . The digital signature covering the access token offering authenticity and integrity protection is not shown below (but must be present).

Note: In this example there is no need for the authorization server to convey further keying material to the client since the client is already in possession of the private key.

describes the architecture for the OAuth 2.0 proof-of-possession security architecture, including use cases, threats, and requirements. This requirements describes one solution component of that architecture, namely the mechanism for the client to interact with the authorization server to either obtain a symmetric key from the authorization server, to obtain an asymmetric key pair, or to offer a public key to the authorization. In any case, these keys are then bound to the access token by the authorization server. To summarize the main security recommendations: A large range of threats can be mitigated by protecting the contents of the access token by using a digital signature or a keyed message digest. Consequently, the token integrity protection MUST be applied to prevent the token from being modified, particularly since it contains a reference to the symmetric key or the asymmetric key. If the access token contains the symmetric key (see Section 2.2 of for a description about how symmetric keys can be securely conveyed within the access token) this symmetric key MUST be encrypted by the authorization server with a long-term key shared with the resource server. To deal with token redirect, it is important for the authorization server to include the identity of the intended recipient (the audience), typically a single resource server (or a list of resource servers), in the token. Using a single shared secret with multiple authorization server to simplify key management is NOT RECOMMENDED since the benefit from using the proof-of-possession concept is significantly reduced. Token replay is also not possible since an eavesdropper will also have to obtain the corresponding private key or shared secret that is bound to the access token. Nevertheless, it is good practice to limit the lifetime of the access token and therefore the lifetime of associated key. The authorization server MUST offer confidentiality protection for any interactions with the client. This step is extremely important since the client will obtain the session key from the authorization server for use with a specific access token. Not using confidentiality protection exposes this secret (and the access token) to an eavesdropper thereby making the OAuth 2.0 proof-of-possession security model completely insecure. OAuth 2.0 relies on TLS to offer confidentiality protection and additional protection can be applied using the JWK offered security mechanism, which would add an additional layer of protection on top of TLS for cases where the keying material is conveyed, for example, to a hardware security module. Which version(s) of TLS ought to be implemented will vary over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 is the most recent version. The client MUST validate the TLS certificate chain when making requests to protected resources, including checking the validity of the certificate. Similarly to the security recommendations for the bearer token specification developers MUST ensure that the ephemeral credentials (i.e., the private key or the session key) is not leaked to third parties. An adversary in possession of the ephemeral credentials bound to the access token will be able to impersonate the client. Be aware that this is a real risk with many smart phone app and Web development environments. Clients can at any time request a new proof-of-possession capable access token. Using a refresh token to regularly request new access tokens that are bound to fresh and unique keys is important. Keeping the lifetime of the access token short allows the authorization server to use shorter key sizes, which translate to a performance benefit for the client and for the resource server. Shorter keys also lead to shorter messages (particularly with asymmetric keying material). When authorization servers bind symmetric keys to access tokens then they SHOULD scope these access tokens to a specific permissions.

This document does not require any actions by IANA.

We would like to thank Chuck Mortimore for his review comments.