ARM Limited

Austria Hannes.Tschofenig@gmx.net http://www.tschofenig.priv.at

Internet-Draft OAuth 2.0 Smart Objects Bearer Tokens This specification describes how to use OAuth 2.0 bearer tokens to access protected resources using the Constrained Application Protocol (CoAP). Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.

OAuth enables clients to access protected resources by obtaining an access token, which is defined in "The OAuth 2.0 Authorization Framework" as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. Tokens are issued to clients by an authorization server and the client uses the access token to access the protected resources hosted by the resource server. This specification describes how to make protected resource requests when the access token is a bearer token and conveyed from the client to the resource server using the Constrained Application Protocol (CoAP) . To secure the communication exchange the Datagram Transport Layer Security Version 1.2 is mandatory to use.

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 "Key words for use in RFCs to Indicate Requirement Levels" . This document also re-uses terminology from RFC 6749 and RFC 6750 .

The abstract OAuth 2.0 flow illustrated in describes the interaction between the client, resource owner, authorization server, and resource server (described in [). The following two steps are specified within this document: (E) The client requests the protected resource from the resource server and authenticates by presenting the access token. (F) The resource server validates the access token, and if valid, serves the request. This document also imposes semantic requirements upon the access token returned in step (D).

| Resource | | | | Owner | | |<-(B)-- Authorization Grant ---| | | | +---------------+ | | | | +---------------+ | |--(C)-- Authorization Grant -->| Authorization | | Client | | Server | | |<-(D)----- Access Token -------| | | | +---------------+ | | | | +---------------+ | |--(E)----- Access Token ------>| Resource | | | | Server | | |<-(F)--- Protected Resource ---| | +--------+ +---------------+ ]]>

Access tokens are embedded in a CoAP message by the use of the "Bearer" option. The definition is shown in .

shows an example request from the client to the resource server.

If the request does not contain an access token that enables access to the protected resource, the resource server MUST respond with a 4.01 "Unauthorized" error message. QUESTION: Should the response also provide information about the scheme (e.g., 'Bearer Tokens' vs. 'Proof-of-Possession Tokens')? Should it contain a "realm" attribute as well? Should a scope value be returned to provide some guidance about the available scopes at that resource server? For example, in response to a protected resource request without a needed bearer token the error response shown in is sent.

To provide information back to the client about the failure of the request the following error codes are defined. These error codes are conveyed within the 'Error' option, which is defined in .

This specification defines the following error codes that are used with the 'Error' option: The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The resource server MUST respond with the 4.00 (Bad Request) status code. The access token provided is expired, revoked, malformed, or invalid for other reasons. The resource MUST respond with the 4.01 (Unauthorized) status code. The client MAY request a new access token and retry the protected resource request. The request requires higher privileges than provided by the access token. The resource server MUST respond with the 4.03 (Forbidden) status code. QUESTION: Is the granularity of the error messages useful enough for client implementations to take actions? As an example, in response to a request using an expired access token the following error is returned.

The security threats of this specification are identical to those discussed in RFC 6750 since the encoding of the request does not change the security threats. It is nevertheless worthwhile to replicate the security recommendation here for readers who do not want to consult another document. Client implementations MUST ensure that bearer tokens are not leaked to unintended parties, as they will be able to use them to gain access to protected resources. This is the primary security consideration when using bearer tokens and underlies all the more specific recommendations that follow. The client MUST validate the certificate chain, if the resource server is authenticated using a certificate-based ciphersuite in DTLS, when making requests to protected resources. Failing to do so may enable man-in-the-middle attacks. Clients MUST always use DTLS when making requests with bearer tokens. Failing to do so exposes the token to third parties and could consequently give attackers unintended access. Authorization servers SHOULD issue short-lived bearer tokens. Using short-lived bearer tokens reduces the impact of them being leaked. Authorization servers MUST issue bearer tokens that contain an audience restriction, scoping their use to the intended relying party or set of relying parties.

This specification requests IANA to allocate two values, as shown below, in the 0..255 range of the CoAP option number registry established with RFC 7252.

TBD: Add a registry for error codes.

The author would like to thank Mike Jones and Dick Hardt for their work on RFC 6750. This document is heavily inspired by their work.