idnits 2.17.1 draft-wahlstroem-ace-oauth-introspection-00.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 (October 1, 2014) is 3495 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: 'RFC6749' on line 118 -- Looks like a reference, but probably isn't: 'RFC7009' on line 132 == Unused Reference: '3' is defined on line 220, but no explicit reference was found in the text == Unused Reference: '8' is defined on line 238, but no explicit reference was found in the text == Unused Reference: '9' is defined on line 242, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 256, but no explicit reference was found in the text == Unused Reference: '13' is defined on line 260, but no explicit reference was found in the text == Unused Reference: '15' is defined on line 268, but no explicit reference was found in the text == Unused Reference: '16' is defined on line 272, 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-04 == Outdated reference: A later version (-01) exists of draft-tschofenig-ace-oauth-bt-00 == Outdated reference: A later version (-01) exists of draft-tschofenig-ace-oauth-iot-00 == Outdated reference: A later version (-32) exists of draft-ietf-oauth-json-web-token-27 == Outdated reference: A later version (-09) exists of draft-bormann-core-ace-aif-01 == Outdated reference: A later version (-02) exists of draft-seitz-ace-usecases-01 Summary: 4 errors (**), 0 flaws (~~), 14 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 October 1, 2014 5 Expires: April 4, 2015 7 OAuth 2.0 Introspection over the Constrained Application Protocol (CoAP) 8 draft-wahlstroem-ace-oauth-introspection-00.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 April 4, 2015. 35 Copyright Notice 37 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . 4 57 6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 7. Security Considerations . . . . . . . . . . . . . . . . . . . 5 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 60 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 61 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 10.1. Normative References . . . . . . . . . . . . . . . . . . 5 63 10.2. Informative References . . . . . . . . . . . . . . . . . 6 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 66 1. Introduction 68 OAuth2 enables clients to access protected resources by obtaining an 69 access token, which is defined in "The OAuth 2.0 Authorization 70 Framework" [2] as "a string representing an access authorization 71 issued to the client", rather than using the resource owner's 72 credentials directly. 74 Tokens are issued to clients by an authorization server and the 75 client uses the access token to access the protected resources hosted 76 by the resource server. This document defines a way for a holder of 77 this token, mostly Clients and Resource Servers, to get metadata like 78 validity and scopes for the token. The OAuth Token Introspection 79 specification [14] defines a way to validate the token using HTTP 80 POST or HTTP GET. This document reuses the work done in the OAuth 81 Token Introspection and defines a mapping of the request and response 82 to CoAP [4] to be used by constrained devices. 84 2. Terminology 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in "Key words for use in 89 RFCs to Indicate Requirement Levels" [1]. 91 This document also re-uses terminology from RFC 6749 [2] and RFC 6750 92 [6]. 94 3. Introspection CoAP Endpoint 96 The Introspection CoAP Endpoint responds to CoAP Confirmable requests 97 from token holders, particularly Clients and Resource Servers. The 98 endpoint takes a single parameter representing the token (and 99 optionally further authentication) and returns a JSON [7] document 100 representing the meta information surrounding the token. The 101 endpoint MUST be protected by DTLS [5] or equivalent. 103 4. Introspection Request 105 The token holder makes a request to the Introspection CoAP Endpoint 106 by adding the following parameters using the "application/x-www-form- 107 urlencoded" format with a character encoding of UTF-8 in the CoAP 108 request entity-body: 110 In order to prevent man-in-the-middle attacks, the client MUST 111 require the use of DTLS with server authentication for any request 112 sent to the authorization and token endpoints. If certificate-based 113 server authentication is used then the client MUST validate the TLS 114 certificate of the authorization server, as defined by RFC6125. 116 The Endpoint SHOULD also require some form of authentication to 117 access this endpoint, such as the Client Authentication as described 118 in OAuth 2.0 [RFC6749] or equivalent. 120 t: REQUIRED. The string value of the token. 122 rid: OPTIONAL. A service-specific string identifying the resource 123 that the client doing the introspection is asking about. 125 hint: OPTIONAL. A hint about the type of the token submitted for 126 introspection. Clients MAY pass this parameter in order to help 127 the authorization server to optimize the token lookup. If the 128 server is unable to locate the token using the given hint, it MUST 129 extend its search across all of its supported token types. An 130 authorization server MAY ignore this parameter, particularly if it 131 is able to detect the token type automatically. Values for this 132 field are defined in OAuth Token Revocation [RFC7009]. 134 cid: OPTIONAL. Client id if client password defined in section 135 2.3.1 in RFC 6750 [6] is used. 137 cid: OPTIONAL. Client secret if client password defined in section 138 2.3.1 in RFC 6750 [6] is used. 140 Question: Should we keep, the longer, original attribute names to 141 make it easier for CoAP-HTTP proxies and Authorization Server 142 implementations? 144 5. Introspection Response 146 If the introspection request is valid and authorized, the 147 authorization server responds with a CoAP message using Content 148 response code with the response encoded as a JSON structure in the 149 payload of the message. If the request failed client authentication 150 or is invalid, the authorization server returns an error response 151 using the CoAP 4.00 'Bad Request' response code with the error 152 messages defined in Section 5.2 of RFC 6749 [2]. 154 The JSON structure in the payload response includes the top-level 155 members defined in Section 2.2 in the OAuth Token Introspection 156 specification [14]. It's recommended to only return the active 157 attribute considering the lossy and constrained nature of CoAP client 158 and server network and capacity. 160 Note that the HTTP "Cache-Control" parameters MAY be used in the CoAP 161 response message. 163 6. Example 165 For example, the client makes a CoAP request carrying the 166 introspection request protected with DTLS to the authorization 167 server. It then receives a response containing metadata about the 168 token. 170 In the example below content-type 51 corresponds to the 'application/ 171 x-www-form-urlencoded'. 173 Authorization 174 Client Server 175 | | 176 |<=======>| DTLS Connection Establishment 177 | | 178 +-------->| Header: POST (T=CON, Code=0.02, MID=0x7d34, 179 | POST | ct=51, Uri-Path:"introspect" 180 | | Payload: cid=qwerty&cs=2123&t=X3241Affw.4233-99JXJ 181 | | 182 |<--------+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34, 183 | 2.05 | ct=50) 184 | | Payload: 185 | | 187 := 188 { 189 "active": true 190 } 192 Figure 1: Example CoAP Introspection Exchange. 194 7. Security Considerations 196 TBD 198 8. IANA Considerations 200 TBD 202 9. Acknowledgements 204 The author would like to thank Justin Richer for his work on [14] 205 richer-oauth-introspection and Hannes Tschofenigs [10] and [11]. 206 This document is heavily inspired from those document's and it 207 borrows a lot of texts from there work. The author would also like 208 to thank Samuel Erdtman for valuable input. 210 10. References 212 10.1. Normative References 214 [1] Bradner, S., "Key words for use in RFCs to Indicate 215 Requirement Levels", BCP 14, RFC 2119, March 1997. 217 [2] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 218 6749, October 2012. 220 [3] Saint-Andre, P. and J. Hodges, "Representation and 221 Verification of Domain-Based Application Service Identity 222 within Internet Public Key Infrastructure Using X.509 223 (PKIX) Certificates in the Context of Transport Layer 224 Security (TLS)", RFC 6125, March 2011. 226 [4] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 227 Application Protocol (CoAP)", RFC 7252, June 2014. 229 [5] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 230 Security Version 1.2", RFC 6347, January 2012. 232 [6] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 233 Framework: Bearer Token Usage", RFC 6750, October 2012. 235 [7] Crockford, D., "The application/json Media Type for 236 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 238 [8] Tschofenig, H., "A Datagram Transport Layer Security 239 (DTLS) 1.2 Profile for the Internet of Things", draft- 240 ietf-dice-profile-04 (work in progress), August 2014. 242 [9] Tschofenig, H., "OAuth 2.0: Audience Information", draft- 243 tschofenig-oauth-audience-00 (work in progress), February 244 2013. 246 10.2. Informative References 248 [10] Tschofenig, H., "The OAuth 2.0 Bearer Token Usage over the 249 Constrained Application Protocol (CoAP)", draft- 250 tschofenig-ace-oauth-bt-00 (work in progress), July 2014. 252 [11] Tschofenig, H., "The OAuth 2.0 Internet of Things (IoT) 253 Client Credentials Grant", draft-tschofenig-ace-oauth- 254 iot-00 (work in progress), July 2014. 256 [12] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 257 (JWT)", draft-ietf-oauth-json-web-token-27 (work in 258 progress), September 2014. 260 [13] Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 261 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 262 Architecture", draft-hunt-oauth-pop-architecture-02 (work 263 in progress), June 2014. 265 [14] Richer, J., "OAuth Token Introspection", draft-richer- 266 oauth-introspection-06 (work in progress), July 2014. 268 [15] Bormann, C., "An Authorization Information Format (AIF) 269 for ACE", draft-bormann-core-ace-aif-01 (work in 270 progress), July 2014. 272 [16] Seitz, L., Gerdes, S., Selander, G., Mani, M., and S. 273 Kumar, "ACE use cases", draft-seitz-ace-usecases-01 (work 274 in progress), July 2014. 276 Author's Address 278 Erik Wahlstroem 279 Nexus Technology 280 Sweden 282 Email: erik.wahlstrom@nexusgroup.com 283 URI: https://www.nexusgroup.com