idnits 2.17.1 draft-tschofenig-oauth-audience-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 draft header indicates that this document updates RFC6750, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 18, 2013) is 4084 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-02 == Outdated reference: A later version (-32) exists of draft-ietf-oauth-json-web-token-06 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth H. Tschofenig, Ed. 3 Internet-Draft Nokia Siemens Networks 4 Updates: 6750 (if approved) February 18, 2013 5 Intended status: Standards Track 6 Expires: August 22, 2013 8 OAuth 2.0: Audience Information 9 draft-tschofenig-oauth-audience-00.txt 11 Abstract 13 The OAuth 2.0 Bearer Token specification allows any party in 14 possession of a bearer token to get access to the associated 15 resources (without demonstrating possession of a cryptographic key). 16 To prevent misuse, two important security assumptions must hold: 17 bearer tokens must be protected from disclosure in storage and in 18 transport and the access token must only be valid for use with a 19 specific resource server (the audience) and with a specific scope. 21 This document defines a new header that is used by the client to 22 indicate what resource server, as the intended recipient, it wants to 23 access. This information is subsequently also communicated by the 24 authorization server securely to the resource server, for example 25 within the audience field of the access token. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on August 22, 2013. 44 Copyright Notice 46 Copyright (c) 2013 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Audience Parameter . . . . . . . . . . . . . . . . . . . . . . 5 64 4. Processing Instructions . . . . . . . . . . . . . . . . . . . 6 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 68 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 70 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 1. Introduction 75 The OAuth 2.0 Bearer Token specification [1] allows any party in 76 possession of a bearer token to get access to the associated 77 resources (without demonstrating possession of a cryptographic key). 78 To prevent misuse, two important security assumptions must hold: 79 bearer tokens must be protected from disclosure in storage and in 80 transport and the access token must only be valid for use with a 81 specific resource server with a specific scope. 83 [1] describes this requirement in the following way: 85 "To deal with token redirect, it is important for the 86 authorization server to include the identity of the intended 87 recipients (the audience), typically a single resource server (or 88 a list of resource servers), in the token. Restricting the use of 89 the token to a specific scope is also RECOMMENDED." 91 In general, if there is an authorization restriction then the 92 respective parties must be aware of this restriction. In our case, 93 the respective parties are authorization server (who has a trust 94 relationship with the resource owner to accept for reject requests 95 for data sharing and creates the access token), the client (who 96 initiates the access to the protected resource), and the resource 97 server (who protects the access to the resource and grants only 98 access to those clients who have been approved by the authorization 99 server). 101 Unfortunately, at the time of writing of [1] the access token format 102 was still in early stages of the design and more details about how to 103 communicate the audience information between the different parties 104 was left unspecified. This document defines a new field for usage 105 with OAuth 2.0. Note that it is not only useful for OAuth 2.0 bearer 106 tokens but also for MAC tokens [5]: the authorization server needs 107 to be told which resource server has to obtain the session key 108 securely in order for the security properties to hold. 110 Restricting the usage of access tokens is important for several 111 reasons: First, a stolen access token cannot be used with resource 112 servers it has not been created for. Second, if the scope is 113 included it cannot be used for requesting access to resources that 114 exceed the indicated permissions. A resource server, who obtains an 115 access token legitimately, cannot access resources on behalf of the 116 resource owner at other resource servers. 118 2. Terminology 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 122 document are to be interpreted as described in RFC 2119 [2]. 124 3. Audience Parameter 126 When the client interacts with the resource server it constructs the 127 access token request to the token endpoint by adding the audience 128 parameter using the "application/x-www-form-urlencoded" format with a 129 character encoding of UTF-8 in the HTTP request entity-body. 131 The audience URI MUST be an absolute URI as defined by Section 4.3 of 132 [3]. It MAY include an "application/x-www-form-urlencoded" formatted 133 query component (Section 3.4 of [3] ). The URI MUST NOT include a 134 fragment component. 136 The ABNF syntax is defined as follows where by the "URI-reference" 137 definition is taken from [3]: 139 audience = URI-reference 141 [QUESTION: Is it OK to just assume a URI here as the audience 142 identifier?] 144 4. Processing Instructions 146 Step (0): As an initial step the client typically determines the 147 resource server it wants to interact with, for example, as part of 148 a discovery procedure. 150 [QUESTION: Should we talk about WebFinger or SWD to be more 151 specific?] 153 Step (1): The client starts the OAuth 2.0 protocol interaction 154 based on the selected grant type. 156 Step (2): When the client interacts with the token endpoint to 157 obtain an access token it MUST populate the newly defined 158 'audience' parameter with the information obtained in step (0). 160 Step (2): The resource server who obtains the request needs to 161 parse it to determine whether the provided audience value matches 162 any of the authorized resource servers it has a relationship with. 163 If the authorization server fails to parse the provided value it 164 MUST reject the request using an error response with the error 165 code "invalid_request". If the authorization server does not 166 consider the resource server acceptable then it MUST return an 167 error response with the error code "access_denied". In both cases 168 additional error information may be provided via the 169 error_description, and the error_uri parameters. If the request 170 has, however, been verified successfully then the authorization 171 server MUST include the audience claim into the access token with 172 the value copied from the audience field provided by the client. 173 In case the access token is encoded using the JSON Web Token 174 format [6] the "aud" claim MUST be used. The access token MUST be 175 protected against modification by protecting it with either a 176 digital signature or a keyed message digest. The authorization 177 server returns the access token to the client, as specified in 178 [4]. 180 [QUESTION: Should we just focus on a JSON-based encoding of 181 the access token since it is the only specified format?] 183 Step (3): The client follows the OAuth 2.0 specification [4] and 184 the specification relevant for the selected token type (e.g., the 185 bearer token specification) to interact with the resource server 186 to make a request to the protected resource with the attached 187 access token. 189 Step (4): When the resource server receives the access token it 190 verifies it according to chosen access token encoding. For 191 example, in case the JSON Web Token format is used then it must 192 adhere to the guidance in [6]. In any case, the resource server 193 MUST verify whether the URI contained in the "aud" claim matches 194 it's own. If the comparison fails the resource server MUST return 195 an error to the client. 197 [NOTE: More guidance is required in [6] regarding the matching 198 procedure.] 200 5. Security Considerations 202 The sole purpose of this document is to extend the OAuth 2.0 protocol 203 to improve security. 205 6. IANA Considerations 207 This document requires IANA to add a new value to the OAuth 208 parameters registry: 210 o Parameter name: audience 212 o Parameter usage location: token request 214 o Change controller: IETF 216 o Specification document(s): [[This document.] 218 7. Acknowledgments 220 The author would like to thank Leif Johansson, and Eve Maler for 221 their feedback. 223 8. References 225 8.1. Normative References 227 [1] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: 228 Bearer Token Usage", RFC 6750, October 2012. 230 [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement 231 Levels", BCP 14, RFC 2119, March 1997. 233 [3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 234 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 235 January 2005. 237 [4] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, 238 October 2012. 240 8.2. Informative References 242 [5] Richer, J., Mills, W., and H. Tschofenig, "OAuth 2.0 Message 243 Authentication Code (MAC) Tokens", 244 draft-ietf-oauth-v2-http-mac-02 (work in progress), 245 November 2012. 247 [6] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", 248 draft-ietf-oauth-json-web-token-06 (work in progress), 249 December 2012. 251 Author's Address 253 Hannes Tschofenig (editor) 254 Nokia Siemens Networks 255 Linnoitustie 6 256 Espoo 02600 257 Finland 259 Phone: +358 (50) 4871445 260 Email: Hannes.Tschofenig@gmx.net 261 URI: http://www.tschofenig.priv.at