MITRE Corporation

202 Burlington Rd. Bedford, MA 01730 srmoore@gmail.com

This document describes a method for a client or resource server utilizing an OAuth 2.0 authorization server when responding to a Constrained Application Protocol (CoAP) GET request with the Observe option . CoAP’s Observe option has the potential to reduce network traffic by allowing clients to get updates on protected resources as the protected resource’s values change rather than polling the protected resource periodically. A client adding the Observe option to a CoAP GET request has the greatest impact on the device providing the protected resource since the resource server (RS) has to maintain a list of requestors and deal with tokens associated with those requests. Additionally an Authorization Server (AS) could potentially allow token introspection to happen over a GET request with the Observe option, further reducing network usage and heavy lifting on the part of the resource server doing the introspection.

The Constrained Application Protocol (CoAP) supports a GET request with Observe option . When a CoAP client makes such a request the server responds as it normally would as well as with an update every time the requested CoAP resource changes. This behavior eliminates the need to poll the resource along with any additional network overhead such as acknowledgements cutting the traffic down to a third of what otherwise would be required. , describe how to use OAuth in CoAP requests but do not cover the case of GET requests that have the Observe option set. From a client perspective there isn’t a change other than setting the Observe option, and handling the various responses to that type of request. From the Resource Server (RS) point of view though, there are addition steps that have to be taken to insure proper secure and authorized access to the resource. Additionally, describes how a RS can perform introspection of a token by sending it to an Authorization Server (AS) over a CoAP POST or GET request. Allowing the GET request to include the Observe option would ease network usage even more by reducing the number of introspections requests an RS would need to perform. The method described in this document would allow any resource server to respond to a protected resource CoAP GET with Observe request and to perform token introspection over CoAP using the very same GET with Observe option, eliminating the need to validate the every token before sending out updates.

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 .

defines how a client or resource server can query an OAuth authorization server about an OAuth token using CoAP. For CoAP GETs without the Observe flag and POSTs this method is sufficient as described. Here we define additional behavior for the authorization server to support introspection utilizing CoAP GET with the Observe option (defined in ).

When an OAuth authorization server (AS) receives a properly formatted introspection request over CoAP GET that has the Observe flag set to 0 (register) and the AS supports Observe, the AS should respond with standard 2.xx response with the observe option set. Upon any change in the token’s state (i.e. expiration, revocation, etc.), the server should send a Notification response to the original requestor. If the token is still valid that response should be comprised of a 2.05 (Content) response code along with the updated meta-data for the token as content.

If a token is no longer valid (or if the authentication of the original requestor is no longer valid for introspection), then a notification with the appropriate non-2.xx code should be sent back to the requestor, and the registration for the introspection removed from the authorization server’s list of clients.

If the AS does not allow for the introspection endpoint to be observable, or if the AS doesn’t support it at all, the AS should behave as defined in , making sure that responses do not have the Observe flag set.

When the AS receives a request from a previously registered client that has the Observe flag set to 1 (deregister), that client is indicating that it no longer wants updates about the accompanying token. If the client’s credentials are valid, the AS should removed the client from the list of clients receiving updates for the given token. The CoAP particulars of this process are covered by 4.1.

and describe OAuth 2.0 token usage over CoAP. When a resource server (RS) receives a GET request that has the Observe option set the RS should respond appropriately based on the request, and the state of the OAuth token received, as described below.

When an OAuth protected RS receives a GET request that has the Observe flag set to 0 (register), the RS should first validate the token and then respond appropriately. If the token is valid and the RS supports observability, the RS should return a proper 2.xx response that has the Observe option set, indicating that the RS has added the client to its registered clients list. The RS should also add the client to the registered client list for the requested resource. Whenever the associated resource changes, the RS should send a 2.05 (Content) response to all the clients in the registered clients list after re-validating the token (or by taking advantage of an Observable Introspection Endpoint as described in ). If the token is not valid at the time of request or update, then a notification with the appropriate non-2.xx code should be sent back to the requestor, and the registration for the introspection removed from the authorization server’s list of clients.

If the RS has observable resources disabled, or if the RS doesn’t support observable at all, the RS should behave as described in and , making sure that responses do not have the Observe flag set indicating that the resource is not observable.

When a client wishes to no longer receive updates from a RS via a GET with Observe request, the client will send a request that has the Observe flag set to 1 (deregister). This request should be accompanied by a valid token. If the token is valid, then the RS should remove the client from the list of registered clients associated with the resource the request is for.

TBD

TBD

The author would like to thank William Kim for valuable input, Hannes Tschofenig for his work on and , and Erik Wahlstroem for his work on . The author would also like to thank Justin Richer for his work on and general encouragement in the process.

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation.</t><t> CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. As Internet of Things (IoT) deployments increase steadily the need for a better user experience for handling the authentication and authorization tasks in constrained environments increases. While several technologies have been developed already that allow federated access to protected resource the nature of IoT deployments requires care with the limited resources available on many of these devices. This document defines a new OAuth 2.0 authorization grant for the interaction between constrained clients and resource servers to obtain access tokens for access to protected resources. It does so by leveraging prior work on OAuth 2.0, CoAP, and DTLS. 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. This document defines a method for a client or resource server to query an OAuth authorization server to determine meta- information about an OAuth token using the Constrained Application Protocol (CoAP) [4]. An client in possession of a OAuth2 token can use it to get metadata about the token like validity and approved scopes. Harvard University

1350 Mass. Ave. Cambridge MA 02138 - +1 617 495 3864 sob@harvard.edu

General keyword In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. Authors who follow these guidelines should incorporate this phrase near the beginning of their document: 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. Note that the force of these words is modified by the requirement level of the document in which they are used. This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. 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. [STANDARDS-TRACK] This specification defines a method for a client or protected resource to query an OAuth authorization server to determine meta- information about an OAuth token.