idnits 2.17.1 draft-ietf-oauth-assertions-18.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 (October 21, 2014) is 3446 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-20 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: April 24, 2015 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 October 21, 2014 11 Assertion Framework for OAuth 2.0 Client Authentication and 12 Authorization Grants 13 draft-ietf-oauth-assertions-18 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 April 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 . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . 16 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 . . . . . . 17 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 integrity protected using a digital 182 signature or Message Authentication Code applied by the issuer, which 183 authenticates the issuer and ensures integrity of the assertion 184 content. In many cases, the assertion is issued by a third party and 185 it must be protected against tampering by the client that presents 186 it. An assertion MAY additionally be encrypted, preventing 187 unauthorized parties (such as the client) from inspecting the 188 content. 190 Although this document does not define the processes by which the 191 client obtains the assertion (prior to sending it to the 192 authorization server), there are two common patterns described below. 194 In the first pattern, depicted in Figure 1, the client obtains an 195 assertion from a third party entity capable of issuing, renewing, 196 transforming, and validating security tokens. Typically such an 197 entity is known as a "Security Token Service" (STS) or just "Token 198 Service" and a trust relationship (usually manifested in the exchange 199 of some kind of key material) exists between the token service and 200 the relying party. The token service is the assertion issuer; its 201 role is to fulfill requests from clients, which present various 202 credentials, and mint assertions as requested, fill them with 203 appropriate information, and integrity protect them with a signature 204 or message authentication code. WS-Trust [OASIS.WS-Trust] is one 205 available standard for requesting security tokens (assertions). 207 Relying 208 Party Client Token Service 209 | | | 210 | | 1) Request Assertion | 211 | |------------------------>| 212 | | | 213 | | 2) Assertion | 214 | |<------------------------| 215 | 3) Assertion | | 216 |<-------------------------| | 217 | | | 218 | 4) OK or Failure | | 219 |------------------------->| | 220 | | | 221 | | | 223 Figure 1: Third Party Created Assertion 225 In the second pattern, depicted in Figure 2, the client creates 226 assertions locally. To apply the signatures or message 227 authentication codes to assertions, it has to obtain key material: 228 either symmetric keys or asymmetric key pairs. The mechanisms for 229 obtaining this key material are beyond the scope of this 230 specification. 232 Although assertions are usually used to convey identity and security 233 information, self-issued assertions can also serve a different 234 purpose. They can be used to demonstrate knowledge of some secret, 235 such as a client secret, without actually communicating the secret 236 directly in the transaction. In that case, additional information 237 included in the assertion by the client itself will be of limited 238 value to the relying party and, for this reason, only a bare minimum 239 of information is typically included in such an assertion, such as 240 information about issuing and usage conditions. 242 Relying 243 Party Client 244 | | 245 | | 1) Create 246 | | Assertion 247 | |--------------+ 248 | | | 249 | | 2) Assertion | 250 | |<-------------+ 251 | 3) Assertion | 252 |<-------------------------| 253 | | 254 | 4) OK or Failure | 255 |------------------------->| 256 | | 257 | | 259 Figure 2: Self-Issued Assertion 261 Deployments need to determine the appropriate variant to use based on 262 the required level of security, the trust relationship between the 263 entities, and other factors. 265 From the perspective of what must be done by the entity presenting 266 the assertion, there are two general types of assertions: 268 1. Bearer Assertions: Any entity in possession of a bearer assertion 269 (the bearer) can use it to get access to the associated resources 270 (without demonstrating possession of a cryptographic key). To 271 prevent misuse, bearer assertions need to be protected from 272 disclosure in storage and in transport. Secure communication 273 channels are required between all entities to avoid leaking the 274 assertion to unauthorized parties. 276 2. Holder-of-Key Assertions: To access the associated resources, the 277 entity presenting the assertion must demonstrate possession of 278 additional cryptographic material. The token service thereby 279 binds a key identifier to the assertion and the client has to 280 demonstrate to the relying party that it knows the key 281 corresponding to that identifier when presenting the assertion. 283 The protocol parameters and processing rules defined in this document 284 are intended to support a client presenting a bearer assertion to an 285 authorization server. They are not directly suitable for use with 286 holder-of-key assertions. While they could be used as a baseline for 287 a holder-of-key assertion system, there would be a need for 288 additional mechanisms (to support proof-of-possession of the secret 289 key), and possibly changes to the security model (e.g., to relax the 290 requirement for an Audience). 292 4. Transporting Assertions 294 This section defines HTTP parameters for transporting assertions 295 during interactions with a token endpoint of an OAuth authorization 296 server. Because requests to the token endpoint result in the 297 transmission of clear-text credentials (in both the HTTP request and 298 response), all requests to the token endpoint MUST use TLS, as 299 mandated in Section 3.2 of OAuth 2.0 [RFC6749]. 301 4.1. Using Assertions as Authorization Grants 303 This section defines the use of assertions as authorization grants, 304 based on the definition provided in Section 4.5 of OAuth 2.0 305 [RFC6749]. When using assertions as authorization grants, the client 306 includes the assertion and related information using the following 307 HTTP request parameters: 309 grant_type 310 REQUIRED. The format of the assertion as defined by the 311 authorization server. The value will be an absolute URI. 313 assertion 314 REQUIRED. The assertion being used as an authorization grant. 315 Specific serialization of the assertion is defined by profile 316 documents. 318 scope 319 OPTIONAL. The requested scope as described in Section 3.3 of 320 OAuth 2.0 [RFC6749]. When exchanging assertions for access 321 tokens, the authorization for the token has been previously 322 granted through some out-of-band mechanism. As such, the 323 requested scope MUST be equal or lesser than the scope originally 324 granted to the authorized accessor. The Authorization Server MUST 325 limit the scope of the issued access token to be equal or lesser 326 than the scope originally granted to the authorized accessor. 328 Authentication of the client is optional, as described in 329 Section 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the 330 "client_id" is only needed when a form of client authentication that 331 relies on the parameter is used. 333 The following example demonstrates an assertion being used as an 334 authorization grant (with extra line breaks for display purposes 335 only): 337 POST /token HTTP/1.1 338 Host: server.example.com 339 Content-Type: application/x-www-form-urlencoded 341 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 342 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 344 An assertion used in this context is generally a short lived 345 representation of the authorization grant and authorization servers 346 SHOULD NOT issue access tokens with a lifetime that exceeds the 347 validity period of the assertion by a significant period. In 348 practice, that will usually mean that refresh tokens are not issued 349 in response to assertion grant requests and access tokens will be 350 issued with a reasonably short lifetime. Clients can refresh an 351 expired access token by requesting a new one using the same 352 assertion, if it is still valid, or with a new assertion. 354 An IETF URN for use as the "grant_type" value can be requested using 355 the template in [RFC6755]. A URN of the form 356 urn:ietf:params:oauth:grant-type:* is suggested. 358 4.1.1. Error Responses 360 If an assertion is not valid or has expired, the Authorization Server 361 constructs an error response as defined in OAuth 2.0 [RFC6749]. The 362 value of the "error" parameter MUST be the "invalid_grant" error 363 code. The authorization server MAY include additional information 364 regarding the reasons the assertion was considered invalid using the 365 "error_description" or "error_uri" parameters. 367 For example: 369 HTTP/1.1 400 Bad Request 370 Content-Type: application/json 371 Cache-Control: no-store 373 { 374 "error":"invalid_grant", 375 "error_description":"Audience validation failed" 376 } 378 4.2. Using Assertions for Client Authentication 380 The following section defines the use of assertions as client 381 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 382 When using assertions as client credentials, the client includes the 383 assertion and related information using the following HTTP request 384 parameters: 386 client_assertion_type 387 REQUIRED. The format of the assertion as defined by the 388 authorization server. The value will be an absolute URI. 390 client_assertion 391 REQUIRED. The assertion being used to authenticate the client. 392 Specific serialization of the assertion is defined by profile 393 documents. 395 client_id 396 OPTIONAL. The client identifier as described in Section 2.2 of 397 OAuth 2.0 [RFC6749]. The "client_id" is unnecessary for client 398 assertion authentication because the client is identified by the 399 subject of the assertion. If present, the value of the 400 "client_id" parameter MUST identify the same client as is 401 identified by the client assertion. 403 The following example demonstrates a client authenticating using an 404 assertion during an Access Token Request, as defined in Section 4.1.3 405 of OAuth 2.0 [RFC6749] (with extra line breaks for display purposes 406 only): 408 POST /token HTTP/1.1 409 Host: server.example.com 410 Content-Type: application/x-www-form-urlencoded 412 grant_type=authorization_code& 413 code=i1WsRn1uB1& 414 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 415 %3Aclient-assertion-type%3Asaml2-bearer& 416 client_assertion=PHNhbW...[omitted for brevity]...ZT 418 Token endpoints can differentiate between assertion based credentials 419 and other client credential types by looking for the presence of the 420 "client_assertion" and "client_assertion_type" parameters, which will 421 only be present when using assertions for client authentication. 423 An IETF URN for use as the "client_assertion_type" value may be 424 requested using the template in [RFC6755]. A URN of the form 425 urn:ietf:params:oauth:client-assertion-type:* is suggested. 427 4.2.1. Error Responses 429 If an assertion is invalid for any reason or if more than one client 430 authentication mechanism is used, the Authorization Server constructs 431 an error response as defined in OAuth 2.0 [RFC6749]. The value of 432 the "error" parameter MUST be the "invalid_client" error code. The 433 authorization server MAY include additional information regarding the 434 reasons the client assertion was considered invalid using the 435 "error_description" or "error_uri" parameters. 437 For example: 439 HTTP/1.1 400 Bad Request 440 Content-Type: application/json 441 Cache-Control: no-store 443 { 444 "error":"invalid_client" 445 "error_description":"assertion has expired" 446 } 448 5. Assertion Content and Processing 450 This section provides a general content and processing model for the 451 use of assertions in OAuth 2.0 [RFC6749]. 453 5.1. Assertion Metamodel 455 The following are entities and metadata involved in the issuance, 456 exchange, and processing of assertions in OAuth 2.0. These are 457 general terms, abstract from any particular assertion format. 458 Mappings of these terms into specific representations are provided by 459 profiles of this specification. 461 Issuer 462 A unique identifier for the entity that issued the assertion. 463 Generally this is the entity that holds the key material used to 464 sign or integrity protect the assertion. Examples of issuers are 465 OAuth clients (when assertions are self-issued) and third party 466 security token services. If the assertion is self-issued, the 467 Issuer value is the client identifier. If the assertion was 468 issued by a Security Token Service (STS), the Issuer should 469 identify the STS in a manner recognized by the Authorization 470 Server. In the absence of an application profile specifying 471 otherwise, compliant applications MUST compare Issuer values using 472 the Simple String Comparison method defined in Section 6.2.1 of 473 RFC 3986 [RFC3986]. 475 Subject 476 A unique identifier for the principal that is the subject of the 477 assertion. 479 * When using assertions for client authentication, the Subject 480 identifies the client to the authorization server using the 481 value of the "client_id" of the OAuth client. 483 * When using assertions as an authorization grant, the Subject 484 identifies an authorized accessor for which the access token is 485 being requested (typically the resource owner, or an authorized 486 delegate). 488 Audience 489 A value that identifies the party or parties intended to process 490 the assertion. The URL of the Token Endpoint, as defined in 491 Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate that 492 the authorization server as a valid intended audience of the 493 assertion. In the absence of an application profile specifying 494 otherwise, compliant applications MUST compare the audience values 495 using the Simple String Comparison method defined in Section 6.2.1 496 of RFC 3986 [RFC3986]. 498 Issued At 499 The time at which the assertion was issued. While the 500 serialization may differ by assertion format, it is REQUIRED that 501 the time be expressed in UTC with no time zone component. 503 Expires At 504 The time at which the assertion expires. While the serialization 505 may differ by assertion format, it is REQUIRED that the time be 506 expressed in UTC with no time zone component. 508 Assertion ID 509 A nonce or unique identifier for the assertion. The Assertion ID 510 may be used by implementations requiring message de-duplication 511 for one-time use assertions. Any entity that assigns an 512 identifier MUST ensure that there is negligible probability that 513 that entity or any other entity will accidentally assign the same 514 identifier to a different data object. 516 5.2. General Assertion Format and Processing Rules 518 The following are general format and processing rules for the use of 519 assertions in OAuth: 521 o The assertion MUST contain an Issuer. The Issuer identifies the 522 entity that issued the assertion as recognized by the 523 Authorization Server. If an assertion is self-issued, the Issuer 524 MUST be the value of the client's "client_id". 526 o The assertion MUST contain a Subject. The Subject typically 527 identifies an authorized accessor for which the access token is 528 being requested (i.e., the resource owner or an authorized 529 delegate), but in some cases, may be a pseudonymous identifier or 530 other value denoting an anonymous user. When the client is acting 531 on behalf of itself, the Subject MUST be the value of the client's 532 "client_id". 534 o The assertion MUST contain an Audience that identifies the 535 Authorization Server as the intended audience. The Authorization 536 Server MUST reject any assertion that does not contain the its own 537 identity as the intended audience. 539 o The assertion MUST contain an Expires At entity that limits the 540 time window during which the assertion can be used. The 541 authorization server MUST reject assertions that have expired 542 (subject to allowable clock skew between systems). Note that the 543 authorization server may reject assertions with an Expires At 544 attribute value that is unreasonably far in the future. 546 o The assertion MAY contain an Issued At entity containing the UTC 547 time at which the assertion was issued. 549 o The Authorization Server MUST reject assertions with an invalid 550 signature or Message Authentication Code. The algorithm used to 551 validate the signature or message authentication code and the 552 mechanism for designating the secret used to generate the 553 signature or message authentication code over the assertion are 554 beyond the scope of this specification. 556 6. Common Scenarios 558 The following provides additional guidance, beyond the format and 559 processing rules defined in Section 4 and Section 5, on assertion use 560 for a number of common use cases. 562 6.1. Client Authentication 564 A client uses an assertion to authenticate to the authorization 565 server's token endpoint by using the "client_assertion_type" and 566 "client_assertion" parameters as defined in Section 4.2. The Subject 567 of the assertion identifies the client. If the assertion is self- 568 issued by the client, the Issuer of the assertion also identifies the 569 client. 571 The example in Section 4.2 shows a client authenticating using an 572 assertion during an Access Token Request. 574 6.2. Client Acting on Behalf of Itself 576 When a client is accessing resources on behalf of itself, it does so 577 in a manner analogous to the Client Credentials Grant defined in 578 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 579 combines both the authentication and authorization grant usage 580 patterns. In this case, the interactions with the authorization 581 server should be treated as using an assertion for Client 582 Authentication according to Section 4.2, while using the grant_type 583 parameter with the value "client_credentials" to indicate that the 584 client is requesting an access token using only its client 585 credentials. 587 The following example demonstrates an assertion being used for a 588 Client Credentials Access Token Request, as defined in Section 4.4.2 589 of OAuth 2.0 [RFC6749] (with extra line breaks for display purposes 590 only): 592 POST /token HTTP/1.1 593 Host: server.example.com 594 Content-Type: application/x-www-form-urlencoded 596 grant_type=client_credentials& 597 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 598 %3Aclient-assertion-type%3Asaml2-bearer& 599 client_assertion=PHNhbW...[omitted for brevity]...ZT 601 6.3. Client Acting on Behalf of a User 603 When a client is accessing resources on behalf of a user, it does so 604 by using the "grant_type" and "assertion" parameters as defined in 605 Section 4.1. The Subject identifies an authorized accessor for which 606 the access token is being requested (typically the resource owner, or 607 an authorized delegate). 609 The example in Section 4.1 shows a client making an Access Token 610 Request using an assertion as an Authorization Grant. 612 6.3.1. Client Acting on Behalf of an Anonymous User 614 When a client is accessing resources on behalf of an anonymous user, 615 a mutually agreed upon Subject identifier indicating anonymity is 616 used. The Subject value might be an opaque persistent or transient 617 pseudonymous identifier for the user or be an agreed upon static 618 value indicating an anonymous user (e.g., "anonymous"). The 619 authorization may be based upon additional criteria, such as 620 additional attributes or claims provided in the assertion. For 621 example, a client might present an assertion from a trusted issuer 622 asserting that the bearer is over 18 via an included claim. In this 623 case, no additional information about the user's identity is 624 included, yet all the data needed to issue an access token is 625 present. 627 More information about anonymity, pseudonymity, and privacy 628 considerations in general can be found in [RFC6973]. 630 7. Interoperability Considerations 632 This specification defines a framework for using assertions with 633 OAuth 2.0. However, as an abstract framework in which the data 634 formats used for representing many values are not defined, on its 635 own, this specification is not sufficient to produce interoperable 636 implementations. 638 Two other specifications that profile this framework for specific 639 assertion have been developed: one [I-D.ietf-oauth-saml2-bearer] uses 640 SAML 2.0-based assertions and the other [I-D.ietf-oauth-jwt-bearer] 641 uses JSON Web Tokens (JWTs). These two instantiations of this 642 framework specify additional details about the assertion encoding and 643 processing rules for using those kinds of assertions with OAuth 2.0. 645 However, even when profiled for specific assertion types, agreements 646 between system entities regarding identifiers, keys, and endpoints 647 are required in order to achieve interoperable deployments. Specific 648 items that require agreement are as follows: values for the issuer 649 and audience identifiers, supported assertion and client 650 authentication types, the location of the token endpoint, the key 651 used to apply and verify the digital signature or Message 652 Authentication Code over the assertion, one-time use restrictions on 653 assertions, maximum assertion lifetime allowed, and the specific 654 subject and attribute requirements of the assertion. The exchange of 655 such information is explicitly out of scope for this specification. 656 Deployments for particular trust frameworks, circles of trust, or 657 other uses cases will need to agree among the participants on the 658 kinds of values to be used for some abstract fields defined by this 659 specification. In some cases, additional profiles may be created 660 that constrain or prescribe these values or specify how they are to 661 be exchanged. The OAuth 2.0 Dynamic Client Registration Core 662 Protocol [I-D.ietf-oauth-dyn-reg] is one such profile that enables 663 OAuth Clients to register metadata about themselves at an 664 Authorization Server. 666 8. Security Considerations 668 This section discusses security considerations that apply when using 669 assertions with OAuth 2.0 as described in this document. As 670 discussed in Section 3, there are two different ways to obtain 671 assertions: either as self-issued or obtained from a third party 672 token service. While the actual interactions for obtaining an 673 assertion are outside the scope of this document, the details are 674 important from a security perspective. Section 3 discusses the high 675 level architectural aspects. Many of the security considerations 676 discussed in this section are applicable to both the OAuth exchange 677 as well as the client obtaining the assertion. 679 The remainder of this section focuses on the exchanges that concern 680 presenting an assertion for client authentication and for the 681 authorization grant. 683 8.1. Forged Assertion 685 Threat: 686 An adversary could forge or alter an assertion in order to obtain 687 an access token (in case of the authorization grant) or to 688 impersonate a client (in case of the client authentication 689 mechanism). 691 Countermeasures: 692 To avoid this kind of attack, the entities must assure that proper 693 mechanisms for protecting the integrity of the assertion are 694 employed. This includes the issuer digitally signing the 695 assertion or computing a keyed message digest over the assertion. 697 8.2. Stolen Assertion 699 Threat: 700 An adversary may be able obtain an assertion (e.g., by 701 eavesdropping) and then reuse it (replay it) at a later point in 702 time. 704 Countermeasures: 705 The primary mitigation for this threat is the use of secure 706 communication channels with server authentication for all network 707 exchanges. 709 An assertion may also contain several elements to prevent replay 710 attacks. There is, however, a clear tradeoff between reusing an 711 assertion for multiple exchanges and obtaining and creating new 712 fresh assertions. 714 Authorization Servers and Resource Servers may use a combination 715 of the Assertion ID and Issued At/Expires At attributes for replay 716 protection. Previously processed assertions may be rejected based 717 on the Assertion ID. The addition of the validity window relieves 718 the authorization server from maintaining an infinite state table 719 of processed Assertion IDs. 721 8.3. Unauthorized Disclosure of Personal Information 723 Threat: 724 The ability for other entities to obtain information about an 725 individual, such as authentication information, role in an 726 organization, or other authorization relevant information, raises 727 privacy concerns. 729 Countermeasures: 730 To address the threats, two cases need to be differentiated: 732 First, a third party that did not participate in any of the 733 exchange is prevented from eavesdropping on the content of the 734 assertion by employing confidentiality protection of the exchange 735 using TLS. This ensures that an eavesdropper on the wire is 736 unable to obtain information. However, this does not prevent 737 legitimate protocol entities from obtaining information that they 738 are not allowed to possess from assertions. Some assertion 739 formats allow for the assertion to be encrypted, preventing 740 unauthorized parties from inspecting the content. 742 Second, an Authorization Server may obtain an assertion that was 743 created by a third party token service and that token service may 744 have placed attributes into the assertion. To mitigate potential 745 privacy problems, prior consent for the release of such attribute 746 information from the resource owner should be obtained. OAuth 747 itself does not directly provide such capabilities, but this 748 consent approval may be obtained using other identity management 749 protocols, user consent interactions, or in an out-of-band 750 fashion. 752 For the cases where a third party token service creates assertions 753 to be used for client authentication, privacy concerns are 754 typically lower, since many of these clients are Web servers 755 rather than individual devices operated by humans. If the 756 assertions are used for client authentication of devices or 757 software that can be closely linked to end users, then privacy 758 protection safeguards need to be taken into consideration. 760 Further guidance on privacy friendly protocol design can be found 761 in [RFC6973]. 763 8.4. Privacy Considerations 765 An assertion may contain privacy-sensitive information and, to 766 prevent disclosure of such information to unintended parties, should 767 only be transmitted over encrypted channels, such as TLS. In cases 768 where it is desirable to prevent disclosure of certain information 769 the client, the assertion, or portions of it, should be be encrypted 770 to the authorization server. 772 Deployments should determine the minimum amount of information 773 necessary to complete the exchange and include only such information 774 in the assertion. In some cases, the subject identifier can be a 775 value representing an anonymous or pseudonymous user, as described in 776 Section 6.3.1. 778 9. IANA Considerations 780 This is a request to add three values, as listed in the sub-sections 781 below, to the "OAuth Parameters" registry established by RFC 6749 782 [RFC6749]. 784 9.1. assertion Parameter Registration 786 o Parameter name: assertion 788 o Parameter usage location: token request 790 o Change controller: IESG 792 o Specification document(s): [[this document]] 794 9.2. client_assertion Parameter Registration 796 o Parameter name: client_assertion 798 o Parameter usage location: token request 800 o Change controller: IESG 802 o Specification document(s): [[this document]] 804 9.3. client_assertion_type Parameter Registration 806 o Parameter name: client_assertion_type 808 o Parameter usage location: token request 810 o Change controller: IESG 812 o Specification document(s): [[this document]] 814 10. References 816 10.1. Normative References 818 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 819 Requirement Levels", BCP 14, RFC 2119, March 1997. 821 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 822 Resource Identifier (URI): Generic Syntax", STD 66, RFC 823 3986, January 2005. 825 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 826 6749, October 2012. 828 10.2. Informative References 830 [I-D.ietf-oauth-dyn-reg] 831 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 832 Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 833 draft-ietf-oauth-dyn-reg-20 (work in progress), August 834 2014. 836 [I-D.ietf-oauth-jwt-bearer] 837 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 838 (JWT) Profile for OAuth 2.0 Client Authentication and 839 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 840 in progress), October 2014. 842 [I-D.ietf-oauth-saml2-bearer] 843 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 844 Profile for OAuth 2.0 Client Authentication and 845 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 846 in progress), October 2014. 848 [OASIS.WS-Trust] 849 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 850 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", Feb 851 2009. 853 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 854 for OAuth", RFC 6755, October 2012. 856 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 857 Morris, J., Hansen, M., and R. Smith, "Privacy 858 Considerations for Internet Protocols", RFC 6973, July 859 2013. 861 Appendix A. Acknowledgements 863 The authors wish to thank the following people that have influenced 864 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 865 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 866 specification, and the members of the OAuth working group. 868 Appendix B. Document History 870 [[ to be removed by the RFC editor before publication as an RFC ]] 872 draft-ietf-oauth-assertions-18 874 o Changes/suggestions from IESG reviews. 876 draft-ietf-oauth-assertions-17 878 o Added Privacy Considerations section per AD review discussion 879 http://www.ietf.org/mail-archive/web/oauth/current/msg13148.html 880 and http://www.ietf.org/mail-archive/web/oauth/current/ 881 msg13144.html 883 draft-ietf-oauth-assertions-16 885 o Clarified some text around the treatment of subject based on the 886 rough rough consensus from the thread staring at 887 http://www.ietf.org/mail-archive/web/oauth/current/msg12630.html 889 draft-ietf-oauth-assertions-15 891 o Updated references. 893 o Improved formatting of hanging lists. 895 draft-ietf-oauth-assertions-14 897 o Update reference: draft-iab-privacy-considerations is now RFC 6973 899 o Update reference: draft-ietf-oauth-dyn-reg from -13 to -15 901 draft-ietf-oauth-assertions-13 903 o Clean up language around subject per the subject part of 904 http://www.ietf.org/mail-archive/web/oauth/current/msg12155.html 906 o Replace "Client Credentials flow" by "Client Credentials _Grant_" 907 as suggested in http://www.ietf.org/mail- 908 archive/web/oauth/current/msg12155.html 910 o For consistency with SAML and JWT per http://www.ietf.org/mail- 911 archive/web/oauth/current/msg12251.html and http://www.ietf.org/ 912 mail-archive/web/oauth/current/msg12253.html Stated that "In the 913 absence of an application profile specifying otherwise, compliant 914 applications MUST compare the audience values using the Simple 915 String Comparison method defined in Section 6.2.1 of RFC 3986." 917 o Added one-time use, maximum lifetime, and specific subject and 918 attribute requirements to Interoperability Considerations. 920 draft-ietf-oauth-assertions-12 922 o Stated that issuer and audience values SHOULD be compared using 923 the Simple String Comparison method defined in Section 6.2.1 of 924 RFC 3986 unless otherwise specified by the application. 926 draft-ietf-oauth-assertions-11 928 o Addressed comments from IESG evaluation 929 https://datatracker.ietf.org/doc/draft-ietf-oauth-assertions/ 930 ballot/. 932 o Reworded Interoperability Considerations to state what 933 identifiers, keys, endpoints, etc. need to be exchanged/agreed 934 upon. 936 o Added brief description of assertion to the into and included a 937 reference to Section 3 (Framework) where it's described more. 939 o Changed such that a self-issued assertion must (was should) have 940 the client id as the issuer. 942 o Changed "Specific Assertion Format and Processing Rules" to 943 "Common Scenarios" and reworded to be more suggestive of common 944 practices, rather than trying to be normative. Also removed lots 945 of repetitive text in that section. 947 o Refined language around audience, subject, client identifiers, 948 etc. to hopefully be clearer and less redundant. 950 o Changed title from "Assertion Framework for OAuth 2.0" to 951 "Assertion Framework for OAuth 2.0 Client Authentication and 952 Authorization Grants" to be more explicit about the scope of the 953 document per http://www.ietf.org/mail-archive/web/oauth/current/ 954 msg11063.html. 956 o Noted that authentication of the client per Section 3.2.1 of OAuth 957 is optional for an access token request with an assertion as an 958 authorization grant and removed client_id from the associated 959 example. 961 draft-ietf-oauth-assertions-10 963 o Changed term "Principal" to "Subject". 965 o Added Interoperability Considerations section. 967 o Applied Shawn Emery's comments from the security directorate 968 review, including correcting urn:ietf:params:oauth:grant_type:* to 969 urn:ietf:params:oauth:grant-type:*. 971 draft-ietf-oauth-assertions-09 973 o Allow audience values to not be URIs. 975 o Added informative references to draft-ietf-oauth-saml2-bearer and 976 draft-ietf-oauth-jwt-bearer. 978 o Clarified that the statements about possible issuers are non- 979 normative by using the language "Examples of issuers". 981 draft-ietf-oauth-assertions-08 983 o Update reference to RFC 6755 from draft-ietf-oauth-urn-sub-ns 985 o Tidy up IANA consideration section 987 draft-ietf-oauth-assertions-07 989 o Reference RFC 6749. 991 o Remove extraneous word per http://www.ietf.org/mail- 992 archive/web/oauth/current/msg10029.html 994 draft-ietf-oauth-assertions-06 996 o Add more text to intro explaining that an assertion grant type can 997 be used with or without client authentication/identification and 998 that client assertion authentication is nothing more than an 999 alternative way for a client to authenticate to the token endpoint 1001 draft-ietf-oauth-assertions-05 1003 o Non-normative editorial cleanups 1005 draft-ietf-oauth-assertions-04 1006 o Updated document to incorporate the review comments from the 1007 shepherd - thread and alternative draft at http://www.ietf.org/ 1008 mail-archive/web/oauth/current/msg09437.html 1010 o Added reference to draft-ietf-oauth-urn-sub-ns and include 1011 suggestions on urn:ietf:params:oauth:[grant-type|client-assertion- 1012 type]:* URNs 1014 draft-ietf-oauth-assertions-03 1016 o updated reference to draft-ietf-oauth-v2 from -25 to -26 1018 draft-ietf-oauth-assertions-02 1020 o Added text about limited lifetime ATs and RTs per 1021 http://www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 1023 o Changed the line breaks in some examples to avoid awkward 1024 rendering to text format. Also removed encoded '=' padding from a 1025 few examples because both known derivative specs, SAML and JWT, 1026 omit the padding char in serialization/encoding. 1028 o Remove section 7 on error responses and move that (somewhat 1029 modified) content into subsections of section 4 broken up by 1030 authn/authz per http://www.ietf.org/mail- 1031 archive/web/oauth/current/msg08735.html. 1033 o Rework the text about "MUST validate ... in order to establish a 1034 mapping between ..." per http://www.ietf.org/mail- 1035 archive/web/oauth/current/msg08872.html and http://www.ietf.org/ 1036 mail-archive/web/oauth/current/msg08749.html. 1038 o Change "The Principal MUST identify an authorized accessor. If 1039 the assertion is self-issued, the Principal SHOULD be the 1040 client_id" in 6.1 per http://www.ietf.org/mail- 1041 archive/web/oauth/current/msg08873.html. 1043 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 1044 oauth-v2 (rather than self) http://www.ietf.org/mail- 1045 archive/web/oauth/current/msg08874.html. 1047 o Move the "Section 3 of" out of the xref to hopefully fix the link 1048 in 4.1 and remove the client_id bullet from 4.2 per 1049 http://www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 1051 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 1052 some then redundant text per http://www.ietf.org/mail- 1053 archive/web/oauth/current/msg08890.html. 1055 o Change "The following format and processing rules SHOULD be 1056 applied" to "The following format and processing rules apply" in 1057 sections 6.x to remove conflicting normative qualification of 1058 other normative statements per http://www.ietf.org/mail- 1059 archive/web/oauth/current/msg08892.html. 1061 o Add text the client_id must id the client to 4.1 and remove 1062 similar text from other places per http://www.ietf.org/mail- 1063 archive/web/oauth/current/msg08893.html. 1065 o Remove the MUST from the text prior to the HTTP parameter 1066 definitions per http://www.ietf.org/mail- 1067 archive/web/oauth/current/msg08920.html. 1069 o Updated examples to use grant_type and client_assertion_type 1070 values from the OAuth SAML Assertion Profiles spec. 1072 Authors' Addresses 1074 Brian Campbell 1075 Ping Identity 1077 Email: brian.d.campbell@gmail.com 1079 Chuck Mortimore 1080 Salesforce.com 1082 Email: cmortimore@salesforce.com 1084 Michael B. Jones 1085 Microsoft 1087 Email: mbj@microsoft.com 1089 Yaron Y. Goland 1090 Microsoft 1092 Email: yarong@microsoft.com