Internet DRAFT - draft-tschofenig-ace-oauth-bt
draft-tschofenig-ace-oauth-bt
Network Working Group H. Tschofenig
Internet-Draft ARM Limited
Intended status: Informational March 8, 2015
Expires: September 9, 2015
The OAuth 2.0 Bearer Token Usage over the Constrained Application
Protocol (CoAP)
draft-tschofenig-ace-oauth-bt-01.txt
Abstract
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.
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 September 9, 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
Tschofenig Expires September 9, 2015 [Page 1]
Internet-Draft OAuth 2.0 Bearer Token Usage over CoAP March 2015
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 . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 4
6. Security Considerations . . . . . . . . . . . . . . . . . . . 6
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7
9. Normative References . . . . . . . . . . . . . . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7
1. Introduction
OAuth enables clients to access protected resources by obtaining an
access token, which is defined in "The OAuth 2.0 Authorization
Framework" [4] 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) [3]. To secure the
communication exchange the Datagram Transport Layer Security Version
1.2 [1] is mandatory to use.
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" [5].
This document also re-uses terminology from RFC 6749 [4] and RFC 6750
[2].
Tschofenig Expires September 9, 2015 [Page 2]
Internet-Draft OAuth 2.0 Bearer Token Usage over CoAP March 2015
3. Introduction
The abstract OAuth 2.0 flow illustrated in Figure 1 describes the
interaction between the client, resource owner, authorization server,
and resource server (described in [[4]). 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).
+--------+ +---------------+
| |--(A)- Authorization Request ->| Resource |
| | | Owner |
| |<-(B)-- Authorization Grant ---| |
| | +---------------+
| |
| | +---------------+
| |--(C)-- Authorization Grant -->| Authorization |
| Client | | Server |
| |<-(D)----- Access Token -------| |
| | +---------------+
| |
| | +---------------+
| |--(E)----- Access Token ------>| Resource |
| | | Server |
| |<-(F)--- Protected Resource ---| |
+--------+ +---------------+
Figure 1: Abstract OAuth 2.0 Protocol Flow.
4. Requests
Access tokens are embedded in a CoAP message by the use of the
"Bearer" option. The definition is shown in Figure 2.
Tschofenig Expires September 9, 2015 [Page 3]
Internet-Draft OAuth 2.0 Bearer Token Usage over CoAP March 2015
+-----+----+---+---+---+----------------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+-----+----+---+---+---+----------------+--------+--------+---------+
| TBD | x | | | | Bearer | opaque | var | (none) |
+-----+----+---+---+---+----------------+--------+--------+---------+
Legend:
C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable
Figure 2: Bearer Option Definition.
Figure 3 shows an example request from the client to the resource
server.
Header: GET (T=CON, Code=0.01, MID=0x7d34,
Uri-Path:"resource", Bearer: "mF_9.B5f-4.1JqM")
Figure 3: Example CoAP Request with Bearer Token.
5. Responses
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 Figure 4 is sent.
Header: ACK (T=ACK, Code=4.01, MID=0x7d34)
Figure 4: Failed Request due to Missing Access Token.
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 Figure 5.
Tschofenig Expires September 9, 2015 [Page 4]
Internet-Draft OAuth 2.0 Bearer Token Usage over CoAP March 2015
+-----+----+---+---+---+----------------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+-----+----+---+---+---+----------------+--------+--------+---------+
| TBD | | | | | Error | uint | 0-2 | (none) |
+-----+----+---+---+---+----------------+--------+--------+---------+
Legend:
C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable
Figure 5: Error Option Definition.
This specification defines the following error codes that are used
with the 'Error' option:
invalid_request (0)
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.
invalid_token (1)
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.
insufficient_scope (2)
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.
Header: ACK (T=ACK, Code=4.01, MID=0x7d34,
Error="1")
Figure 6: Failed Request due Expired Access Token.
Tschofenig Expires September 9, 2015 [Page 5]
Internet-Draft OAuth 2.0 Bearer Token Usage over CoAP March 2015
6. Security Considerations
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.
Safeguard bearer tokens: 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.
Validate TLS certificate chains: 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.
Always use DTLS (coaps): Clients MUST always use DTLS [1] when
making requests with bearer tokens. Failing to do so exposes the
token to third parties and could consequently give attackers
unintended access.
Issue short-lived bearer tokens: Authorization servers SHOULD issue
short-lived bearer tokens. Using short-lived bearer tokens
reduces the impact of them being leaked.
Issue scoped bearer tokens: Authorization servers MUST issue bearer
tokens that contain an audience restriction, scoping their use to
the intended relying party or set of relying parties.
7. IANA Considerations
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.
Tschofenig Expires September 9, 2015 [Page 6]
Internet-Draft OAuth 2.0 Bearer Token Usage over CoAP March 2015
+--------+-----------+------------+
| Number | Name | Reference |
+--------+-----------+------------+
| TBD-61 | Bearer | [this RFC] |
| TBD-62 | Error | [this RFC] |
+--------+-----------+------------+
TBD: Add a registry for error codes.
8. Acknowledgements
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.
9. Normative References
[1] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, January 2012.
[2] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012.
[3] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, June 2014.
[4] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012.
[5] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
Author's Address
Hannes Tschofenig
ARM Limited
Austria
Email: Hannes.Tschofenig@gmx.net
URI: http://www.tschofenig.priv.at
Tschofenig Expires September 9, 2015 [Page 7]
