Network Working Group S. Moore
Internet-Draft MITRE Corporation
Intended status: Informational July 20, 2015
Expires: January 21, 2016
OAuth 2.0 over Constrained Application Protocol (CoAP) for GET with
Observe Requests
draft-moore-ace-oauth-observe-00
Abstract
This document describes a method for a client or resource server
utilizing an OAuth 2.0 [RFC6749] authorization server when responding
to a Constrained Application Protocol (CoAP) [RFC7252] GET request
with the Observe option [I-D.ietf-core-observe]. 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.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 21, 2016.
Moore Expires January 21, 2016 [Page 1]
Internet-Draft OCGO July 2015
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Observable CoAP OAuth Introspection Endpoint . . . . . . . . 3
3.1. Authorization Server with Observe Enabled . . . . . . . . 3
3.2. OAuth token no longer valid . . . . . . . . . . . . . . . 4
3.3. Authorization Server without Observe Enabled . . . . . . 4
3.4. Unregistering an Introspection Request . . . . . . . . . 4
4. OAuth Protected Resource CoAP GET with Observe . . . . . . . 4
4.1. CoAP GET with Observer usage . . . . . . . . . . . . . . 4
4.2. Observer option not supported . . . . . . . . . . . . . . 5
4.3. Unregistering an Observer Request . . . . . . . . . . . . 5
5. Security Considerations . . . . . . . . . . . . . . . . . . . 5
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 5
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
8.1. Normative References . . . . . . . . . . . . . . . . . . 6
8.2. Informative References . . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] supports a GET
request with Observe option [I-D.ietf-core-observe]. 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.
Moore Expires January 21, 2016 [Page 2]
Internet-Draft OCGO July 2015
[I-D.tschofenig-ace-oauth-iot], [I-D.tschofenig-ace-oauth-bt]
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, [I-D.wahlstroem-ace-oauth-introspection] 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.
2. Terminology
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" [RFC2119].
This document also re-uses terminology from RFC 6749 [RFC6749] and
RFC 6750 [RFC6750].
3. Observable CoAP OAuth Introspection Endpoint
[I-D.wahlstroem-ace-oauth-introspection] 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
[I-D.ietf-core-observe]).
3.1. Authorization Server with Observe Enabled
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
Moore Expires January 21, 2016 [Page 3]
Internet-Draft OCGO July 2015
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.
3.2. OAuth token no longer valid
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.
3.3. Authorization Server without Observe Enabled
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 [I-D.wahlstroem-ace-oauth-introspection], making
sure that responses do not have the Observe flag set.
3.4. Unregistering an Introspection Request
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
[I-D.ietf-core-observe] 4.1.
4. OAuth Protected Resource CoAP GET with Observe
[I-D.tschofenig-ace-oauth-iot] and [I-D.tschofenig-ace-oauth-bt]
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.
4.1. CoAP GET with Observer usage
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
Moore Expires January 21, 2016 [Page 4]
Internet-Draft OCGO July 2015
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 Section 3).
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.
4.2. Observer option not supported
If the RS has observable resources disabled, or if the RS doesn't
support observable at all, the RS should behave as described in
[I-D.tschofenig-ace-oauth-iot] and [I-D.tschofenig-ace-oauth-bt],
making sure that responses do not have the Observe flag set
indicating that the resource is not observable.
4.3. Unregistering an Observer Request
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.
5. Security Considerations
TBD
6. IANA Considerations
TBD
7. Acknowledgments
The author would like to thank William Kim for valuable input, Hannes
Tschofenig for his work on [I-D.tschofenig-ace-oauth-iot] and
[I-D.tschofenig-ace-oauth-bt], and Erik Wahlstroem for his work on
[I-D.wahlstroem-ace-oauth-introspection]. The author would also like
to thank Justin Richer for his work on
[I-D.richer-oauth-introspection] and general encouragement in the
process.
Moore Expires January 21, 2016 [Page 5]
Internet-Draft OCGO July 2015
8. References
8.1. Normative References
[I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP", draft-ietf-
core-observe-16 (work in progress), December 2014.
[I-D.tschofenig-ace-oauth-bt]
Tschofenig, H., "The OAuth 2.0 Bearer Token Usage over the
Constrained Application Protocol (CoAP)", draft-
tschofenig-ace-oauth-bt-01 (work in progress), March 2015.
[I-D.tschofenig-ace-oauth-iot]
Tschofenig, H., "The OAuth 2.0 Internet of Things (IoT)
Client Credentials Grant", draft-tschofenig-ace-oauth-
iot-01 (work in progress), March 2015.
[I-D.wahlstroem-ace-oauth-introspection]
Wahlstroem, E., "OAuth 2.0 Introspection over the
Constrained Application Protocol (CoAP)", draft-
wahlstroem-ace-oauth-introspection-01 (work in progress),
March 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework",
RFC 6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, June 2014.
8.2. Informative References
[I-D.richer-oauth-introspection]
Richer, J., "OAuth Token Introspection", draft-richer-
oauth-introspection-06 (work in progress), July 2014.
Author's Address
Moore Expires January 21, 2016 [Page 6]
Internet-Draft OCGO July 2015
Stephen R Moore
MITRE Corporation
202 Burlington Rd.
Bedford, MA 01730
Email: srmoore@gmail.com
Moore Expires January 21, 2016 [Page 7]