Network Working Group E. Wahlstroem Internet-Draft Nexus Technology Intended status: Informational March 9, 2015 Expires: September 10, 2015 OAuth 2.0 Introspection over the Constrained Application Protocol (CoAP) draft-wahlstroem-ace-oauth-introspection-01.txt Abstract 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. 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 10, 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. Wahlstroem Expires September 10, 2015 [Page 1] Internet-Draft OAuth 2.0 Token Introspection over CoAP March 2015 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Introspection CoAP Endpoint . . . . . . . . . . . . . . . . . 3 4. Introspection Request . . . . . . . . . . . . . . . . . . . . 3 5. Introspection Response . . . . . . . . . . . . . . . . . . . 3 6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 7. Security Considerations . . . . . . . . . . . . . . . . . . . 5 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 5 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 11.1. Normative References . . . . . . . . . . . . . . . . . . 5 11.2. Informative References . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction OAuth2 enables clients to access protected resources by obtaining an access token, which is defined in "The OAuth 2.0 Authorization Framework" [2] 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 document defines a way for a holder of this token, mostly Clients and Resource Servers, to get metadata like validity and scopes for the token. The OAuth Token Introspection specification [14] defines a way to validate the token using HTTP POST or HTTP GET. This document reuses the work done in the OAuth Token Introspection and defines a mapping of the request and response to CoAP [4] to be used by constrained devices. 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" [1]. This document also re-uses terminology from RFC 6749 [2] and RFC 6750 [6]. Wahlstroem Expires September 10, 2015 [Page 2] Internet-Draft OAuth 2.0 Token Introspection over CoAP March 2015 3. Introspection CoAP Endpoint The Introspection CoAP Endpoint responds to CoAP Confirmable requests from token holders, particularly Clients and Resource Servers. The endpoint takes a single parameter representing the token (and optionally further authentication) and returns a JSON [7] document representing the meta information surrounding the token. The endpoint MUST be protected by DTLS [5] or equivalent. 4. Introspection Request The token holder makes a request to the Introspection CoAP Endpoint by adding the following parameters using the "application/x-www-form- urlencoded" format with a character encoding of UTF-8 in the CoAP request entity-body: In order to prevent man-in-the-middle attacks, the client MUST require the use of DTLS with server authentication for any request sent to the authorization and token endpoints. If certificate-based server authentication is used then the client MUST validate the TLS certificate of the authorization server, as defined by RFC6125. The Endpoint SHOULD also require some form of authentication to access this endpoint, such as the Client Authentication as described in OAuth 2.0 [RFC6749] or equivalent. token: REQUIRED. The string value of the token. resource_id: OPTIONAL. A service-specific string identifying the resource that the client doing the introspection is asking about. token_type_hint: OPTIONAL. A hint about the type of the token submitted for introspection. Clients MAY pass this parameter in order to help the authorization server to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, particularly if it is able to detect the token type automatically. Values for this field are defined in OAuth Token Revocation [RFC7009]. 5. Introspection Response If the introspection request is valid and authorized, the authorization server responds with a CoAP message using Content response code with the response encoded as a JSON structure in the payload of the message. If the request failed client authentication or is invalid, the authorization server returns an error response Wahlstroem Expires September 10, 2015 [Page 3] Internet-Draft OAuth 2.0 Token Introspection over CoAP March 2015 using the CoAP 4.00 'Bad Request' response code with the error messages defined in Section 5.2 of RFC 6749 [2]. The JSON structure in the payload response includes the top-level members defined in Section 2.2 in the OAuth Token Introspection specification [14]. It's recommended to only return the active attribute considering the lossy and constrained nature of CoAP client and server network and capacity. Note that the HTTP "Cache-Control" parameters MAY be used in the CoAP response message. 6. Example For example, the client makes a CoAP request carrying the introspection request protected with DTLS to the authorization server. It then receives a response containing metadata about the token. In the example below content-type 51 corresponds to the 'application/ x-www-form-urlencoded'. Authorization Client Server | | |<=======>| DTLS Connection Establishment | | +-------->| Header: POST (T=CON, Code=0.02, MID=0x7d34, | POST | ct=51, Uri-Path:"introspect" | | Payload: cid=qwerty&cs=2123&t=X3241Affw.4233-99JXJ | | |<--------+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34, | 2.05 | ct=50) | | Payload: | | := { "active": true } Figure 1: Example CoAP Introspection Exchange. Wahlstroem Expires September 10, 2015 [Page 4] Internet-Draft OAuth 2.0 Token Introspection over CoAP March 2015 7. Security Considerations TBD 8. IANA Considerations TBD 9. Acknowledgements The author would like to thank Justin Richer for his work on [14] richer-oauth-introspection and Hannes Tschofenigs [10] and [11]. This document is heavily inspired from those document's and it borrows a lot of texts from there work. The author would also like to thank Samuel Erdtman for valuable input. 10. Change Log [[This section to be removed prior to publication as an RFC]] Draft 01 - Using same request format as OAuth2 introspection endpoint to ease proxying. 11. References 11.1. Normative References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [3] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, March 2011. [4] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, June 2014. [5] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, January 2012. [6] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012. Wahlstroem Expires September 10, 2015 [Page 5] Internet-Draft OAuth 2.0 Token Introspection over CoAP March 2015 [7] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [8] Tschofenig, H. and T. Fossati, "A TLS/DTLS Profile for the Internet of Things", draft-ietf-dice-profile-10 (work in progress), March 2015. [9] Tschofenig, H., "OAuth 2.0: Audience Information", draft- tschofenig-oauth-audience-00 (work in progress), February 2013. 11.2. Informative References [10] 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. [11] Tschofenig, H., "The OAuth 2.0 Internet of Things (IoT) Client Credentials Grant", draft-tschofenig-ace-oauth- iot-01 (work in progress), March 2015. [12] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", draft-ietf-oauth-json-web-token-32 (work in progress), December 2014. [13] Hunt, P., Richer, J., Mills, W., Mishra, P., and H. Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security Architecture", draft-hunt-oauth-pop-architecture-02 (work in progress), June 2014. [14] Richer, J., "OAuth Token Introspection", draft-richer- oauth-introspection-06 (work in progress), July 2014. [15] Bormann, C., "An Authorization Information Format (AIF) for ACE", draft-bormann-core-ace-aif-01 (work in progress), July 2014. [16] Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. Kumar, "ACE use cases", draft-seitz-ace-usecases-02 (work in progress), October 2014. Author's Address Wahlstroem Expires September 10, 2015 [Page 6] Internet-Draft OAuth 2.0 Token Introspection over CoAP March 2015 Erik Wahlstroem Nexus Technology Sweden Email: erik.wahlstrom@nexusgroup.com URI: https://www.nexusgroup.com Wahlstroem Expires September 10, 2015 [Page 7]