idnits 2.17.1 draft-ietf-oauth-assertions-17.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, 2014) is 3563 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 (-30) exists of draft-ietf-oauth-dyn-reg-16 Summary: 0 errors (**), 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 Ping Identity 4 Intended status: Standards Track C. Mortimore 5 Expires: January 24, 2015 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 July 23, 2014 11 Assertion Framework for OAuth 2.0 Client Authentication and 12 Authorization Grants 13 draft-ietf-oauth-assertions-17 15 Abstract 17 This specification provides a framework for the use of assertions 18 with OAuth 2.0 in the form of a new client authentication mechanism 19 and a new authorization grant type. Mechanisms are specified for 20 transporting assertions during interactions with a token endpoint, as 21 well as general processing rules. 23 The intent of this specification is to provide a common framework for 24 OAuth 2.0 to interwork with other identity systems using assertions, 25 and to provide alternative client authentication mechanisms. 27 Note that this specification only defines abstract message flows and 28 processing rules. In order to be implementable, companion 29 specifications are necessary to provide the corresponding concrete 30 instantiations. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on January 24, 2015. 49 Copyright Notice 51 Copyright (c) 2014 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 4 68 3. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 4. Transporting Assertions . . . . . . . . . . . . . . . . . . . 7 70 4.1. Using Assertions as Authorization Grants . . . . . . . . 7 71 4.1.1. Error Responses . . . . . . . . . . . . . . . . . . . 8 72 4.2. Using Assertions for Client Authentication . . . . . . . 8 73 4.2.1. Error Responses . . . . . . . . . . . . . . . . . . . 9 74 5. Assertion Content and Processing . . . . . . . . . . . . . . 10 75 5.1. Assertion Metamodel . . . . . . . . . . . . . . . . . . . 10 76 5.2. General Assertion Format and Processing Rules . . . . . . 11 77 6. Common Scenarios . . . . . . . . . . . . . . . . . . . . . . 12 78 6.1. Client Authentication . . . . . . . . . . . . . . . . . . 12 79 6.2. Client Acting on Behalf of Itself . . . . . . . . . . . . 13 80 6.3. Client Acting on Behalf of a User . . . . . . . . . . . . 13 81 6.3.1. Client Acting on Behalf of an Anonymous User . . . . 13 82 7. Interoperability Considerations . . . . . . . . . . . . . . . 14 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 84 8.1. Forged Assertion . . . . . . . . . . . . . . . . . . . . 15 85 8.2. Stolen Assertion . . . . . . . . . . . . . . . . . . . . 15 86 8.3. Unauthorized Disclosure of Personal Information . . . . . 16 87 8.4. Privacy Considerations . . . . . . . . . . . . . . . . . 17 88 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 89 9.1. assertion Parameter Registration . . . . . . . . . . . . 17 90 9.2. client_assertion Parameter Registration . . . . . . . . . 17 91 9.3. client_assertion_type Parameter Registration . . . . . . 18 92 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 93 10.1. Normative References . . . . . . . . . . . . . . . . . . 18 94 10.2. Informative References . . . . . . . . . . . . . . . . . 18 95 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 96 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 99 1. Introduction 101 An assertion is a package of information that facilitates the sharing 102 of identity and security information across security domains. 103 Section 3 provides a more detailed description of the concept of an 104 assertion for the purpose of this specification. 106 OAuth 2.0 [RFC6749] is an authorization framework that enables a 107 third-party application to obtain limited access to a protected HTTP 108 resource. In OAuth, those third-party applications are called 109 clients; they access protected resources by presenting an access 110 token to the HTTP resource. Access tokens are issued to clients by 111 an authorization server with the (sometimes implicit) approval of the 112 resource owner. These access tokens are typically obtained by 113 exchanging an authorization grant, which represents the authorization 114 granted by the resource owner (or by a privileged administrator). 115 Several authorization grant types are defined to support a wide range 116 of client types and user experiences. OAuth also provides an 117 extensibility mechanism for defining additional grant types, which 118 can serve as a bridge between OAuth and other protocol frameworks. 120 This specification provides a general framework for the use of 121 assertions as authorization grants with OAuth 2.0. It also provides 122 a framework for assertions to be used for client authentication. It 123 provides generic mechanisms for transporting assertions during 124 interactions with an authorization server's token endpoint, as well 125 as general rules for the content and processing of those assertions. 126 The intent is to provide an alternative client authentication 127 mechanism (one that doesn't send client secrets), as well as to 128 facilitate the use of OAuth 2.0 in client-server integration 129 scenarios, where the end-user may not be present. 131 This specification only defines abstract message flows and processing 132 rules. In order to be implementable, companion specifications are 133 necessary to provide the corresponding concrete instantiations. For 134 instance, SAML 2.0 Profile for OAuth 2.0 Client Authentication and 135 Authorization Grants [I-D.ietf-oauth-saml2-bearer] defines a concrete 136 instantiation for SAML 2.0 assertions and JSON Web Token (JWT) 137 Profile for OAuth 2.0 Client Authentication and Authorization Grants 138 [I-D.ietf-oauth-jwt-bearer] defines a concrete instantiation for 139 JWTs. 141 Note: The use of assertions for client authentication is orthogonal 142 to and separable from using assertions as an authorization grant. 143 They can be used either in combination or separately. Client 144 assertion authentication is nothing more than an alternative way for 145 a client to authenticate to the token endpoint and must be used in 146 conjunction with some grant type to form a complete and meaningful 147 protocol request. Assertion authorization grants may be used with or 148 without client authentication or identification. Whether or not 149 client authentication is needed in conjunction with an assertion 150 authorization grant, as well as the supported types of client 151 authentication, are policy decisions at the discretion of the 152 authorization server. 154 2. Notational Conventions 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 158 document are to be interpreted as described in [RFC2119] . 160 Throughout this document, values are quoted to indicate that they are 161 to be taken literally. When using these values in protocol messages, 162 the quotes must not be used as part of the value. 164 3. Framework 166 An assertion is a package of information that allows identity and 167 security information to be shared across security domains. An 168 assertion typically contains information about a subject or 169 principal, information about the party that issued the assertion and 170 when was it issued, as well as the conditions under which the 171 assertion is to be considered valid, such as when and where it can be 172 used. 174 The entity that creates and signs or integrity protects the assertion 175 is typically known as the "Issuer" and the entity that consumes the 176 assertion and relies on its information is typically known as the 177 "Relying Party". In the context of this document, the authorization 178 server acts as a relying party. 180 Assertions used in the protocol exchanges defined by this 181 specification MUST always be protected against tampering using a 182 digital signature or a keyed message digest applied by the issuer. 183 An assertion MAY additionally be encrypted, preventing unauthorized 184 parties from inspecting the content. 186 Although this document does not define the processes by which the 187 client obtains the assertion (prior to sending it to the 188 authorization server), there are two common patterns described below. 190 In the first pattern, depicted in Figure 1, the client obtains an 191 assertion from a third party entity capable of issuing, renewing, 192 transforming, and validating security tokens. Typically such an 193 entity is known as a "Security Token Service" (STS) or just "Token 194 Service" and a trust relationship (usually manifested in the exchange 195 of some kind of key material) exists between the token service and 196 the relying party. The token service is the assertion issuer; its 197 role is to fulfill requests from clients, which present various 198 credentials, and mint assertions as requested, fill them with 199 appropriate information, and integrity protect them with a signature 200 or message authentication code. WS-Trust [OASIS.WS-Trust] is one 201 available standard for requesting security tokens (assertions). 203 Relying 204 Party Client Token Service 205 | | | 206 | | 1) Request Assertion | 207 | |------------------------>| 208 | | | 209 | | 2) Assertion | 210 | |<------------------------| 211 | 3) Assertion | | 212 |<-------------------------| | 213 | | | 214 | 4) OK or Failure | | 215 |------------------------->| | 216 | | | 217 | | | 219 Figure 1: Third Party Created Assertion 221 In the second pattern, depicted in Figure 2, the client creates 222 assertions locally. To apply the signatures or message 223 authentication codes to assertions, it has to obtain key material: 224 either symmetric keys or asymmetric key pairs. The mechanisms for 225 obtaining this key material are beyond the scope of this 226 specification. 228 Although assertions are usually used to convey identity and security 229 information, self-issued assertions can also serve a different 230 purpose. They can be used to demonstrate knowledge of some secret, 231 such as a client secret, without actually communicating the secret 232 directly in the transaction. In that case, additional information 233 included in the assertion by the client itself will be of limited 234 value to the relying party and, for this reason, only a bare minimum 235 of information is typically included in such an assertion, such as 236 information about issuing and usage conditions. 238 Relying 239 Party Client 240 | | 241 | | 1) Create 242 | | Assertion 243 | |--------------+ 244 | | | 245 | | 2) Assertion | 246 | |<-------------+ 247 | 3) Assertion | 248 |<-------------------------| 249 | | 250 | 4) OK or Failure | 251 |------------------------->| 252 | | 253 | | 255 Figure 2: Self-Issued Assertion 257 Deployments need to determine the appropriate variant to use based on 258 the required level of security, the trust relationship between the 259 entities, and other factors. 261 From the perspective of what must be done by the entity presenting 262 the assertion, there are two general types of assertions: 264 1. Bearer Assertions: Any entity in possession of a bearer assertion 265 (the bearer) can use it to get access to the associated resources 266 (without demonstrating possession of a cryptographic key). To 267 prevent misuse, bearer assertions need to be protected from 268 disclosure in storage and in transport. Secure communication 269 channels are required between all entities to avoid leaking the 270 assertion to unauthorized parties. 272 2. Holder-of-Key Assertions: To access the associated resources, the 273 entity presenting the assertion must demonstrate possession of 274 additional cryptographic material. The token service thereby 275 binds a key identifier to the assertion and the client has to 276 demonstrate to the relying party that it knows the key 277 corresponding to that identifier when presenting the assertion. 278 This mechanism provides additional security properties. 280 The protocol parameters and processing rules defined in this document 281 are intended to support a client presenting a bearer assertion to an 282 authorization server. The use of holder-of-key assertions are not 283 precluded by this document, but additional protocol details would 284 need to be specified. 286 4. Transporting Assertions 288 This section defines HTTP parameters for transporting assertions 289 during interactions with a token endpoint of an OAuth authorization 290 server. Because requests to the token endpoint result in the 291 transmission of clear-text credentials (in both the HTTP request and 292 response), all requests to the token endpoint MUST use TLS, as 293 mandated in Section 3.2 of OAuth 2.0 [RFC6749]. 295 4.1. Using Assertions as Authorization Grants 297 This section defines the use of assertions as authorization grants, 298 based on the definition provided in Section 4.5 of OAuth 2.0 299 [RFC6749]. When using assertions as authorization grants, the client 300 includes the assertion and related information using the following 301 HTTP request parameters: 303 grant_type 304 REQUIRED. The format of the assertion as defined by the 305 authorization server. The value MUST be an absolute URI. 307 assertion 308 REQUIRED. The assertion being used as an authorization grant. 309 Specific serialization of the assertion is defined by profile 310 documents. The serialization MUST be encoded for transport within 311 HTTP forms. It is RECOMMENDED that base64url be used. 313 scope 314 OPTIONAL. The requested scope as described in Section 3.3 of 315 OAuth 2.0 [RFC6749]. When exchanging assertions for access 316 tokens, the authorization for the token has been previously 317 granted through some out-of-band mechanism. As such, the 318 requested scope MUST be equal or lesser than the scope originally 319 granted to the authorized accessor. If the scope parameter and/or 320 value are omitted, the scope MUST be treated as equal to the scope 321 originally granted to the authorized accessor. The Authorization 322 Server MUST limit the scope of the issued access token to be equal 323 or lesser than the scope originally granted to the authorized 324 accessor. 326 Authentication of the client is optional, as described in 327 Section 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the 328 "client_id" is only needed when a form of client authentication that 329 relies on the parameter is used. 331 The following non-normative example demonstrates an assertion being 332 used as an authorization grant (with extra line breaks for display 333 purposes only): 335 POST /token HTTP/1.1 336 Host: server.example.com 337 Content-Type: application/x-www-form-urlencoded 339 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 340 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 342 An assertion used in this context is generally a short lived 343 representation of the authorization grant and authorization servers 344 SHOULD NOT issue access tokens with a lifetime that exceeds the 345 validity period of the assertion by a significant period. In 346 practice, that will usually mean that refresh tokens are not issued 347 in response to assertion grant requests and access tokens will be 348 issued with a reasonably short lifetime. Clients can refresh an 349 expired access token by requesting a new one using the same 350 assertion, if it is still valid, or with a new assertion. 352 An IETF URN for use as the "grant_type" value can be requested using 353 the template in [RFC6755]. A URN of the form 354 urn:ietf:params:oauth:grant-type:* is suggested. 356 4.1.1. Error Responses 358 If an assertion is not valid or has expired, the Authorization Server 359 MUST construct an error response as defined in OAuth 2.0 [RFC6749]. 360 The value of the "error" parameter MUST be the "invalid_grant" error 361 code. The authorization server MAY include additional information 362 regarding the reasons the assertion was considered invalid using the 363 "error_description" or "error_uri" parameters. 365 For example: 367 HTTP/1.1 400 Bad Request 368 Content-Type: application/json 369 Cache-Control: no-store 371 { 372 "error":"invalid_grant", 373 "error_description":"Audience validation failed" 374 } 376 4.2. Using Assertions for Client Authentication 378 The following section defines the use of assertions as client 379 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 380 When using assertions as client credentials, the client includes the 381 assertion and related information using the following HTTP request 382 parameters: 384 client_assertion_type 385 REQUIRED. The format of the assertion as defined by the 386 authorization server. The value MUST be an absolute URI. 388 client_assertion 389 REQUIRED. The assertion being used to authenticate the client. 390 Specific serialization of the assertion is defined by profile 391 documents. The serialization MUST be encoded for transport within 392 HTTP forms. It is RECOMMENDED that base64url be used. 394 client_id 395 OPTIONAL. The client identifier as described in Section 2.2 of 396 OAuth 2.0 [RFC6749]. The "client_id" is unnecessary for client 397 assertion authentication because the client is identified by the 398 subject of the assertion. If present, the value of the 399 "client_id" parameter MUST identify the same client as is 400 identified by the client assertion. 402 The following non-normative example demonstrates a client 403 authenticating using an assertion during an Access Token Request, as 404 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 405 breaks for display purposes only): 407 POST /token HTTP/1.1 408 Host: server.example.com 409 Content-Type: application/x-www-form-urlencoded 411 grant_type=authorization_code& 412 code=i1WsRn1uB1& 413 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 414 %3Aclient-assertion-type%3Asaml2-bearer& 415 client_assertion=PHNhbW...[omitted for brevity]...ZT 417 Token endpoints can differentiate between assertion based credentials 418 and other client credential types by looking for the presence of the 419 "client_assertion" and "client_assertion_type" parameters, which will 420 only be present when using assertions for client authentication. 422 An IETF URN for use as the "client_assertion_type" value may be 423 requested using the template in [RFC6755]. A URN of the form 424 urn:ietf:params:oauth:client-assertion-type:* is suggested. 426 4.2.1. Error Responses 428 If an assertion is invalid for any reason or if more than one client 429 authentication mechanism is used, the Authorization Server MUST 430 construct an error response as defined in OAuth 2.0 [RFC6749]. The 431 value of the "error" parameter MUST be the "invalid_client" error 432 code. The authorization server MAY include additional information 433 regarding the reasons the client assertion was considered invalid 434 using the "error_description" or "error_uri" parameters. 436 For example: 438 HTTP/1.1 400 Bad Request 439 Content-Type: application/json 440 Cache-Control: no-store 442 { 443 "error":"invalid_client" 444 "error_description":"assertion has expired" 445 } 447 5. Assertion Content and Processing 449 This section provides a general content and processing model for the 450 use of assertions in OAuth 2.0 [RFC6749]. 452 5.1. Assertion Metamodel 454 The following are entities and metadata involved in the issuance, 455 exchange, and processing of assertions in OAuth 2.0. These are 456 general terms, abstract from any particular assertion format. 457 Mappings of these terms into specific representations are provided by 458 profiles of this specification. 460 Issuer 461 A unique identifier for the entity that issued the assertion. 462 Generally this is the entity that holds the key material used to 463 sign or integrity protect the assertion. Examples of issuers are 464 OAuth clients (when assertions are self-issued) and third party 465 security token services. If the assertion is self-issued, the 466 Issuer value is the client identifier. If the assertion was 467 issued by a Security Token Service (STS), the Issuer should 468 identify the STS in a manner recognized by the Authorization 469 Server. In the absence of an application profile specifying 470 otherwise, compliant applications MUST compare Issuer values using 471 the Simple String Comparison method defined in Section 6.2.1 of 472 RFC 3986 [RFC3986]. 474 Subject 475 A unique identifier for the principal that is the subject of the 476 assertion. 478 * When using assertions for client authentication, the Subject 479 identifies the client to the authorization server using the 480 value of the "client_id" of the OAuth client. 482 * When using assertions as an authorization grant, the Subject 483 identifies an authorized accessor for which the access token is 484 being requested (typically the resource owner, or an authorized 485 delegate). 487 Audience 488 A value that identifies the party or parties intended to process 489 the assertion. The URL of the Token Endpoint, as defined in 490 Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate that 491 the authorization server as a valid intended audience of the 492 assertion. In the absence of an application profile specifying 493 otherwise, compliant applications MUST compare the audience values 494 using the Simple String Comparison method defined in Section 6.2.1 495 of RFC 3986 [RFC3986]. 497 Issued At 498 The time at which the assertion was issued. While the 499 serialization may differ by assertion format, it is REQUIRED that 500 the time be expressed in UTC with no time zone component. 502 Expires At 503 The time at which the assertion expires. While the serialization 504 may differ by assertion format, it is REQUIRED that the time be 505 expressed in UTC with no time zone component. 507 Assertion ID 508 A nonce or unique identifier for the assertion. The Assertion ID 509 may be used by implementations requiring message de-duplication 510 for one-time use assertions. Any entity that assigns an 511 identifier MUST ensure that there is negligible probability that 512 that entity or any other entity will accidentally assign the same 513 identifier to a different data object. 515 5.2. General Assertion Format and Processing Rules 517 The following are general format and processing rules for the use of 518 assertions in OAuth: 520 o The assertion MUST contain an Issuer. The Issuer MUST identify 521 the entity that issued the assertion as recognized by the 522 Authorization Server. If an assertion is self-issued, the Issuer 523 MUST be the value of the client's "client_id". 525 o The assertion MUST contain a Subject. The Subject typically 526 identifies an authorized accessor for which the access token is 527 being requested (i.e., the resource owner or an authorized 528 delegate), but in some cases, may be a pseudonymous identifier or 529 other value denoting an anonymous user. When the client is acting 530 on behalf of itself, the Subject MUST be the value of the client's 531 "client_id". 533 o The assertion MUST contain an Audience that identifies the 534 Authorization Server as the intended audience. Assertions that do 535 not identify the Authorization Server as an intended audience MUST 536 be rejected. 538 o The assertion MUST contain an Expires At entity that limits the 539 time window during which the assertion can be used. The 540 authorization server MUST reject assertions that have expired 541 (subject to allowable clock skew between systems). The 542 authorization server MAY reject assertions with an Expires At 543 attribute value that is unreasonably far in the future. 545 o The assertion MAY contain an Issued At entity containing the UTC 546 time at which the assertion was issued. 548 o The Authorization Server MUST reject assertions with an invalid 549 signature or keyed message digest. The algorithm used to validate 550 the signature or message authentication code and the mechanism for 551 designating the secret used to generate the signature or message 552 authentication code over the assertion are beyond the scope of 553 this specification. 555 6. Common Scenarios 557 The following provides additional guidance, beyond the format and 558 processing rules defined in Section 4 and Section 5, on assertion use 559 for a number of common use cases. 561 6.1. Client Authentication 563 A client uses an assertion to authenticate to the authorization 564 server's token endpoint by using the "client_assertion_type" and 565 "client_assertion" parameters as defined in Section 4.2. The Subject 566 of the assertion identifies the client. If the assertion is self- 567 issued by the client, the Issuer of the assertion also identifies the 568 client. 570 The example in Section 4.2 that shows a client authenticating using 571 an assertion during an Access Token Request. 573 6.2. Client Acting on Behalf of Itself 575 When a client is accessing resources on behalf of itself, it does so 576 in a manner analogous to the Client Credentials Grant defined in 577 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 578 combines both the authentication and authorization grant usage 579 patterns. In this case, the interactions with the authorization 580 server should be treated as using an assertion for Client 581 Authentication according to Section 4.2, while using the grant_type 582 parameter with the value "client_credentials" to indicate that the 583 client is requesting an access token using only its client 584 credentials. 586 The following non-normative example demonstrates an assertion being 587 used for a Client Credentials Access Token Request, as defined in 588 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 589 display purposes only): 591 POST /token HTTP/1.1 592 Host: server.example.com 593 Content-Type: application/x-www-form-urlencoded 595 grant_type=client_credentials& 596 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 597 %3Aclient-assertion-type%3Asaml2-bearer& 598 client_assertion=PHNhbW...[omitted for brevity]...ZT 600 6.3. Client Acting on Behalf of a User 602 When a client is accessing resources on behalf of a user, it does so 603 by using the "grant_type" and "assertion" parameters as defined in 604 Section 4.1. The Subject identifies an authorized accessor for which 605 the access token is being requested (typically the resource owner, or 606 an authorized delegate). 608 The example in Section 4.1 that shows a client making an Access Token 609 Request using an assertion as an Authorization Grant. 611 6.3.1. Client Acting on Behalf of an Anonymous User 613 When a client is accessing resources on behalf of an anonymous user, 614 a mutually agreed upon Subject identifier indicating anonymity is 615 used. The Subject value might be an opaque persistent or transient 616 pseudonymous identifier for the user or be an agreed upon static 617 value indicating an anonymous user (e.g., "anonymous"). The 618 authorization may be based upon additional criteria, such as 619 additional attributes or claims provided in the assertion. For 620 example, a client might present an assertion from a trusted issuer 621 asserting that the bearer is over 18 via an included claim. In this 622 case, no additional information about the user's identity is 623 included, yet all the data needed to issue an access token is 624 present. 626 More information about anonymity, pseudonymity, and privacy 627 considerations in general can be found in [RFC6973]. 629 7. Interoperability Considerations 631 This specification defines a framework for using assertions with 632 OAuth 2.0. However, as an abstract framework in which the data 633 formats used for representing many values are not defined, on its 634 own, this specification is not sufficient to produce interoperable 635 implementations. 637 Two other specifications that profile this framework for specific 638 assertion have been developed: one [I-D.ietf-oauth-saml2-bearer] uses 639 SAML 2.0-based assertions and the other [I-D.ietf-oauth-jwt-bearer] 640 uses JSON Web Tokens (JWTs). These two instantiations of this 641 framework specify additional details about the assertion encoding and 642 processing rules for using those kinds of assertions with OAuth 2.0. 644 However, even when profiled for specific assertion types, agreements 645 between system entities regarding identifiers, keys, and endpoints 646 are required in order to achieve interoperable deployments. Specific 647 items that require agreement are as follows: values for the issuer 648 and audience identifiers, supported assertion and client 649 authentication types, the location of the token endpoint, the key 650 used to apply and verify the digital signature or keyed message 651 digest over the assertion, one-time use restrictions on assertions, 652 maximum assertion lifetime allowed, and the specific subject and 653 attribute requirements of the assertion. The exchange of such 654 information is explicitly out of scope for this specification. 655 Deployments for particular trust frameworks, circles of trust, or 656 other uses cases will need to agree among the participants on the 657 kinds of values to be used for some abstract fields defined by this 658 specification. In some cases, additional profiles may be created 659 that constrain or prescribe these values or specify how they are to 660 be exchanged. The OAuth 2.0 Dynamic Client Registration Core 661 Protocol [I-D.ietf-oauth-dyn-reg] is one such profile that enables 662 OAuth Clients to register metadata about themselves at an 663 Authorization Server. 665 8. Security Considerations 667 This section discusses security considerations that apply when using 668 assertions with OAuth 2.0 as described in this document. As 669 discussed in Section 3, there are two different ways to obtain 670 assertions: either as self-issued or obtained from a third party 671 token service. While the actual interactions for obtaining an 672 assertion are outside the scope of this document, the details are 673 important from a security perspective. Section 3 discusses the high 674 level architectural aspects. Many of the security considerations 675 discussed in this section are applicable to both the OAuth exchange 676 as well as the client obtaining the assertion. 678 The remainder of this section focuses on the exchanges that concern 679 presenting an assertion for client authentication and for the 680 authorization grant. 682 8.1. Forged Assertion 684 Threat: 685 An adversary could forge or alter an assertion in order to obtain 686 an access token (in case of the authorization grant) or to 687 impersonate a client (in case of the client authentication 688 mechanism). 690 Countermeasures: 691 To avoid this kind of attack, the entities must assure that proper 692 mechanisms for protecting the integrity of the assertion are 693 employed. This includes the issuer digitally signing the 694 assertion or computing a keyed message digest over the assertion. 696 8.2. Stolen Assertion 698 Threat: 699 An adversary may be able obtain an assertion (e.g., by 700 eavesdropping) and then reuse it (replay it) at a later point in 701 time. 703 Countermeasures: 704 The primary mitigation for this threat is the use of secure 705 communication channels with server authentication for all network 706 exchanges. 708 An assertion may also contain several elements to prevent replay 709 attacks. There is, however, a clear tradeoff between reusing an 710 assertion for multiple exchanges and obtaining and creating new 711 fresh assertions. 713 Authorization Servers and Resource Servers may use a combination 714 of the Assertion ID and Issued At/Expires At attributes for replay 715 protection. Previously processed assertions may be rejected based 716 on the Assertion ID. The addition of the validity window relieves 717 the authorization server from maintaining an infinite state table 718 of processed Assertion IDs. 720 8.3. Unauthorized Disclosure of Personal Information 722 Threat: 723 The ability for other entities to obtain information about an 724 individual, such as authentication information, role in an 725 organization, or other authorization relevant information, raises 726 privacy concerns. 728 Countermeasures: 729 To address the threats, two cases need to be differentiated: 731 First, a third party that did not participate in any of the 732 exchange is prevented from eavesdropping on the content of the 733 assertion by employing confidentiality protection of the exchange 734 using TLS. This ensures that an eavesdropper on the wire is 735 unable to obtain information. However, this does not prevent 736 legitimate protocol entities from obtaining information that they 737 are not allowed to possess from assertions. Some assertion 738 formats allow for the assertion to be encrypted, preventing 739 unauthorized parties from inspecting the content. 741 Second, an Authorization Server may obtain an assertion that was 742 created by a third party token service and that token service may 743 have placed attributes into the assertion. To mitigate potential 744 privacy problems, prior consent for the release of such attribute 745 information from the resource owner should be obtained. OAuth 746 itself does not directly provide such capabilities, but this 747 consent approval may be obtained using other identity management 748 protocols, user consent interactions, or in an out-of-band 749 fashion. 751 For the cases where a third party token service creates assertions 752 to be used for client authentication, privacy concerns are 753 typically lower, since many of these clients are Web servers 754 rather than individual devices operated by humans. If the 755 assertions are used for client authentication of devices or 756 software that can be closely linked to end users, then privacy 757 protection safeguards need to be taken into consideration. 759 Further guidance on privacy friendly protocol design can be found 760 in [RFC6973]. 762 8.4. Privacy Considerations 764 An assertion may contain privacy-sensitive information and, to 765 prevent disclosure of such information to unintended parties, should 766 only be transmitted over encrypted channels, such as TLS. In cases 767 where it is desirable to prevent disclosure of certain information 768 the client, the assertion, or portions of it, should be be encrypted 769 to the authorization server. 771 Deployments should determine the minimum amount of information 772 necessary to complete the exchange and include only such information 773 in the assertion. In some cases, the subject identifier can be a 774 value representing an anonymous or pseudonymous user, as described in 775 Section 6.3.1. 777 9. IANA Considerations 779 This is a request to add three values, as listed in the sub-sections 780 below, to the "OAuth Parameters" registry established by RFC 6749 781 [RFC6749]. 783 9.1. assertion Parameter Registration 785 o Parameter name: assertion 787 o Parameter usage location: token request 789 o Change controller: IETF 791 o Specification document(s): [[this document]] 793 9.2. client_assertion Parameter Registration 795 o Parameter name: client_assertion 797 o Parameter usage location: token request 799 o Change controller: IETF 801 o Specification document(s): [[this document]] 803 9.3. client_assertion_type Parameter Registration 805 o Parameter name: client_assertion_type 807 o Parameter usage location: token request 809 o Change controller: IETF 811 o Specification document(s): [[this document]] 813 10. References 815 10.1. Normative References 817 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 818 Requirement Levels", BCP 14, RFC 2119, March 1997. 820 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 821 Resource Identifier (URI): Generic Syntax", STD 66, RFC 822 3986, January 2005. 824 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 825 6749, October 2012. 827 10.2. Informative References 829 [I-D.ietf-oauth-dyn-reg] 830 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 831 Hunt, "OAuth 2.0 Dynamic Client Registration Core 832 Protocol", draft-ietf-oauth-dyn-reg-16 (work in progress), 833 February 2014. 835 [I-D.ietf-oauth-jwt-bearer] 836 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 837 (JWT) Profile for OAuth 2.0 Client Authentication and 838 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 839 in progress), July 2014. 841 [I-D.ietf-oauth-saml2-bearer] 842 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 843 Profile for OAuth 2.0 Client Authentication and 844 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 845 in progress), July 2014. 847 [OASIS.WS-Trust] 848 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 849 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", Feb 850 2009. 852 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 853 for OAuth", RFC 6755, October 2012. 855 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 856 Morris, J., Hansen, M., and R. Smith, "Privacy 857 Considerations for Internet Protocols", RFC 6973, July 858 2013. 860 Appendix A. Acknowledgements 862 The authors wish to thank the following people that have influenced 863 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 864 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 865 specification, and the members of the OAuth working group. 867 Appendix B. Document History 869 [[ to be removed by the RFC editor before publication as an RFC ]] 871 draft-ietf-oauth-assertions-17 873 o Added Privacy Considerations section per AD review discussion 874 http://www.ietf.org/mail-archive/web/oauth/current/msg13148.html 875 and http://www.ietf.org/mail-archive/web/oauth/current/ 876 msg13144.html 878 draft-ietf-oauth-assertions-16 880 o Clarified some text around the treatment of subject based on the 881 rough rough consensus from the thread staring at 882 http://www.ietf.org/mail-archive/web/oauth/current/msg12630.html 884 draft-ietf-oauth-assertions-15 886 o Updated references. 888 o Improved formatting of hanging lists. 890 draft-ietf-oauth-assertions-14 892 o Update reference: draft-iab-privacy-considerations is now RFC 6973 894 o Update reference: draft-ietf-oauth-dyn-reg from -13 to -15 896 draft-ietf-oauth-assertions-13 898 o Clean up language around subject per the subject part of 899 http://www.ietf.org/mail-archive/web/oauth/current/msg12155.html 901 o Replace "Client Credentials flow" by "Client Credentials _Grant_" 902 as suggested in http://www.ietf.org/mail- 903 archive/web/oauth/current/msg12155.html 905 o For consistency with SAML and JWT per http://www.ietf.org/mail- 906 archive/web/oauth/current/msg12251.html and http://www.ietf.org/ 907 mail-archive/web/oauth/current/msg12253.html Stated that "In the 908 absence of an application profile specifying otherwise, compliant 909 applications MUST compare the audience values using the Simple 910 String Comparison method defined in Section 6.2.1 of RFC 3986." 912 o Added one-time use, maximum lifetime, and specific subject and 913 attribute requirements to Interoperability Considerations. 915 draft-ietf-oauth-assertions-12 917 o Stated that issuer and audience values SHOULD be compared using 918 the Simple String Comparison method defined in Section 6.2.1 of 919 RFC 3986 unless otherwise specified by the application. 921 draft-ietf-oauth-assertions-11 923 o Addressed comments from IESG evaluation 924 https://datatracker.ietf.org/doc/draft-ietf-oauth-assertions/ 925 ballot/. 927 o Reworded Interoperability Considerations to state what 928 identifiers, keys, endpoints, etc. need to be exchanged/agreed 929 upon. 931 o Added brief description of assertion to the into and included a 932 reference to Section 3 (Framework) where it's described more. 934 o Changed such that a self-issued assertion must (was should) have 935 the client id as the issuer. 937 o Changed "Specific Assertion Format and Processing Rules" to 938 "Common Scenarios" and reworded to be more suggestive of common 939 practices, rather than trying to be normative. Also removed lots 940 of repetitive text in that section. 942 o Refined language around audience, subject, client identifiers, 943 etc. to hopefully be clearer and less redundant. 945 o Changed title from "Assertion Framework for OAuth 2.0" to 946 "Assertion Framework for OAuth 2.0 Client Authentication and 947 Authorization Grants" to be more explicit about the scope of the 948 document per http://www.ietf.org/mail-archive/web/oauth/current/ 949 msg11063.html. 951 o Noted that authentication of the client per Section 3.2.1 of OAuth 952 is optional for an access token request with an assertion as an 953 authorization grant and removed client_id from the associated 954 example. 956 draft-ietf-oauth-assertions-10 958 o Changed term "Principal" to "Subject". 960 o Added Interoperability Considerations section. 962 o Applied Shawn Emery's comments from the security directorate 963 review, including correcting urn:ietf:params:oauth:grant_type:* to 964 urn:ietf:params:oauth:grant-type:*. 966 draft-ietf-oauth-assertions-09 968 o Allow audience values to not be URIs. 970 o Added informative references to draft-ietf-oauth-saml2-bearer and 971 draft-ietf-oauth-jwt-bearer. 973 o Clarified that the statements about possible issuers are non- 974 normative by using the language "Examples of issuers". 976 draft-ietf-oauth-assertions-08 978 o Update reference to RFC 6755 from draft-ietf-oauth-urn-sub-ns 980 o Tidy up IANA consideration section 982 draft-ietf-oauth-assertions-07 984 o Reference RFC 6749. 986 o Remove extraneous word per http://www.ietf.org/mail- 987 archive/web/oauth/current/msg10029.html 989 draft-ietf-oauth-assertions-06 991 o Add more text to intro explaining that an assertion grant type can 992 be used with or without client authentication/identification and 993 that client assertion authentication is nothing more than an 994 alternative way for a client to authenticate to the token endpoint 996 o Non-normative editorial cleanups 998 draft-ietf-oauth-assertions-04 1000 o Updated document to incorporate the review comments from the 1001 shepherd - thread and alternative draft at http://www.ietf.org/ 1002 mail-archive/web/oauth/current/msg09437.html 1004 o Added reference to draft-ietf-oauth-urn-sub-ns and include 1005 suggestions on urn:ietf:params:oauth:[grant-type|client-assertion- 1006 type]:* URNs 1008 draft-ietf-oauth-assertions-03 1010 o updated reference to draft-ietf-oauth-v2 from -25 to -26 1012 draft-ietf-oauth-assertions-02 1014 o Added text about limited lifetime ATs and RTs per 1015 http://www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 1017 o Changed the line breaks in some examples to avoid awkward 1018 rendering to text format. Also removed encoded '=' padding from a 1019 few examples because both known derivative specs, SAML and JWT, 1020 omit the padding char in serialization/encoding. 1022 o Remove section 7 on error responses and move that (somewhat 1023 modified) content into subsections of section 4 broken up by 1024 authn/authz per http://www.ietf.org/mail- 1025 archive/web/oauth/current/msg08735.html. 1027 o Rework the text about "MUST validate ... in order to establish a 1028 mapping between ..." per http://www.ietf.org/mail- 1029 archive/web/oauth/current/msg08872.html and http://www.ietf.org/ 1030 mail-archive/web/oauth/current/msg08749.html. 1032 o Change "The Principal MUST identify an authorized accessor. If 1033 the assertion is self-issued, the Principal SHOULD be the 1034 client_id" in 6.1 per http://www.ietf.org/mail- 1035 archive/web/oauth/current/msg08873.html. 1037 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 1038 oauth-v2 (rather than self) http://www.ietf.org/mail- 1039 archive/web/oauth/current/msg08874.html. 1041 o Move the "Section 3 of" out of the xref to hopefully fix the link 1042 in 4.1 and remove the client_id bullet from 4.2 per 1043 http://www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 1045 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 1046 some then redundant text per http://www.ietf.org/mail- 1047 archive/web/oauth/current/msg08890.html. 1049 o Change "The following format and processing rules SHOULD be 1050 applied" to "The following format and processing rules apply" in 1051 sections 6.x to remove conflicting normative qualification of 1052 other normative statements per http://www.ietf.org/mail- 1053 archive/web/oauth/current/msg08892.html. 1055 o Add text the client_id must id the client to 4.1 and remove 1056 similar text from other places per http://www.ietf.org/mail- 1057 archive/web/oauth/current/msg08893.html. 1059 o Remove the MUST from the text prior to the HTTP parameter 1060 definitions per http://www.ietf.org/mail- 1061 archive/web/oauth/current/msg08920.html. 1063 o Updated examples to use grant_type and client_assertion_type 1064 values from the OAuth SAML Assertion Profiles spec. 1066 Authors' Addresses 1068 Brian Campbell 1069 Ping Identity 1071 Email: brian.d.campbell@gmail.com 1073 Chuck Mortimore 1074 Salesforce.com 1076 Email: cmortimore@salesforce.com 1078 Michael B. Jones 1079 Microsoft 1081 Email: mbj@microsoft.com 1082 Yaron Y. Goland 1083 Microsoft 1085 Email: yarong@microsoft.com