idnits 2.17.1 draft-ietf-oauth-assertions-01.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 31, 2011) is 4559 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 C. Mortimore, Ed. 3 Internet-Draft Salesforce 4 Intended status: Standards Track M. Jones 5 Expires: May 3, 2012 Microsoft 6 B. Campbell 7 Ping 8 Y. Goland 9 Microsoft 10 October 31, 2011 12 OAuth 2.0 Assertion Profile 13 draft-ietf-oauth-assertions-01 15 Abstract 17 This specification provides a general framework for the use of 18 assertions as client credentials and/or authorization grants with 19 OAuth 2.0. It includes a generic mechanism for transporting 20 assertions during interactions with a token endpoint, as wells as 21 rules for the content and processing of those assertions. The intent 22 is to provide an enhanced security profile by using derived values 23 such as signatures or HMACs, as well as facilitate the use of OAuth 24 2.0 in client-server integration scenarios where the end-user may not 25 be present. 27 This specification only defines abstract message flow and assertion 28 content. Actual use requires implementation of a companion protocol 29 binding specification. Additional profile documents provide standard 30 representations in formats such as SAML and JWT. 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 May 3, 2012. 49 Copyright Notice 51 Copyright (c) 2011 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. Requirements Notation and Conventions . . . . . . . . . . . . 3 67 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3. Authentication vs. Authorization . . . . . . . . . . . . . . . 4 69 4. Transporting Assertions . . . . . . . . . . . . . . . . . . . 4 70 4.1. Using Assertions for Client Authentication . . . . . . . . 4 71 4.2. Using Assertions as Authorization Grants . . . . . . . . . 5 72 5. Assertion Content and Processing . . . . . . . . . . . . . . . 6 73 5.1. Assertion Metamodel . . . . . . . . . . . . . . . . . . . 7 74 5.2. General Assertion Format and Processing Rules . . . . . . 8 75 6. Specific Assertion Format and Processing Rules . . . . . . . . 8 76 6.1. Client authentication . . . . . . . . . . . . . . . . . . 9 77 6.2. Client acting on behalf of itself . . . . . . . . . . . . 9 78 6.3. Client acting on behalf of a user . . . . . . . . . . . . 11 79 6.4. Client acting on behalf of an anonymous user . . . . . . . 12 80 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 13 81 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 82 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 83 9.1. Parameter Registration Request . . . . . . . . . . . . . . 14 84 9.2. Parameter Registration Request . . . . . . . . . . . . . . 14 85 9.3. Parameter Registration Request . . . . . . . . . . . . . . 15 86 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 87 11. Normative References . . . . . . . . . . . . . . . . . . . . . 15 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 90 1. Requirements Notation and Conventions 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 94 document are to be interpreted as described in [RFC2119] . 96 Throughout this document, values are quoted to indicate that they are 97 to be taken literally. When using these values in protocol messages, 98 the quotes MUST NOT be used as part of the value. 100 2. Overview 102 The OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2] provides a 103 method for making authenticated HTTP requests to a resource using an 104 access token. Access tokens are issued to clients by an 105 authorization server with the (sometimes implicit) approval of the 106 resource owner. These access tokens are typically obtained by 107 exchanging an authorization grant representing authorization by the 108 resource owner or privileged administrator. Several authorization 109 grant types are defined to support a wide range of client types and 110 user experiences. OAuth also allows for the definition of new 111 extension grant types to support additional clients or to provide a 112 bridge between OAuth and other trust frameworks. Finally, OAuth 113 allows the definition of additional authentication mechanisms to be 114 used by clients when interacting with the authorization server. 116 In scenarios where security is at a premium one wants to avoid 117 sending secrets across the Internet, even on encrypted connections. 118 Instead one wants to send values derived from the secret that prove 119 to the receiver that the sender is in possession of the secret 120 without actually sending the secret. Typically the way derived 121 values are created is by generating an assertion that is then either 122 HMAC'ed or digitally signed using an agreed upon secret. By 123 validating the HMAC or digital signature on the assertion, the 124 receiver can prove to themselves that the entity that generated the 125 assertion was in possession of the secret without actually 126 communicating the secret directly. 128 This specification provides a general framework for the use of 129 assertions as client credentials and/or authorization grants with 130 OAuth 2.0. It includes a generic mechanism for transporting 131 assertions during interactions with a token endpoint, as wells as 132 rules for the content and processing of those assertions. The intent 133 is to provide an enhanced security profile by using derived values 134 such as signatures or HMACs, as well as facilitate the use of OAuth 135 2.0 in client-server integration scenarios where the end-user may not 136 be present. 138 This specification only defines abstract message flow and assertion 139 content. Actual use requires implementation of a companion protocol 140 binding specification. Additional profile documents provide standard 141 representations in formats such as SAML and JWT. 143 3. Authentication vs. Authorization 145 This specification provides a model for using assertions for 146 authentication of an OAuth client during interactions with an 147 Authorization Server, as well as the use of assertions as 148 authorization grants. It is important to note that the use of 149 assertions for client authentication is orthogonal and separable from 150 using assertions as an authorization grant and can be used either in 151 combination or in isolation. In addition, in scenarios when 152 assertion based authentication and authorization are used in 153 combination, the assertion format and processing may be redundant; 154 under such circumstances, the protocol may be optimized to present a 155 single assertion. 157 4. Transporting Assertions 159 This section defines generic HTTP parameters for transporting 160 assertions during interactions with a token endpoint. 162 4.1. Using Assertions for Client Authentication 164 In scenarios where one wants to avoid sending secrets, one wants to 165 send values derived from the secret that prove to the receiver that 166 the sender is in possession of the secret without actually sending 167 the secret. 169 For example, a client can establish a secret using an out-of-band 170 mechanism with a resource server. As part of this out-of-band 171 communication the client and resource server agree that the client 172 will authenticate itself using an assertion with agreed upon 173 parameters that will be signed by the provisioned secret. Later on, 174 the client might send an access token request to the token endpoint 175 for the resource server that includes an authorization code, as well 176 as a client_assertion that is signed with the previously agreed key 177 and parameters. The client_assertion proves to the token endpoint 178 the identity of the client and the authorization code provides the 179 link to the end-user authorization. 181 The following section defines the use of assertions as client 182 credentials as an extension of Section 3.2 of OAuth 2.0 183 [I-D.ietf.oauth-v2]. When using assertions as client credentials, 184 the client MUST include the assertion using the following HTTP 185 request parameters: 187 client_id OPTIONAL. The client identifier as described in Section 3 188 of OAuth 2.0 [I-D.ietf.oauth-v2]. 190 client_assertion_type REQUIRED. The format of the assertion as 191 defined by the authorization server. The value MUST be an 192 absolute URI. 194 client_assertion REQUIRED. The assertion being used to authenticate 195 the client. Specific serialization of the assertion is defined by 196 profile documents. The serialization MUST be encoded for 197 transport within HTTP forms. It is RECOMMENDED that base64url be 198 used. 200 The following non-normative example demonstrates a client 201 authenticating using an assertion during an Authorization Code Access 202 Token Request as defined in Section 4.1.3 of OAuth 2.0 203 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only): 204 POST /token HTTP/1.1 205 Host: server.example.com 206 Content-Type: application/x-www-form-urlencoded 208 grant_type=authorization_code& 209 code=i1WsRn1uB1& 210 client_id=s6BhdRkqt3& 211 client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion& 212 client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT 214 The client MUST NOT include the client_credential using more than one 215 mechanism. Token endpoints can differentiate between client 216 assertion credentials and other client credential types by looking 217 for the presence of the client_assertion and client_assertion_type 218 attributes which will only be present with client assertion 219 credentials. See section 7 for more details 221 4.2. Using Assertions as Authorization Grants 223 An assertion can be used to request an access token when a client 224 wishes to utilize an existing trust relationship. This may be done 225 through the semantics of (and a digital signature/HMAC calculated 226 over) the assertion, and expressed to the authorization server 227 through an extension authorization grant type. The processes by 228 which authorization is previously granted, and by which the client 229 obtains the assertion prior to exchanging it with the authorization 230 server, are out of scope. 232 The following defines the use of assertions as authorization grants 233 as an extension of OAuth 2.0 [I-D.ietf.oauth-v2], section 4.5. When 234 using assertions as authorization grants, the client MUST include the 235 assertion using the following HTTP request parameters: 237 client_id OPTIONAL. The client identifier as described in Section 3 238 of OAuth 2.0 [I-D.ietf.oauth-v2]. 240 grant_type REQUIRED. The format of the assertion as defined by the 241 authorization server. The value MUST be an absolute URI. 243 assertion REQUIRED. The assertion being used as an authorization 244 grant. Specific serialization of the assertion is defined by 245 profile documents. The serialization MUST be encoded for 246 transport within HTTP forms. It is RECOMMENDED that base64url be 247 used. 249 scope OPTIONAL. The request MAY contain a "scope" parameter. The 250 scope of the access request is expressed as a list of space- 251 delimited strings. The value is defined by the authorization 252 server. If the value contains multiple space- delimited strings, 253 their order does not matter, and each string adds an additional 254 access range to the requested scope. When exchanging assertions 255 for access_tokens, the authorization for the token has been 256 previously granted through some other mechanism. As such, the 257 requested scope SHOULD be equal or lesser than the scope 258 originally granted to the authorized accessor. If the scope 259 parameter and/or value is omitted, the scope SHOULD be treated as 260 equal to the scope originally granted to the authorized accessor. 261 The Authorization Server SHOULD limit the scope of the issued 262 access token to be equal or lesser than the scope originally 263 granted to the authorized accessor. 265 The following non-normative example demonstrates an assertion being 266 used as an authorization grant. (line breaks are for display purposes 267 only): 268 POST /token HTTP/1.1 269 Host: server.example.com 270 Content-Type: application/x-www-form-urlencoded 272 client_id=s6BhdRkqt3& 273 grant_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion& 274 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 276 5. Assertion Content and Processing 278 This section provides a general content and processing model for the 279 use of assertions in OAuth 2.0 [I-D.ietf.oauth-v2]. 281 5.1. Assertion Metamodel 283 The following are entities and metadata involved in the issuance, 284 exchange and processing of assertions in OAuth 2.0. These are 285 general terms, abstract from any particular assertion format. 286 Mappings of these terms into specific representations are provided by 287 profiles of this specification. 289 Issuer The unique identifier for the entity that issued the 290 assertion. Generally this is the entity that holds the keying 291 material used to generate the assertion. In some use-cases 292 Issuers may be either OAuth Clients (when assertions are self- 293 asserted ) or a Security Token Service (an entity capable of 294 issuing, renewing, transforming and validating of security 295 tokens). 297 Principal A unique identifier for the subject of the assertion. 298 When using assertions for client authentication, the Principal 299 SHOULD be the client_id of the OAuth client. When using 300 assertions as an authorization grant, the Principal MUST identify 301 an authorized accessor for whom the access token is being 302 requested (typically the resource owner, or an authorized 303 delegate). 305 Audience A URI that identifies the party intended to process the 306 assertion. The audience SHOULD be the URL of the Token Endpoint 307 as defined in section 2.2 of OAuth 2.0 [I-D.ietf.oauth-v2]. 309 Issued At The time at which the assertion was issued. While the 310 serialization may differ by assertion format, this is always 311 expressed in UTC with no time zone component. 313 Expires At The time at which the assertion expires. While the 314 serialization may differ by assertion format, this is always 315 expressed in UTC with no time zone component. 317 Assertion ID A nonce or unique identifier for the assertion. The 318 Assertion ID may be used by implementations requiring message de- 319 duplication for one-time use assertions. Any entity that assigns 320 an identifier MUST ensure that there is negligible probability 321 that that entity or any other entity will accidentally assign the 322 same identifier to a different data object. 324 5.2. General Assertion Format and Processing Rules 326 The following are general format and processing rules for the use of 327 assertions in OAuth: 329 o The assertion MUST contain an Issuer. The Issuer MUST identify 330 the entity that issued the assertion as recognized by the 331 Authorization Server. If an assertion is self-asserted, the 332 Issuer SHOULD be the client_id. 334 o The assertion SHOULD contain a Principal. The Principal MUST 335 identify an authorized accessor for whom the access token is being 336 requested ( typically the resource owner, or an authorized 337 delegate ) When the client is acting on behalf of itself, the 338 Principal SHOULD be the client_id. 340 o The assertion MUST contain an Audience that identifies the 341 Authorization Server as the intended audience. The Authorization 342 Server MUST verify that it is an intended audience for the 343 assertion. The Audience SHOULD be the URL of the Authorization 344 Server's Token Endpoint. 346 o The assertion MUST contain an Expires At entity that limits the 347 time window during which the assertion can be used. The 348 authorization server MUST verify that the expiration time has not 349 passed, subject to allowable clock skew between systems. The 350 authorization server SHOULD reject assertions with an Expires At 351 attribute value that is unreasonably far in the future. 353 o The assertion MAY contain an Issued At entity containing the UTC 354 time at which the assertion was issued. 356 o The assertion MAY contain an Assertion ID. An Authorization 357 Server MAY dictate that Assertion ID is mandatory. 359 o The Authorization Server MUST validate the assertion in order to 360 establish a mapping between the Issuer and the secret used to 361 generate the assertion. The algorithm used to validate the 362 assertion, and the mechanism for designating the secret used to 363 generate the assertion is out-of-scope for this specification. 365 6. Specific Assertion Format and Processing Rules 367 The following clarifies the format and processing rules defined in 368 section 4 and section 5 for a number of common use-cases: 370 6.1. Client authentication 372 When a client authenticates to a token service using an assertion, it 373 SHOULD do so according to section 4.1. The following format and 374 processing rules SHOULD be applied: 376 o The client_id HTTP parameter SHOULD identify the client to the 377 authorization server. 379 o The client_assertion_type HTTP parameter MUST identify the 380 assertion format being used for authentication. 382 o The client_assertion HTTP parameter MUST contain the serialized 383 assertion in a format indicated by the client_assertion_type 384 parameter. 386 o The Issuer of the assertion MUST identify the entity that issued 387 the assertion as recognized by the Authorization Server. If the 388 assertion is self-asserted, the Issuer SHOULD be the client_id. 390 o The Principal MUST identify an authorized accessor. If the 391 assertion is self-issued, the Principal SHOULD be the client_id. 393 o The Audience of the assertion MUST identify the Authorization 394 Server and SHOULD be the URL of the Token Endpoint. 396 o The Authorization Server MUST validate the assertion in order to 397 establish a mapping between the Issuer and the secret used to 398 generate the assertion. 400 The following non-normative example demonstrates the use of a client 401 authentication using an assertion during an Authorization Code Access 402 Token Request as defined in Section 4.1.3 of OAuth 2.0 403 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only): 404 POST /token HTTP/1.1 405 Host: server.example.com 406 Content-Type: application/x-www-form-urlencoded 408 grant_type=authorization_code& 409 code=i1WsRn1uB1& 410 client_id=s6BhdRkqt3& 411 client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion& 412 client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 414 6.2. Client acting on behalf of itself 416 When a client is accessing resources on behalf of itself, it SHOULD 417 do so in a manner analogous to the Client Credentials flow defined in 418 Section 4.4 of OAuth 2.0 [I-D.ietf.oauth-v2]. This is a special case 419 that combines both the authentication and authorization grant usage 420 patterns. In this case, the interactions with the authorization 421 server SHOULD be treated as using an assertion for Client 422 Authentication according to section 4.1, with the addition of a 423 grant_type parameter. The following format and processing rules 424 SHOULD be applied. 426 o The client_id HTTP parameter SHOULD identify the client to the 427 authorization server. 429 o The grant_type HTTP request parameter MUST be 430 "client_credentials". 432 o The client_assertion_type HTTP parameter MUST identify the 433 assertion format. 435 o The client_assertion HTTP parameter MUST contain the serialized 436 assertion as in a format indicated by the client_assertion_type 437 parameter. 439 o The Issuer of the assertion MUST identify the entity that issued 440 the assertion as recognized by the Authorization Server. If the 441 assertion is self-asserted, the Issuer SHOULD be the client_id. 442 If the assertion was issued by a Security Token Service, the 443 Issuer SHOULD identify the STS as recognized by the Authorization 444 Server. 446 o The Principal SHOULD be the client_id. 448 o The Audience of the assertion MUST identify the Authorization 449 Server and SHOULD be the URL of the Token Endpoint. 451 o The Authorization Server MUST validate the assertion in order to 452 establish a mapping between the Issuer and the secret used to 453 generate the assertion. 455 The following non-normative example demonstrates the use of a sample 456 assertion being used for a Client Credentials Access Token Request as 457 defined in Section 4.4.2 of OAuth 2.0 [I-D.ietf.oauth-v2]. (line 458 breaks are for display purposes only): 460 POST /token HTTP/1.1 461 Host: server.example.com 462 Content-Type: application/x-www-form-urlencoded 464 client_id=s6BhdRkqt3& 465 grant_type=client_credentials& 466 client_assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion& 467 client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D 469 6.3. Client acting on behalf of a user 471 When a client is accessing resources on behalf of a user, it SHOULD 472 be treated as using an assertion as an Authorization Grant according 473 to section 4.2. The following format and processing rules SHOULD be 474 applied: 476 o The client_id HTTP parameter MUST identify the client to the 477 authorization server. 479 o The grant_type HTTP request parameter MUST indicate the assertion 480 format. 482 o The assertion HTTP parameter MUST contain the serialized assertion 483 as in a format indicated by the grant_type parameter. 485 o The Issuer of the assertion MUST identify the entity that issued 486 the assertion as recognized by the Authorization Server. If the 487 assertion is self-asserted, the Issuer SHOULD be the client_id. 488 If the assertion was issued by a STS, the Issuer SHOULD identify 489 the STS as recognized by the Authorization Server. 491 o The Principal MUST identify an authorized accessor for whom the 492 access token is being requested (typically the resource owner, or 493 an authorized delegate). 495 o The Audience of the assertion MUST identify the Authorization 496 Server and MAY be the URL of the Token Endpoint. 498 o The Authorization Server MUST validate the assertion in order to 499 establish a mapping between the Issuer and the secret used to 500 generate the assertion. 502 The following non-normative example demonstrates the use of a client 503 authenticating using an assertion during an Authorization Code Access 504 Token Request as defined in Section 4.1.3 of OAuth 2.0 505 [I-D.ietf.oauth-v2]. (line breaks are for display purposes only): 507 POST /token HTTP/1.1 508 Host: server.example.com 509 Content-Type: application/x-www-form-urlencoded 511 client_id=s6BhdRkqt3& 512 grant_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion& 513 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D 515 6.4. Client acting on behalf of an anonymous user 517 When a client is accessing resources on behalf of an anonymous user, 518 the following format and processing rules SHOULD be applied: 520 o The client_id HTTP parameter MUST identify the client to the 521 authorization server. 523 o The grant_type HTTP request parameter MUST indicate the assertion 524 format. 526 o The assertion HTTP parameter MUST contain the serialized assertion 527 as in a format indicated by the grant_type parameter. 529 o The Issuer of the assertion MUST identify the entity that issued 530 the assertion as recognized by the Authorization Server. If the 531 assertion is self-asserted, the Issuer SHOULD be the client_id. 532 If the assertion was issued by a Security Token Service, the 533 Issuer SHOULD identify the STS as recognized by the Authorization 534 Server. 536 o The Principal SHOULD indicate to the Authorization Server that the 537 client is acting on-behalf of an anonymous user as defined by the 538 Authorization Server. It is implied that authorization is based 539 upon additional criteria, such as additional attributes or claims 540 provided in the assertion. For example, a client may present an 541 assertion from a trusted issuer asserting that the bearer is over 542 18 via an included claim. In this case, no additional information 543 about the user's identity is included yet all the data needed to 544 issue an access token is present. 546 o The Audience of the assertion MUST identify the Authorization 547 Server and MAY be the URL of the Token Endpoint. 549 o The Authorization Server MUST validate the assertion in order to 550 establish a mapping between the Issuer and the secret used to 551 generate the assertion. 553 7. Error Responses 555 If an assertion is not valid or has expired, the Authorization Server 556 MUST construct an error response as defined in OAuth 2.0 557 [I-D.ietf.oauth-v2]. The value of the error parameter MUST be the 558 "invalid_grant" error code. The authorization server MAY include 559 additional information regarding the reasons the assertion was 560 considered invalid using the "error_description" or "error_uri" 561 parameters. 563 For example: 564 HTTP/1.1 400 Bad Request 565 Content-Type: application/json 566 Cache-Control: no-store 568 { 569 "error":"invalid_grant", 570 "error_description":"Audience validation failed" 571 } 573 A client MUST NOT include client credentials using more than one 574 mechanism. Token endpoints can differentiate between assertion based 575 credentials and other client credential types by looking for the 576 presence of the client_assertion and client_assertion_type attributes 577 which will only be present when using assertions for client 578 authentication. If more than one mechanism is used, the 579 Authorization Server MUST construct an error response as defined in 580 OAuth 2.0 [I-D.ietf.oauth-v2]. The value of the error parameter MUST 581 be the "invalid_client" error code. The authorization server MAY 582 include additional information regarding the reasons the client was 583 considered invalid using the "error_description" or "error_uri" 584 parameters. 586 For example: 587 HTTP/1.1 400 Bad Request 588 Content-Type: application/json 589 Cache-Control: no-store 591 { 592 "error":"invalid_client" 593 "error_description":"Multiple Credentials Not Allowed" 594 } 596 8. Security Considerations 598 Authorization Providers concerned with preventing replay attacks may 599 choose to implement using replay detection using a combination of the 600 AssertionID and IssuedAt/ExpiredAt attributes. Previously processed 601 assertions MAY be de-duped and rejected based on the AssertionID. 602 The addition of the validity window relieves the authorization server 603 from maintaining an infinite state table of processed assertion IDs. 605 Authorization Servers SHOULD consider the amount of information 606 exposed in error responses, and the risk associated with exposing 607 details of specific processing errors. In addition, Authorization 608 Servers SHOULD prevent timing attacks related to cryptographic 609 processing of the assertion. 611 No additional considerations beyond those described within the OAuth 612 2.0 Protocol Framework, Section 10 [I-D.ietf.oauth-v2]. 614 9. IANA Considerations 616 9.1. Parameter Registration Request 618 The following is the parameter registration request, as defined in 619 The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol 620 [I-D.ietf.oauth-v2], for the "assertion" parameter: 622 o Parameter name: assertion 624 o Parameter usage location: client authentication, token request 626 o Change controller: IETF 628 o Specification document(s): [[this document]] 630 9.2. Parameter Registration Request 632 The following is the parameter registration request, as defined in 633 The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol 634 [I-D.ietf.oauth-v2], for the "client_assertion" parameter: 636 o Parameter name: client_assertion 638 o Parameter usage location: client authentication, token request 640 o Change controller: IETF 642 o Specification document(s): [[this document]] 644 9.3. Parameter Registration Request 646 The following is the parameter registration request, as defined in 647 The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol 648 [I-D.ietf.oauth-v2], for the "client_assertion_type" parameter: 650 o Parameter name: client_assertion_type 652 o Parameter usage location: client authentication, token request 654 o Change controller: IETF 656 o Specification document(s): [[this document]] 658 10. Acknowledgements 660 The authors wish to thank the following people that have influenced 661 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 662 Tony Nadalin, the authors of OAuth WRAP, and those in the OAuth 2 663 working group. 665 11. Normative References 667 [I-D.ietf.oauth-v2] 668 Hammer-Lahav, E., "The OAuth 2.0 Authorization Protocol", 669 September 2011. 671 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 672 Requirement Levels", BCP 14, RFC 2119, March 1997. 674 Authors' Addresses 676 Chuck Mortimore (editor) 677 Salesforce.com 679 Email: cmortimore@salesforce.com 681 Michael B. Jones 682 Microsoft 684 Email: mbj@microsoft.com 685 Brian Campbell 686 Ping Identity 688 Email: bcampbell@pingidentity.com 690 Yaron Y. Goland 691 Microsoft 693 Email: yarong@microsoft.com