idnits 2.17.1 draft-wahlstroem-ace-oauth-introspection-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([4]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 9, 2015) is 3329 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: 'RFC6749' on line 119 -- Looks like a reference, but probably isn't: 'RFC7009' on line 134 == Unused Reference: '3' is defined on line 219, but no explicit reference was found in the text == Unused Reference: '8' is defined on line 237, but no explicit reference was found in the text == Unused Reference: '9' is defined on line 241, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 255, but no explicit reference was found in the text == Unused Reference: '13' is defined on line 259, but no explicit reference was found in the text == Unused Reference: '15' is defined on line 267, but no explicit reference was found in the text == Unused Reference: '16' is defined on line 271, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6125 (ref. '3') (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (ref. '5') (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 4627 (ref. '7') (Obsoleted by RFC 7158, RFC 7159) == Outdated reference: A later version (-17) exists of draft-ietf-dice-profile-10 == Outdated reference: A later version (-09) exists of draft-bormann-core-ace-aif-01 Summary: 4 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wahlstroem 3 Internet-Draft Nexus Technology 4 Intended status: Informational March 9, 2015 5 Expires: September 10, 2015 7 OAuth 2.0 Introspection over the Constrained Application Protocol (CoAP) 8 draft-wahlstroem-ace-oauth-introspection-01.txt 10 Abstract 12 This document defines a method for a client or resource server to 13 query an OAuth authorization server to determine meta- information 14 about an OAuth token using the Constrained Application Protocol 15 (CoAP) [4]. An client in possession of a OAuth2 token can use it to 16 get metadata about the token like validity and approved scopes. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on September 10, 2015. 35 Copyright Notice 37 Copyright (c) 2015 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 54 3. Introspection CoAP Endpoint . . . . . . . . . . . . . . . . . 3 55 4. Introspection Request . . . . . . . . . . . . . . . . . . . . 3 56 5. Introspection Response . . . . . . . . . . . . . . . . . . . 3 57 6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 7. Security Considerations . . . . . . . . . . . . . . . . . . . 5 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 60 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 61 10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 11.1. Normative References . . . . . . . . . . . . . . . . . . 5 64 11.2. Informative References . . . . . . . . . . . . . . . . . 6 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 67 1. Introduction 69 OAuth2 enables clients to access protected resources by obtaining an 70 access token, which is defined in "The OAuth 2.0 Authorization 71 Framework" [2] as "a string representing an access authorization 72 issued to the client", rather than using the resource owner's 73 credentials directly. 75 Tokens are issued to clients by an authorization server and the 76 client uses the access token to access the protected resources hosted 77 by the resource server. This document defines a way for a holder of 78 this token, mostly Clients and Resource Servers, to get metadata like 79 validity and scopes for the token. The OAuth Token Introspection 80 specification [14] defines a way to validate the token using HTTP 81 POST or HTTP GET. This document reuses the work done in the OAuth 82 Token Introspection and defines a mapping of the request and response 83 to CoAP [4] to be used by constrained devices. 85 2. Terminology 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 89 document are to be interpreted as described in "Key words for use in 90 RFCs to Indicate Requirement Levels" [1]. 92 This document also re-uses terminology from RFC 6749 [2] and RFC 6750 93 [6]. 95 3. Introspection CoAP Endpoint 97 The Introspection CoAP Endpoint responds to CoAP Confirmable requests 98 from token holders, particularly Clients and Resource Servers. The 99 endpoint takes a single parameter representing the token (and 100 optionally further authentication) and returns a JSON [7] document 101 representing the meta information surrounding the token. The 102 endpoint MUST be protected by DTLS [5] or equivalent. 104 4. Introspection Request 106 The token holder makes a request to the Introspection CoAP Endpoint 107 by adding the following parameters using the "application/x-www-form- 108 urlencoded" format with a character encoding of UTF-8 in the CoAP 109 request entity-body: 111 In order to prevent man-in-the-middle attacks, the client MUST 112 require the use of DTLS with server authentication for any request 113 sent to the authorization and token endpoints. If certificate-based 114 server authentication is used then the client MUST validate the TLS 115 certificate of the authorization server, as defined by RFC6125. 117 The Endpoint SHOULD also require some form of authentication to 118 access this endpoint, such as the Client Authentication as described 119 in OAuth 2.0 [RFC6749] or equivalent. 121 token: REQUIRED. The string value of the token. 123 resource_id: OPTIONAL. A service-specific string identifying the 124 resource that the client doing the introspection is asking about. 126 token_type_hint: OPTIONAL. A hint about the type of the token 127 submitted for introspection. Clients MAY pass this parameter in 128 order to help the authorization server to optimize the token 129 lookup. If the server is unable to locate the token using the 130 given hint, it MUST extend its search across all of its supported 131 token types. An authorization server MAY ignore this parameter, 132 particularly if it is able to detect the token type automatically. 133 Values for this field are defined in OAuth Token Revocation 134 [RFC7009]. 136 5. Introspection Response 138 If the introspection request is valid and authorized, the 139 authorization server responds with a CoAP message using Content 140 response code with the response encoded as a JSON structure in the 141 payload of the message. If the request failed client authentication 142 or is invalid, the authorization server returns an error response 143 using the CoAP 4.00 'Bad Request' response code with the error 144 messages defined in Section 5.2 of RFC 6749 [2]. 146 The JSON structure in the payload response includes the top-level 147 members defined in Section 2.2 in the OAuth Token Introspection 148 specification [14]. It's recommended to only return the active 149 attribute considering the lossy and constrained nature of CoAP client 150 and server network and capacity. 152 Note that the HTTP "Cache-Control" parameters MAY be used in the CoAP 153 response message. 155 6. Example 157 For example, the client makes a CoAP request carrying the 158 introspection request protected with DTLS to the authorization 159 server. It then receives a response containing metadata about the 160 token. 162 In the example below content-type 51 corresponds to the 'application/ 163 x-www-form-urlencoded'. 165 Authorization 166 Client Server 167 | | 168 |<=======>| DTLS Connection Establishment 169 | | 170 +-------->| Header: POST (T=CON, Code=0.02, MID=0x7d34, 171 | POST | ct=51, Uri-Path:"introspect" 172 | | Payload: cid=qwerty&cs=2123&t=X3241Affw.4233-99JXJ 173 | | 174 |<--------+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34, 175 | 2.05 | ct=50) 176 | | Payload: 177 | | 179 := 180 { 181 "active": true 182 } 184 Figure 1: Example CoAP Introspection Exchange. 186 7. Security Considerations 188 TBD 190 8. IANA Considerations 192 TBD 194 9. Acknowledgements 196 The author would like to thank Justin Richer for his work on [14] 197 richer-oauth-introspection and Hannes Tschofenigs [10] and [11]. 198 This document is heavily inspired from those document's and it 199 borrows a lot of texts from there work. The author would also like 200 to thank Samuel Erdtman for valuable input. 202 10. Change Log 204 [[This section to be removed prior to publication as an RFC]] 206 Draft 01 - Using same request format as OAuth2 introspection endpoint 207 to ease proxying. 209 11. References 211 11.1. Normative References 213 [1] Bradner, S., "Key words for use in RFCs to Indicate 214 Requirement Levels", BCP 14, RFC 2119, March 1997. 216 [2] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 217 6749, October 2012. 219 [3] Saint-Andre, P. and J. Hodges, "Representation and 220 Verification of Domain-Based Application Service Identity 221 within Internet Public Key Infrastructure Using X.509 222 (PKIX) Certificates in the Context of Transport Layer 223 Security (TLS)", RFC 6125, March 2011. 225 [4] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 226 Application Protocol (CoAP)", RFC 7252, June 2014. 228 [5] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 229 Security Version 1.2", RFC 6347, January 2012. 231 [6] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 232 Framework: Bearer Token Usage", RFC 6750, October 2012. 234 [7] Crockford, D., "The application/json Media Type for 235 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 237 [8] Tschofenig, H. and T. Fossati, "A TLS/DTLS Profile for the 238 Internet of Things", draft-ietf-dice-profile-10 (work in 239 progress), March 2015. 241 [9] Tschofenig, H., "OAuth 2.0: Audience Information", draft- 242 tschofenig-oauth-audience-00 (work in progress), February 243 2013. 245 11.2. Informative References 247 [10] Tschofenig, H., "The OAuth 2.0 Bearer Token Usage over the 248 Constrained Application Protocol (CoAP)", draft- 249 tschofenig-ace-oauth-bt-01 (work in progress), March 2015. 251 [11] Tschofenig, H., "The OAuth 2.0 Internet of Things (IoT) 252 Client Credentials Grant", draft-tschofenig-ace-oauth- 253 iot-01 (work in progress), March 2015. 255 [12] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 256 (JWT)", draft-ietf-oauth-json-web-token-32 (work in 257 progress), December 2014. 259 [13] Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 260 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 261 Architecture", draft-hunt-oauth-pop-architecture-02 (work 262 in progress), June 2014. 264 [14] Richer, J., "OAuth Token Introspection", draft-richer- 265 oauth-introspection-06 (work in progress), July 2014. 267 [15] Bormann, C., "An Authorization Information Format (AIF) 268 for ACE", draft-bormann-core-ace-aif-01 (work in 269 progress), July 2014. 271 [16] Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. 272 Kumar, "ACE use cases", draft-seitz-ace-usecases-02 (work 273 in progress), October 2014. 275 Author's Address 276 Erik Wahlstroem 277 Nexus Technology 278 Sweden 280 Email: erik.wahlstrom@nexusgroup.com 281 URI: https://www.nexusgroup.com