idnits 2.17.1 draft-campbell-oauth-sts-03.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 23, 2015) is 3192 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) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) == Outdated reference: A later version (-07) exists of draft-ietf-oauth-pop-key-distribution-01 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group B. Campbell 3 Internet-Draft J. Bradley 4 Intended status: Standards Track Ping Identity 5 Expires: January 24, 2016 July 23, 2015 7 OAuth 2.0 Token Exchange: an STS for the REST of us 8 draft-campbell-oauth-sts-03 10 Abstract 12 An OAuth 2.0 framework for exchanging security tokens enabling 13 authorization servers to act as lightweight HTTP and JSON based 14 security token services. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on January 24, 2016. 33 Copyright Notice 35 Copyright (c) 2015 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 52 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.3. Delegation vs. Impersonation Semantics . . . . . . . . . 3 54 2. Security Token Request . . . . . . . . . . . . . . . . . . . 4 55 3. Security Token Response . . . . . . . . . . . . . . . . . . . 6 56 3.1. Successful Security Token Response . . . . . . . . . . . 6 57 3.2. Error Response . . . . . . . . . . . . . . . . . . . . . 7 58 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 60 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 61 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 63 7.2. Informative References . . . . . . . . . . . . . . . . . 8 64 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 9 65 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 10 66 Appendix C. Document History . . . . . . . . . . . . . . . . . . 10 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 69 1. Introduction 71 A security token service (STS) is a service capable of validating and 72 issuing security tokens, which enables web service clients to obtain 73 appropriate temporary access credentials for resources in 74 heterogeneous environments or across security domains. Clients have 75 historically used WS-Trust [WS-Trust] as the protocol to interact 76 with an STS for token exchange. However WS-Trust is a fairly 77 heavyweight framework which uses XML, SOAP, WS-Security, XML- 78 Signatures, etc. while the trend in modern web development has been 79 towards more lightweight services utilizing RESTful patterns and 80 JSON. The OAuth 2.0 Authorization Framework [RFC6749] and OAuth 2.0 81 Bearer Tokens [RFC6750] have emerged as popular standards for 82 authorizing and securing access to HTTP and RESTful resources but do 83 not provide all that is needed to support generic STS interactions. 85 This specification defines a lightweight protocol extending OAuth 2.0 86 that enables clients to request and obtain security tokens from 87 authorization servers acting in the role of an STS. There is support 88 for enabling one party to act on behalf of another as well as 89 enabling one party to delegate constrained authority to another. 90 Similar to OAuth 2.0, this specification focuses on client developer 91 simplicity and requires only an HTTP client and JSON parser, which 92 are nearly universally available in modern development environments. 93 The STS protocol defined in this specification is not itself RESTful 94 (an STS doesn't lend itself particularly well to a REST approach) but 95 does utilize communication patterns and data formats that should be 96 more palatable to developers accustom to working with RESTful 97 systems. 99 A new security token request grant type and the associated specific 100 parameters for a security token request to the token endpoint are 101 defined by this specification. A security token response is a normal 102 OAuth 2.0 response from the token endpoint with some additional 103 parameters defined herein to provide information to the client. 105 The security tokens obtained from an STS could be used in a variety 106 of contexts, the specifics of which are beyond the scope of this 107 document. 109 The scope of this specification is limited to the definition of a 110 framework and basic wire protocol for an STS style token exchange 111 utilizing OAuth 2.0. The syntax, semantics and security 112 characteristics of the tokens themselves (both those presented to the 113 AS and those obtained by the client) are explicitly out of scope and 114 no requirements are placed on the trust model in which an 115 implementation might be deployed. Additional profiles may provide 116 more detailed requirements around the specific nature of the parties 117 and trust involved, whether signatures and/or encryption of tokens is 118 required, etc., however, such details will often be policy decisions 119 made with respect to the specific needs of individual deployments and 120 will be configured or implemented accordingly. 122 1.1. Requirements Notation and Conventions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in RFC 127 2119 [RFC2119]. 129 1.2. Terminology 131 This specification uses the terms "authorization server" "token 132 endpoint", "access token request", "access token response", and 133 "client" defined by OAuth 2.0 [RFC6749]. 135 1.3. Delegation vs. Impersonation Semantics 137 When principal A impersonates principal B, A is given all the rights 138 that B has within some defined rights context. Whereas, with 139 delegation semantics, principal A still has its own identity separate 140 from B and it is explicitly understood that while B may have 141 delegated its rights to A, any actions taken are being taken by A and 142 not B. In a sense, A is an agent for B. 144 Delegation semantics are therefore different than impersonation 145 semantics, with which it is sometimes confused. When principal A 146 impersonates principal B, then in so far as any entity receiving such 147 a token is concerned, they are actually dealing with B. It is true 148 that some members of the identity system might have awareness that 149 impersonation is going on but it is not a requirement. For all 150 intents and purposes, when A is impersonating B, A is B. 152 A security token with delegation semantics is requested using this 153 framework by including both an on_behalf_of token and an act_as token 154 in the request. The on_behalf_of token represents the identity of 155 the party on behalf of whom the token is being requested while the 156 act_as token represents the identity of the party to whom the access 157 rights of the returned token are being delegated. In this case, the 158 token returned to the client will contain claims about both parties. 160 A security token with impersonation semantics is requested using this 161 framework by including an on_behalf_of token in the request and 162 omitting the act_as token. The on_behalf_of token represents the 163 identity of the party on behalf of whom the token is being requested 164 the token returned to the client will contain claims about that 165 party. 167 2. Security Token Request 169 A client requests a security token by making a token request to the 170 authorization server's token endpoint using the extension grant type 171 mechanism defined in Section 4.5 of OAuth 2.0 [RFC6749]. 173 Client authentication to the authorization server is done using the 174 normal mechanisms provided by OAuth 2.0. Section 2.3.1 of The OAuth 175 2.0 Authorization Framework [RFC6749] defines password-based 176 authentication of the client, however, client authentication is 177 extensible and other mechanisms are allowed. For example, [RFC7522] 178 and [RFC7523] define client authentication using SAML Assertions and 179 JSON Web Tokens respectively. Other mechanisms, such as TLS client 180 authentication, are also possible. The supported methods of client 181 authentication and whether or not to allow unauthenticated or 182 unidentified clients are deployment decisions that are at the 183 discretion of the authorization server. 185 The client makes a general security token request to the token 186 endpoint with an extension grant type by including the following 187 parameters using the "application/x-www-form-urlencoded" format with 188 a character encoding of UTF-8 in the HTTP request entity-body: 190 grant_type 191 REQUIRED. The value "urn:ietf:params:oauth:grant-type:security- 192 token-request" indicates that it is a security token request. 194 aud 195 OPTIONAL. Indicates the location of the service or resource where 196 the client intends to use the requested security token. The value 197 MUST be an absolute URI as defined by Section 4.3 of [RFC3986]. 198 The URI MAY include a query component but MUST NOT include a 199 fragment component. When applicable, the value of this parameter 200 also typically informs the audience restrictions on the returned 201 security token. 203 scope 204 OPTIONAL. A list of space-delimited, case-sensitive strings that 205 allow the client to specify the desired scope of requested 206 security token in the context of the service or resource where the 207 token will be used (possibly indicated by the "aud" parameter). 209 requested_security_token_type 210 OPTIONAL. Identifier for the type of the requested security 211 token. For example, a JWT can be requested with the identifier 212 "urn:ietf:params:oauth:token-type:jwt", which is defined in JSON 213 Web Token [RFC7519]. If the requested type is unspecified, the 214 returned token type is at the discretion of the authorization 215 server and may be dictated by knowledge of the requirements of the 216 service or resource whose location is indicated by the "aud" 217 parameter. 219 on_behalf_of 220 REQUIRED. The value of this request parameter is a security token 221 which represents the identity of the party on behalf of whom the 222 request is being made. Typically the subject of this token will 223 be the primary subject of the security token returned in response 224 to this request. 226 on_behalf_of_token_type 227 REQUIRED. An identifier that indicates the type of the security 228 token sent with the "on_behalf_of" parameter. 230 act_as 231 OPTIONAL. The value of this request parameter is a security token 232 which represents the identity of the party that is authorized to 233 use the requested security token. When this parameter is present, 234 it indicates that the client wants a token that contains claims 235 about two distinct entities: 1) the entity represented by the 236 token in the "on_behalf_of" parameter as the primary subject and 237 2) the entity represented by this token as a party who is 238 authorized to act on behalf of that subject. 240 act_as_token_type 241 REQUIRED when the "act_as" parameter is present in the request but 242 MUST NOT be included otherwise. The value of this parameter is an 243 identifier that indicates the type of the security token sent with 244 the "act_as" parameter. 246 3. Security Token Response 248 The authorization server responds to a security token request with a 249 normal OAuth 2.0 response from the token endpoint as defined in 250 Section 5 of RFC 6749 [RFC6749]. Additional details and explanation 251 are provided in the following subsections. 253 3.1. Successful Security Token Response 255 If the request is valid and meets all policy and other criteria of 256 the authorization server, a successful token response is constructed 257 by adding the following parameters to the entity-body of the HTTP 258 response using the "application/json" media type as defined by 259 [RFC4627] and an HTTP 200 status code. The parameters are serialized 260 into a JavaScript Object Notation (JSON) structure by adding each 261 parameter at the top level. Parameter names and string values are 262 included as JSON strings. Numerical values are included as JSON 263 numbers. The order of parameters does not matter and can vary. 265 access_token 266 REQUIRED. The security token issued by the authorization server 267 in response to the security token request. The "access_token" 268 parameter from Section 5.1 of RFC 6749 [RFC6749] is used here to 269 carry the requested security token, which allows this token 270 exchange framework to use the existing OAuth 2.0 request and 271 response constructs defined for the token endpoint. 273 security_token_type 274 REQUIRED. An identifier for the general type of the returned 275 security token. For example, if the security token is a JWT, this 276 value of the "security_token_type" is 277 "urn:ietf:params:oauth:token-type:jwt". 279 token_type 280 REQUIRED. A case insensitive value describing the type of the 281 token issued as discussed in Section 7.1 of RFC 6749 [RFC6749]. 282 Note that this value is different from the value of the 283 "security_token_type" and provides the client with information 284 about how to utilize the token to access protected resources. For 285 example, a value of "Bearer" as defined in [RFC6750] indicates 286 that the security token is a bearer token and the client can 287 simply present it as is without any additional proof of 288 eligibility beyond the contents of the token itself. A value of 289 "PoP", on the other hand, indicates that use of the token will 290 require demonstrating possession of a cryptographic key associated 291 with the security token ([I-D.ietf-oauth-pop-key-distribution] 292 describes the "PoP" token type). 294 expires_in 295 RECOMMENDED. The validity lifetime, in seconds, of the issued 296 security token. For example, the value 3600 denotes that the 297 token will expire in one hour from the time the response was 298 generated. 300 scope 301 OPTIONAL, if the scope of the security token is identical to the 302 scope requested by the client; otherwise, REQUIRED. 304 refresh_token 305 NOT RECOMMENDED. Refresh tokens will typically not be issued in 306 response to a "urn:ietf:params:oauth:grant-type:security-token- 307 request" grant type requests. 309 3.2. Error Response 311 If either the "on_behalf_of" or "act_as" tokens are invalid for any 312 reason, or are unacceptable based on policy, the authorization server 313 MUST construct an error response as defined in Section 5.2 of OAuth 314 2.0 [RFC6749] The value of the "error" parameter MUST be the 315 "invalid_grant" error code. The authorization server MAY include 316 additional information regarding the reasons for the error using the 317 "error_description" or "error_uri" parameters. 319 4. Examples 321 [[ TODO: at least two examples, with and without act_as, showing a 322 request/response exchange and including some relevant internal 323 details of the tokens involved ]] 325 5. IANA Considerations 327 [[ TODO ]] The "urn:ietf:params:oauth:grant-type:security-token- 328 request" Grant Type is to be registered in the IANA 329 urn:ietf:params:oauth registry established in [RFC6755]. 331 [[ TODO ]] Other parameters like "requested_security_token_type", 332 "on_behalf_of", "on_behalf_of_token_type", "act_as", etc. need to be 333 registered in the appropriate registries. The "aud" parameter needs 334 to be registered too but that may well get done in 336 [I-D.ietf-oauth-pop-key-distribution] and aud may/does have wider 337 applicability so perhaps deserves it's own little spec? 339 6. Security Considerations 341 [[ TODO ]] 343 7. References 345 7.1. Normative References 347 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 348 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 349 RFC2119, March 1997, 350 . 352 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 353 Resource Identifier (URI): Generic Syntax", STD 66, RFC 354 3986, DOI 10.17487/RFC3986, January 2005, 355 . 357 [RFC4627] Crockford, D., "The application/json Media Type for 358 JavaScript Object Notation (JSON)", RFC 4627, DOI 359 10.17487/RFC4627, July 2006, 360 . 362 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 363 RFC 6749, DOI 10.17487/RFC6749, October 2012, 364 . 366 7.2. Informative References 368 [I-D.ietf-oauth-pop-key-distribution] 369 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 370 "OAuth 2.0 Proof-of-Possession: Authorization Server to 371 Client Key Distribution", draft-ietf-oauth-pop-key- 372 distribution-01 (work in progress), March 2015. 374 [I-D.jones-oauth-token-exchange] 375 Jones, M., Nadalin, A., and C. Baker, "OAuth 2.0 Token 376 Exchange", draft-jones-oauth-token-exchange-01 (work in 377 progress), July 2014. 379 [OpenID.Core] 380 Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. 381 Mortimore, "OpenID Connect Core 1.0", February 2014. 383 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 384 Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/ 385 RFC6750, October 2012, 386 . 388 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 389 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 390 . 392 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 393 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 394 . 396 [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security 397 Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 398 Client Authentication and Authorization Grants", RFC 7522, 399 DOI 10.17487/RFC7522, May 2015, 400 . 402 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 403 (JWT) Profile for OAuth 2.0 Client Authentication and 404 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 405 2015, . 407 [WS-Trust] 408 Nadalin, A., Goodner, M., Gudgin, M., Barbir, A., and H. 409 Granqvist, "WS-Trust 1.4 (incorporating Approved Errata 410 01)", February 2012, . 413 Appendix A. Open Issues 415 Some, but surely not all, decisions to be made with potential 416 associated draft updates: 418 o Are the constructs for expressing delegation and impersonation the 419 'right' ones? Do they provide sufficient flexibility while being 420 reasonably understandable and implementable? 422 o Does it really make sense to use the act_as and on_behalf_of 423 terms? They come with some baggage. 425 o More guidance on what delegation should look like in the returned 426 token? I.e. refer to "azp" in [OpenID.Core]? Or something else? 428 o Do we need to codify if/how the identity of the client end up in 429 returned token? Should it be an AS decision? A special case of 430 delegation/act_as? Something else? 432 o Does the error response need a way to convey additional 433 information beyond what OAuth 2.0 provides? 435 o Exactly how the presentation of PoP or other non-bearer tokens 436 works. Should a challenge-response mechanism be considered rather 437 than trying to stuff the whole PoP into a single request? 439 Appendix B. Acknowledgements 441 The author wishes to thank Michael Jones for bringing forth the 442 concept of OAuth 2.0 Token Exchange with 443 [I-D.jones-oauth-token-exchange]. This draft borrows heavily from 444 Jones' work while striving to provide a syntax that is more 445 consistent with OAuth 2.0 [RFC6749], which will hopefully be more 446 familiar to developers and easier to understand and implement. 448 The author also wishes to thank John Bradley for his endless patience 449 and willingness to share his expertise. 451 The following individuals also contributed ideas, feedback, and 452 wording that shaped and formed the final specification: 454 Chuck Mortimore, Justin Richter, Phil Hunt, and Scott Tomilson. 456 Appendix C. Document History 458 [[ to be removed by the RFC Editor before publication as an RFC ]] 460 -03 462 o The aud parameter is now OPTIONAL rather than REQUIRED. 464 o Update references for JWT and SAML/JWT assertion frameworks to the 465 new RFCs. 467 -02 469 o Refreshing draft before -01 expires. 471 -01 473 o Add Bradley as an author. 475 -00 477 o Gotta start somewhere... 479 Authors' Addresses 481 Brian Campbell 482 Ping Identity 484 Email: brian.d.campbell@gmail.com 486 John Bradley 487 Ping Identity 489 Email: ve7jtb@ve7jtb.com