idnits 2.17.00 (12 Aug 2021) /tmp/idnits40682/draft-ietf-oauth-v2-07.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 11, 2010) is 4361 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) == Unused Reference: 'NIST FIPS-180-3' is defined on line 1495, but no explicit reference was found in the text == Unused Reference: 'RFC2045' is defined on line 1499, but no explicit reference was found in the text == Unused Reference: 'RFC2104' is defined on line 1503, but no explicit reference was found in the text == Unused Reference: 'RFC3023' is defined on line 1521, but no explicit reference was found in the text == Unused Reference: 'RFC3447' is defined on line 1524, but no explicit reference was found in the text == Unused Reference: 'RFC3629' is defined on line 1528, but no explicit reference was found in the text == Unused Reference: 'I-D.hammer-oauth' is defined on line 1549, but no explicit reference was found in the text == Unused Reference: 'I-D.hardt-oauth' is defined on line 1553, but no explicit reference was found in the text == Outdated reference: draft-ietf-httpbis-p1-messaging has been published as RFC 7230 -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST FIPS-180-3' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Downref: Normative reference to an Informational RFC: RFC 2818 ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: draft-hammer-oauth has been published as RFC 5849 Summary: 8 errors (**), 0 flaws (~~), 12 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer-Lahav, Ed. 3 Internet-Draft Yahoo! 4 Intended status: Standards Track D. Recordon 5 Expires: December 13, 2010 Facebook 6 D. Hardt 7 Microsoft 8 June 11, 2010 10 The OAuth 2.0 Protocol 11 draft-ietf-oauth-v2-07 13 Abstract 15 This specification describes the OAuth 2.0 protocol. OAuth provides 16 a method for making authenticated HTTP requests using a token - an 17 string used to denote an access grant with specific scope, duration, 18 and other attributes. Tokens are issued to third-party clients by an 19 authorization server with the approval of the resource owner. OAuth 20 defines multiple flows for obtaining a token to support a wide range 21 of client types and user experience. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on December 13, 2010. 40 Copyright Notice 42 Copyright (c) 2010 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 1.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 1.4. Notational Conventions . . . . . . . . . . . . . . . . . . 8 62 2. Client Flows . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 2.1. Web Server Flow . . . . . . . . . . . . . . . . . . . . . 8 64 2.2. User-Agent Flow . . . . . . . . . . . . . . . . . . . . . 10 65 2.3. Username and Password Flow . . . . . . . . . . . . . . . . 11 66 2.4. Client Credentials Flow . . . . . . . . . . . . . . . . . 13 67 2.5. Assertion Flow . . . . . . . . . . . . . . . . . . . . . . 13 68 2.6. Native Application Considerations . . . . . . . . . . . . 14 69 3. Client Credentials . . . . . . . . . . . . . . . . . . . . . . 15 70 3.1. Client Authentication . . . . . . . . . . . . . . . . . . 15 71 4. Establishing Resource Owner Authorization . . . . . . . . . . 16 72 4.1. Verification Code . . . . . . . . . . . . . . . . . . . . 17 73 4.1.1. End-User Authorization Endpoint . . . . . . . . . . . 17 74 4.2. Resource Owner Credentials . . . . . . . . . . . . . . . . 20 75 4.3. Assertion . . . . . . . . . . . . . . . . . . . . . . . . 21 76 5. Obtaining an Access Token . . . . . . . . . . . . . . . . . . 21 77 5.1. Token Endpoint . . . . . . . . . . . . . . . . . . . . . . 21 78 5.1.1. Verification Code . . . . . . . . . . . . . . . . . . 22 79 5.1.2. Resource Owner Credentials . . . . . . . . . . . . . . 22 80 5.1.3. Assertion . . . . . . . . . . . . . . . . . . . . . . 23 81 5.1.4. Refresh Token . . . . . . . . . . . . . . . . . . . . 24 82 5.1.5. Access Token Response . . . . . . . . . . . . . . . . 25 83 5.1.6. Error Response . . . . . . . . . . . . . . . . . . . . 26 84 6. Accessing a Protected Resource . . . . . . . . . . . . . . . . 27 85 6.1. The Authorization Request Header . . . . . . . . . . . . . 28 86 6.2. URI Query Parameter . . . . . . . . . . . . . . . . . . . 28 87 6.3. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 29 88 7. Identifying a Protected Resource . . . . . . . . . . . . . . . 30 89 7.1. The WWW-Authenticate Response Header . . . . . . . . . . . 30 90 8. Security Considerations . . . . . . . . . . . . . . . . . . . 31 91 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 92 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 31 93 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 31 94 Appendix C. Document History . . . . . . . . . . . . . . . . . . 32 95 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 96 10.1. Normative References . . . . . . . . . . . . . . . . . . . 34 97 10.2. Informative References . . . . . . . . . . . . . . . . . . 35 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 100 1. Introduction 102 With the increasing use of distributed web services and cloud 103 computing, third-party applications require access to server-hosted 104 resources. These resources are usually protected and require 105 authentication using the resource owner's credentials (typically a 106 username and password). In the traditional client-server 107 authentication model, a client accessing a protected resource on a 108 server presents the resource owner's credentials in order to 109 authenticate and gain access. 111 Resource owners should not be required to share their credentials 112 when granting third-party applications access to their protected 113 resources. They should also have the ability to restrict access to a 114 limited subset of the resources they control, to limit access 115 duration, or to limit access to the HTTP methods supported by these 116 resources. 118 OAuth provides a method for making authenticated HTTP requests using 119 a token - an identifier used to denote an access grant with specific 120 scope, duration, and other attributes. Tokens are issued to third- 121 party clients by an authorization server with the approval of the 122 resource owner. Instead of sharing their credentials with the 123 client, resource owners grant access by authenticating directly with 124 the authorization server which in turn issues a token to the client. 125 The client uses the token to authenticate with the resource server 126 and gain access. 128 For example, a web user (resource owner) can grant a printing service 129 (client) access to her protected photos stored at a photo sharing 130 service (resource server), without sharing her username and password 131 with the printing service. Instead, she authenticates directly with 132 the photo sharing service (authorization server) which issues the 133 printing service delegation-specific credentials (token). 135 This specification defines the use of OAuth over HTTP [RFC2616] (or 136 HTTP over TLS as defined by [RFC2818]). Other specifications may 137 extend it for use with other transport protocols. 139 1.1. Terminology 141 resource server 142 An HTTP [RFC2616] server capable of accepting authenticated 143 resource requests using the OAuth protocol. 145 protected resource 146 An access-restricted resource which can be obtained from a 147 resource server using an OAuth-authenticated request. 149 client 150 An HTTP client capable of making authenticated requests for 151 protected resources using the OAuth protocol. 153 resource owner 154 An entity capable of granting access to a protected resource. 156 end-user 157 A human resource owner. 159 token 160 A string representing an access grant issued to the client. 161 The string is usually opaque to the client and can self-contain 162 the authorization information in a verifiable manner (i.e. 163 signed), or denotes an identifier used to retrieve the 164 authorization information. 166 access token 167 A token used by the client to make authenticated requests on 168 behalf of the resource owner. Access tokens represent a 169 specific scope, duration, and other access attributes granted 170 by the resource owner and enforced by the resource and 171 authorization servers. 173 refresh token 174 A token used by the client to replace an expired access token 175 with a new access token without having to involve the resource 176 owner. A refresh token is used when the access token is valid 177 for a shorter time period than the duration of the access grant 178 granted by the resource owner. 180 authorization server 181 An HTTP server capable of issuing tokens after successfully 182 authenticating the resource owner and obtaining authorization. 183 The authorization server may be the same server as the resource 184 server, or a separate entity. 186 end-user authorization endpoint 187 The authorization server's HTTP endpoint capable of 188 authenticating the end-user and obtaining authorization. 190 token endpoint 191 The authorization server's HTTP endpoint capable of issuing 192 tokens and refreshing expired tokens. 194 client identifier 195 An unique identifier issued to the client to identify itself to 196 the authorization server. Client identifiers may have a 197 matching secret. 199 1.2. Overview 201 Clients interact with a protected resource, first by requesting 202 access (which is granted in the form of an access token) from the 203 authorization server, and then by authenticating with the resource 204 server by presenting the access token. Figure 1 demonstrates the 205 flow between the client and authorization server (A, B), and the flow 206 between the client and resource server (C, D), when the client is 207 acting autonomously (the client is also the resource owner). 209 +--------+ +---------------+ 210 | |--(A)------ Credentials --------->| Authorization | 211 | | | Server | 212 | |<-(B)------ Access Token ---------| | 213 | | (w/ Optional Refresh Token) +---------------+ 214 | Client | 215 | | HTTP Request +---------------+ 216 | |--(C)--- with Access Token ------>| Resource | 217 | | | Server | 218 | |<-(D)------ HTTP Response --------| | 219 +--------+ +---------------+ 221 Figure 1: Generic Client-Server Flow 223 Access token strings can use any internal structure agreed upon 224 between the authorization server and the resource server, but their 225 structure is opaque to the client. Since the access token provides 226 the client access to the protected resource for the life of the 227 access token (or until revoked), the authorization server should 228 issue access tokens which expire within an appropriate time, usually 229 much shorter than the duration of the access grant. 231 When an access token expires, the client can request a new access 232 token from the authorization server by presenting its credentials 233 again (Figure 1), or by using the refresh token (if issued with the 234 access token) as shown in Figure 2. Once an expired access token has 235 been replaced with a new access token (A, B), the client uses the new 236 access token as before (C, D). 238 +--------+ +---------------+ 239 | |--(A)------ Refresh Token ------->| Authorization | 240 | | | Server | 241 | |<-(B)------ Access Token ---------| | 242 | | +---------------+ 243 | Client | 244 | | HTTP Request +---------------+ 245 | |--(C)--- with Access Token ------>| Resource | 246 | | | Server | 247 | |<-(D)----- HTTP Response ---------| | 248 +--------+ +---------------+ 250 Figure 2: Refreshing an Access Token 252 This specification defines a number of authorization flows to support 253 different client types and scenarios. These authorization flows can 254 be separated into three groups: user delegation flows, direct 255 credentials flows, and autonomous flows. 257 Additional authorization flows may be defined by other specifications 258 to cover different scenarios and client types. 260 User delegation flows are used to grant client access to protected 261 resources by the end-user without sharing the end-user credentials 262 (e.g. a username and password) with the client. Instead, the end- 263 user authenticates directly with the authorization server, and grants 264 client access to its protected resources. The user delegation flows 265 defined by this specifications are: 267 o Web Server Flow - This flow is optimized for clients that are part 268 of a web server application, accessible via HTTP requests. This 269 flow is described in Section 2.1. 271 o User-Agent Flow - This flow is designed for clients running inside 272 a user-agent (typically a web browser). This flow is described in 273 Section 2.2. 275 Direct credentials flows enable clients to obtain an access token 276 with a single request using the client credentials or end-user 277 credentials without seeking additional resource owner authorization. 278 The direct credentials flows defined by this specification are: 280 o Username and Password Flow - This flow is used in cases where the 281 end-user trusts the client to handle its credentials but it is 282 still undesirable for the client to store the end-user's username 283 and password. This flow is only suitable when there is a high 284 degree of trust between the end-user and the client. This flow is 285 described in Section 2.3. 287 o Client Credentials Flow - The client uses its credentials to 288 obtain an access token. This flow is described in Section 2.4. 290 Autonomous flows enable clients to utilize existing trust 291 relationships or different authorization constructs to obtain an 292 access token. They provide a bridge between OAuth and other trust 293 frameworks. The autonomous authorization flow defined by this 294 specifications is: 296 o Assertion Flow - The client presents an assertion such as a SAML 297 [OASIS.saml-core-2.0-os] assertion to the authorization server in 298 exchange for an access token. This flow is described in 299 Section 2.5. 301 The sizes of tokens and other values received from the authorization 302 server, are left undefined by this specification. Clients should 303 avoid making assumptions about value sizes. Servers should document 304 the expected size of any value they issue. 306 1.3. Example 308 [[ Todo ]] 310 1.4. Notational Conventions 312 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 313 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 314 document are to be interpreted as described in [RFC2119]. 316 This document uses the Augmented Backus-Naur Form (ABNF) notation of 317 [I-D.ietf-httpbis-p1-messaging]. Additionally, the realm and auth- 318 param rules are included from [RFC2617]. 320 Unless otherwise noted, all the protocol parameter names and values 321 are case sensitive. 323 2. Client Flows 325 2.1. Web Server Flow 327 The web server flow is a user delegation flow suitable for clients 328 capable of interacting with the end-user's user-agent (typically a 329 web browser) and capable of receiving incoming requests from the 330 authorization server (capable of acting as an HTTP server). 332 +----------+ Client Identifier +---------------+ 333 | -+----(A)-- & Redirect URI ------->| | 334 | End-user | | Authorization | 335 | at |<---(B)-- User authenticates --->| Server | 336 | Browser | | | 337 | -+----(C)-- Verification Code ----<| | 338 +-|----|---+ +---------------+ 339 | | ^ v 340 (A) (C) | | 341 | | | | 342 ^ v | | 343 +---------+ | | 344 | |>---(D)-- Client Credentials, --------' | 345 | Web | Verification Code, | 346 | Client | & Redirect URI | 347 | | | 348 | |<---(E)------- Access Token -----------------' 349 +---------+ (w/ Optional Refresh Token) 351 Figure 3: Web Server Flow 353 The web server flow illustrated in Figure 3 includes the following 354 steps: 356 (A) The web client initiates the flow by redirecting the end-user's 357 user-agent to the end-user authorization endpoint as described 358 in Section 4.1.1 using client type "web_server". The client 359 includes its client identifier, requested scope, local state, 360 and a redirect URI to which the authorization server will send 361 the end-user back once authorization is granted (or denied). 363 (B) The authorization server authenticates the end-user (via the 364 user-agent) and establishes whether the end-user grants or 365 denies the client's access request. 367 (C) Assuming the end-user granted access, the authorization server 368 redirects the user-agent back to the client to the redirection 369 URI provided earlier. The authorization includes a verification 370 code for the client to use to obtain an access token. 372 (D) The client requests an access token from the authorization 373 server by authenticating and including the verification code 374 received in the previous step as described in Section 5.1. 376 (E) The authorization server validates the client credentials and 377 the verification code and responds back with the access token. 379 2.2. User-Agent Flow 381 The user-agent flow is a user delegation flow suitable for client 382 applications residing in a user-agent, typically implemented in a 383 browser using a scripting language such as JavaScript. These clients 384 cannot keep client secrets confidential and the authentication of the 385 client is based on the user-agent's same-origin policy. 387 Unlike other flows in which the client makes separate authorization 388 and access token requests, the client received the access token as a 389 result of the authorization request in the form of an HTTP 390 redirection. The client requests the authorization server to 391 redirect the user-agent to another web server or local resource 392 accessible to the browser which is capable of extracting the access 393 token from the response and passing it to the client. 395 This user-agent flow does not utilize the client secret since the 396 client executables reside on the end-user's computer or device which 397 makes the client secret accessible and exploitable. Because the 398 access token is encoded into the redirection URI, it may be exposed 399 to the end-user and other applications residing on the computer or 400 device. 402 +----------+ Client Identifier +----------------+ 403 | |>---(A)-- & Redirection URI --->| | 404 | | | | 405 End <--+ - - - +----(B)-- User authenticates -->| Authorization | 406 User | | | Server | 407 | |<---(C)-- Redirect URI --------<| | 408 | Client | with Access Token | | 409 | in | (w/ Optional Refresh Token) +----------------+ 410 | Browser | in Fragment 411 | | +----------------+ 412 | |>---(D)-- Redirect URI -------->| | 413 | | without Fragment | Web Server | 414 | | | with Client | 415 | (F) |<---(E)-- Web Page with -------<| Resource | 416 | Access | Script | | 417 | Token | +----------------+ 418 +----------+ 419 Figure 4: User-Agent Flow 421 The user-agent flow illustrated in Figure 4 includes the following 422 steps: 424 (A) The client sends the user-agent to the end-user authorization 425 endpoint as described in Section 4.1.1 using client type 426 "user-agent". The client includes its client identifier, 427 requested scope, local state, and a redirect URI to which the 428 authorization server will send the end-user back once 429 authorization is granted (or denied). 431 (B) The authorization server authenticates the end-user (via the 432 user-agent) and establishes whether the end-user grants or 433 denies the client's access request. 435 (C) Assuming the end-user granted access, the authorization server 436 redirects the user-agent to the redirection URI provided 437 earlier. The redirection URI includes the access token (and an 438 optional verification code) in the URI fragment. 440 (D) The user-agent follows the redirection instructions by making an 441 HTTP "GET" request to the web server which does not include the 442 fragment. The user-agent retains the fragment information 443 locally. The user-agent MUST NOT include the fragment component 444 with the request. 446 (E) The web server returns a web page (typically an HTML page with 447 an embedded script) capable of accessing the full redirection 448 URI including the fragment retained by the user-agent, and 449 extracting the access token (and other parameters) contained in 450 the fragment. 452 (F) The user-agent executes the script provided by the web server 453 which extracts the access token and passes it to the client. If 454 a verification code was issued, the client can pass it to a web 455 server component to obtain another access token for additional 456 server-based protected resources interaction. 458 2.3. Username and Password Flow 460 The username and password flow is suitable for clients capable of 461 asking end-users for their usernames and passwords. It is also used 462 to migrate existing clients using direct authentication schemes such 463 as HTTP Basic or Digest authentication to OAuth by converting the 464 end-user credentials stored with tokens. 466 However, unlike the HTTP Basic authentication scheme defined in 468 [RFC2617], the end-user's credentials are used in a single request 469 and are exchanged for an access token and refresh token which 470 eliminates the client need to store them for future use. 472 The methods through which the client prompts end users for their 473 usernames and passwords is beyond the scope of this specification. 474 The client MUST discard the usernames and passwords once an access 475 token has been obtained. 477 This flow is suitable in cases where the end-user already has a trust 478 relationship with the client, such as its computer operating system 479 or highly privileged applications. Authorization servers should take 480 special care when enabling the username and password flow, and only 481 when other delegation flows are not viable. 483 End-user 484 v 485 : 486 (A) 487 : 488 v 489 +--------+ +---------------+ 490 | | Client Credentials | | 491 | |>--(B)--- & User Credentials ---->| Authorization | 492 | Client | | Server | 493 | |<--(C)---- Access Token ---------<| | 494 | | (w/ Optional Refresh Token) | | 495 +--------+ +---------------+ 497 Figure 5: Username and Password Flow 499 The username and password flow illustrated in Figure 5 includes the 500 following steps: 502 (A) The end-user provides the client with its username and password. 504 (B) The client requests an access token from the authorization 505 server by authenticating and including the end-user's username 506 and password, and desired scope as described in Section 5.1. 508 (C) The authorization server validates the end-user credentials and 509 the client credentials and issues an access token. 511 2.4. Client Credentials Flow 513 The client credentials flow is used when the client acts on behalf of 514 itself (the client is the resource owner), or when the client 515 credentials are used to obtain an access token representing a 516 previously established access authorization. The client secret is 517 assumed to be high-entropy since it is not designed to be memorized 518 by an end-user. 520 +--------+ +---------------+ 521 | | | | 522 | |>--(A)--- Client Credentials ---->| Authorization | 523 | Client | | Server | 524 | |<--(B)---- Access Token ---------<| | 525 | | (w/ Optional Refresh Token) | | 526 +--------+ +---------------+ 528 Figure 6: Client Credentials Flow 530 The client credential flow illustrated in Figure 6 includes the 531 following steps: 533 (A) The client requests an access token from the authorization 534 server by authenticating and including the desired scope as 535 described in Section 5.1. No additional authorization grant 536 information is needed. 538 (B) The authorization server validates the client credentials and 539 issues an access token. 541 2.5. Assertion Flow 543 The assertion flow is used when a client wishes to exchange an 544 existing security token or assertion for an access token. This flow 545 is suitable when the client is the resource owner or is acting on 546 behalf of the resource owner (based on the content of the assertion 547 used). 549 The assertion flow requires the client to obtain a assertion (such as 550 a SAML [OASIS.saml-core-2.0-os] assertion) from an assertion issuer 551 or to self-issue an assertion prior to initiating the flow. The 552 assertion format, the process by which the assertion is obtained, and 553 the method of validating the assertion are defined by the assertion 554 issuer and the authorization server, and are beyond the scope of this 555 specification. 557 +--------+ +---------------+ 558 | | | | 559 | |>--(A)------ Assertion ---------->| Authorization | 560 | Client | | Server | 561 | |<--(B)---- Access Token ---------<| | 562 | | | | 563 +--------+ +---------------+ 565 Figure 7: Assertion Flow 567 The assertion flow illustrated in Figure 7 includes the following 568 steps: 570 (A) The client requests an access token from the authorization 571 server by authenticating and including the assertion, assertion 572 type, and desired scope as described in Section 5.1. 574 (B) The authorization server validates the assertion and issues an 575 access token. 577 2.6. Native Application Considerations 579 Native application are clients running as native code on the end- 580 user's computer or device (i.e. executing outside a browser or as a 581 desktop program). These clients are often capable of interacting 582 with (or embedding) the end-user's user-agent but are incapable of 583 receiving callback requests from the server (incapable of acting as 584 an HTTP server). 586 Native application clients can utilize many of the flows defined in 587 this specification with little or no changes. For example: 589 o Launch an external user-agent and have it redirect back to the 590 client using a custom URI scheme. This works with the web server 591 flow and user-agent flow. 593 o Launch an external user-agent and poll for changes to the window 594 title. This works with the web server flow with a server-hosted 595 custom redirect result page that puts the verification code in the 596 title. 598 o Use an embedded user-agent and obtain the redirection URI. This 599 works with the web server flow and user-agent flow. 601 o Use the username and password flow and prompt the end-users for 602 their credentials. This is generally discouraged as it hands the 603 end-user's password directly to the 3rd party and may not work 604 with some authentication schemes. 606 When choosing between launching an external browser and an embedded 607 user-agent, developers should consider the following: 609 o External user-agents may improve completion rate as the end-user 610 may already be logged-in and not have to re-authenticate. 612 o Embedded user-agents often offer a better end-user flow, as they 613 remove the need to switch context and open new windows. 615 o Embedded user-agents are less secure because users are 616 authenticating in unidentified window without access to the 617 protections offered by many user-agents. 619 3. Client Credentials 621 When requesting access from the authorization server, the client 622 identifies itself using a set of client credentials. The client 623 credentials include a client identifier and an OPTIONAL symmetric 624 shared secret. The means through which the client obtains these 625 credentials are beyond the scope of this specification, but usually 626 involve registration with the authorization server. 628 The client identifier is used by the authorization server to 629 establish the identity of the client for the purpose of presenting 630 information to the resource owner prior to granting access, as well 631 as for providing different service levels to different clients. They 632 can also be used to block unauthorized clients from requesting 633 access. 635 Due to the nature of some clients, authorization servers SHOULD NOT 636 make assumptions about the confidentiality of client credentials 637 without establishing trust with the client operator. Authorization 638 servers SHOULD NOT issue client secrets to clients incapable of 639 keeping their secrets confidential. 641 3.1. Client Authentication 643 The token endpoint requires the client to authenticate itself to the 644 authorization server. This is done by including the client 645 identifier (and optional secret) in the request. The client 646 identifier and secret are included in the request using two request 647 parameters: "client_id" and "client_secret". 649 For example (line breaks are for display purposes only): 651 POST /token HTTP/1.1 652 Host: server.example.com 653 Content-Type: application/x-www-form-urlencoded 655 type=web_server&client_id=s6BhdRkqt3& 656 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 657 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 659 The client MAY include the client credentials using an HTTP 660 authentication scheme which supports authenticating using a username 661 and password, instead of using the "client_id" and "client_secret" 662 request parameters. Including the client credentials using an HTTP 663 authentication scheme fulfills the requirements of including the 664 parameters as defined by the various flows. 666 The client MUST NOT include the client credentials using more than 667 one mechanism. If more than one mechanism is used, regardless if the 668 credentials are identical, the server MUST reply with an HTTP 400 669 status code (Bad Request) and include the "multiple-credentials" 670 error message. 672 The authorization server MUST accept the client credentials using 673 both the request parameters, and the HTTP Basic authentication scheme 674 as defined in [RFC2617]. The authorization server MAY support 675 additional HTTP authentication schemes. 677 For example (line breaks are for display purposes only): 679 POST /token HTTP/1.1 680 Host: server.example.com 681 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 682 Content-Type: application/x-www-form-urlencoded 684 type=web_server&code=i1WsRn1uB1& 685 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 687 4. Establishing Resource Owner Authorization 689 Before the client can obtain an access token, it must first attain 690 authorization from the resource owner. The methods through which the 691 client attains authorization are codified in the various 692 authorization flows defined in Section 5, and depends on the client 693 type and its trust relationship with the resource owner. 695 Resource owner authorization can be expressed in multiple ways: a 696 verification code obtained through direct interaction with an end- 697 user, the resource owner credentials (or the client credentials when 698 the client is also the resource owner) obtained through a trust 699 relationship with the resource owner, or an assertion obtained 700 through means beyond the scope of this specification. 702 4.1. Verification Code 704 When an end-user is involved, the client attains authorization in the 705 form of a verification code by sending the end-user to the 706 authorization server to review and grant the request. The client 707 sends the end-user by directing the end-user's user-agent to the 708 authorization server's end-user authorization endpoint. 710 4.1.1. End-User Authorization Endpoint 712 When directed to the end-user authorization endpoint, the end-user 713 first authenticates with the authorization server, and then grants or 714 denies the access request. The way in which the authorization server 715 authenticates the end-user (e.g. username and password login, OpenID, 716 session cookies) and in which the authorization server obtains the 717 end-user's authorization, including whether it uses a secure channel 718 such as TLS, is beyond the scope of this specification. However, the 719 authorization server MUST first verify the identity of the end-user. 721 The location of the end-user authorization endpoint can be found in 722 the service documentation, or can be obtained by using [[ OAuth 723 Discovery ]]. The end-user authorization endpoint URI MAY include a 724 query component as defined by [RFC3986] section 3, which must be 725 retained when adding additional query parameters. 727 Since requests to the end-user authorization endpoint result in user 728 authentication and the transmission of sensitive information, the 729 authorization server SHOULD require the use of a transport-layer 730 mechanism such as TLS when sending requests to the end-user 731 authorization endpoint. 733 In order to direct the end-user's user-agent to the authorization 734 server, the client constructs the request URI by adding the following 735 parameters to the end-user authorization endpoint URI query component 736 using the "application/x-www-form-urlencoded" format as defined by 737 [W3C.REC-html401-19991224]: 739 type 740 REQUIRED. The client type (user-agent or web server). 741 Determines how the authorization server delivers the 742 authorization response back to the client. The parameter value 743 MUST be set to "web_server" or "user_agent". 745 client_id 746 REQUIRED. The client identifier as described in Section 3. 748 redirect_uri 749 REQUIRED, unless a redirection URI has been established between 750 the client and authorization server via other means. An 751 absolute URI to which the authorization server will redirect 752 the user-agent to when the end-user authorization step is 753 completed. The authorization server SHOULD require the client 754 to pre-register their redirection URI. Authorization servers 755 MAY restrict the redirection URI to not include a query 756 component as defined by [RFC3986] section 3. 758 state 759 OPTIONAL. An opaque value used by the client to maintain state 760 between the request and callback. The authorization server 761 includes this value when redirecting the user-agent back to the 762 client. 764 scope 765 OPTIONAL. The scope of the access request expressed as a list 766 of space-delimited strings. The value of the "scope" parameter 767 is defined by the authorization server. If the value contains 768 multiple space-delimited strings, their order does not matter, 769 and each string adds an additional access range to the 770 requested scope. 772 The client directs the end-user to the constructed URI using an HTTP 773 redirection response, or by other means available to it via the end- 774 user's user-agent. The request MUST use the HTTP "GET" method. 776 For example, the client directs the end-user's user-agent to make the 777 following HTTPS request (line breaks are for display purposes only): 779 GET /authorize?type=web_server&client_id=s6BhdRkqt3&redirect_uri= 780 https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 781 Host: server.example.com 783 If the client has previously registered a redirection URI with the 784 authorization server, the authorization server MUST verify that the 785 redirection URI received matches the registered URI associated with 786 the client identifier. [[ provide guidance on how to perform matching 787 ]] 789 The authorization server authenticates the end-user and obtains an 790 authorization decision (by asking the end-user or by establishing 791 approval via other means). When a decision has been established, the 792 authorization server directs the end-user's user-agent to the 793 provided client redirection URI using an HTTP redirection response, 794 or by other means available to it via the end-user's user-agent. 796 4.1.1.1. Authorization Server Response 798 If the end-user grants the access request, the authorization server 799 issues an access token, a verification code, or both, and delivers 800 them to the client by adding the following parameters to the 801 redirection URI: 803 code 804 REQUIRED if the client type is "web_server", otherwise 805 OPTIONAL. The verification code generated by the authorization 806 server. The verification code SHOULD expire shortly after it 807 is issued and allowed for a single use. The verification code 808 is bound to the client identifier and redirection URI. 810 access_token 811 REQUIRED if the client type is "user_agent", otherwise MUST NOT 812 be included. The access token. 814 expires_in 815 OPTIONAL. The duration in seconds of the access token lifetime 816 if an access token is included. 818 state 819 REQUIRED if the "state" parameter was present in the client 820 authorization request. Set to the exact value received from 821 the client. 823 If the end-user denies the access request, the authorization server 824 informs the client by adding the following parameters to the 825 redirection URI: 827 error 828 REQUIRED. The parameter value MUST be set to "user_denied". 830 state 831 REQUIRED if the "state" parameter was present in the client 832 authorization request. Set to the exact value received from 833 the client. 835 The method in which the authorization server adds the parameter to 836 the redirection URI is determined by the client type provided by the 837 client in the authorization request using the "type" parameter. 839 If the client type is "web_server", the authorization server adds the 840 parameters to the redirection URI query component using the 841 "application/x-www-form-urlencoded" format as defined by 842 [W3C.REC-html401-19991224]. 844 For example, the authorization server redirects the end-user's user- 845 agent by sending the following HTTP response: 847 HTTP/1.1 302 Found 848 Location: https://client.example.com/cb?code=i1WsRn1uB1 850 If the client type is "user_agent", the authorization server adds the 851 parameters to the redirection URI fragment component using the 852 "application/x-www-form-urlencoded" format as defined by 853 [W3C.REC-html401-19991224]. [[ replace form-encoded with JSON? ]] 855 For example, the authorization server redirects the end-user's user- 856 agent by sending the following HTTP response: 858 HTTP/1.1 302 Found 859 Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600 861 4.2. Resource Owner Credentials 863 While OAuth seeks to eliminate the need for resource owners to share 864 their credentials with the client, possesion of the resource owner 865 credentials constitute an authorization grant (if supported by the 866 authorization server). Resource owner credentials should only be 867 used when there is a high degree of trust between the resource owner 868 the client. 870 In cases where the client is also the resource owner, the client 871 credentials can be used to obtain an access token provisioned for 872 accessing the client's protected resources. 874 4.3. Assertion 876 Assertions enable the client to utilize existing trust relationships 877 or different authorization constructs to obtain an access token. 878 They provide a bridge between OAuth and other trust frameworks. The 879 authorization grant represented by an assertion depends on the 880 assertion type, its content, and how it was issued, which are beyond 881 the scope of this specification. 883 5. Obtaining an Access Token 885 The client obtains an access token by authenticating with the 886 authorization server and presenting its authorization grant. 888 In many cases it is desirable to issue access tokens with a shorter 889 lifetime than the duration of the authorization grant. However, it 890 may be undesirable to require the resource owner to authorize the 891 request again. Instead, the authorization server issues a refresh 892 token in addition to the access token. When the access token 893 expires, the client can request a new access token without involving 894 the resource owner as long as the authorization grant is still valid. 895 The token refresh method is described in Section 5.1.4. 897 5.1. Token Endpoint 899 After obtaining authorization from the resource owner, clients 900 request an access token from the authorization server's token 901 endpoint. When requesting an access token, the client authenticates 902 with the authorization server and includes the authorization grant 903 (in the form of a verification code, resource owner credentials, an 904 assertion, or a refresh token). 906 The location of the token endpoint can be found in the service 907 documentation, or can be obtained by using [[ OAuth Discovery ]]. 908 The token endpoint URI MAY include a query component, which must be 909 retained when adding additional query parameters. 911 Since requests to the token endpoint result in the transmission of 912 plain text credentials in the HTTP request and response, the 913 authorization server MUST require the use of a transport-layer 914 mechanism when sending requests to the token endpoints. Servers MUST 915 support TLS 1.2 as defined in [RFC5246] and MAY support addition 916 mechanisms with equivalent protections. 918 The client obtains an access token by constructing a token request. 919 The client constructs the request URI by: 921 o Adding its client credentials to the request as described in 922 Section 3.1. For example, if the client uses a set of basic 923 client credentials, it adds the "client_id" and "client_secret" 924 parameters to the request (or uses the HTTP Basic authentication 925 scheme). 927 o Adding the authorization grand in the form of a verification code, 928 resource owner credentials, an assertion, or refresh token. If 929 the client is acting on behalf of itself (the client is also the 930 resource owner), no additional information is needed. The 931 authorization grant is added to the request URI query component 932 using the "application/x-www-form-urlencoded" format as described 933 below. 935 5.1.1. Verification Code 937 The client includes the verification code using following parameters: 939 code 940 REQUIRED. The verification code received from the 941 authorization server. 943 redirect_uri 944 REQUIRED. The redirection URI used in the initial request. 946 For example, the client makes the following HTTPS request (line 947 breaks are for display purposes only): 949 POST /token HTTP/1.1 950 Host: server.example.com 951 Content-Type: application/x-www-form-urlencoded 953 client_id=s6BhdRkqt3& 954 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 955 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 957 The authorization server MUST verify that the verification code, 958 client identity, client secret, and redirection URI are all valid and 959 match its stored association. If the request is valid, the 960 authorization server issues a successful response as described in 961 Section 5.1.5. 963 5.1.2. Resource Owner Credentials 965 The client includes the resource owner credentials using the 966 following parameters: [[ add internationalization consideration for 967 username and password ]] 969 username 970 REQUIRED. The end-user's username. 972 password 973 REQUIRED. The end-user's password. 975 scope 976 OPTIONAL. The scope of the access request expressed as a list 977 of space-delimited strings. The value of the "scope" parameter 978 is defined by the authorization server. If the value contains 979 multiple space-delimited strings, their order does not matter, 980 and each string adds an additional access range to the 981 requested scope. 983 For example, the client makes the following HTTPS request (line 984 breaks are for display purposes only): 986 POST /token HTTP/1.1 987 Host: server.example.com 988 Content-Type: application/x-www-form-urlencoded 990 client_id=s6BhdRkqt3&client_secret= 991 47HDu8s&username=johndoe&password=A3ddj3w 993 The authorization server MUST validate the client credentials and 994 end-user credentials and if valid issues an access token response as 995 described in Section 5.1.5. 997 If the client is acting on behalf of itself (the client is also the 998 resource owner), the client authentication alone suffice and the 999 "username" and "password" parameters MUST NOT be used. 1001 5.1.3. Assertion 1003 The client includes the assertion using the following parameters: 1005 assertion_type 1006 REQUIRED. The format of the assertion as defined by the 1007 authorization server. The value MUST be an absolute URI. 1009 assertion 1010 REQUIRED. The assertion. 1012 scope 1013 OPTIONAL. The scope of the access request expressed as a list 1014 of space-delimited strings. The value of the "scope" parameter 1015 is defined by the authorization server. If the value contains 1016 multiple space-delimited strings, their order does not matter, 1017 and each string adds an additional access range to the 1018 requested scope. 1020 For example, the client makes the following HTTPS request (line 1021 breaks are for display purposes only): 1023 POST /token HTTP/1.1 1024 Host: server.example.com 1025 Content-Type: application/x-www-form-urlencoded 1027 client_id=s6BhdRkqt3&client_secret=diejdsks& 1028 assertion_type=urn%3Aoasis%3Anames%sAtc%3ASAML%3A2.0%3Aassertion& 1029 assertion=PHNhbWxwOl...[ommited for brevity]...ZT4%3D 1031 The authorization server MUST validate the assertion and if valid 1032 issues an access token response as described in Section 5.1.5. The 1033 authorization server SHOULD NOT issue a refresh token. 1035 Authorization servers SHOULD issue access tokens with a limited 1036 lifetime and require clients to refresh them by requesting a new 1037 access token using the same assertion if it is still valid. 1038 Otherwise the client MUST obtain a new valid assertion. 1040 5.1.4. Refresh Token 1042 Token refresh is used when the lifetime of an access token is shorter 1043 than the lifetime of the authorization grant. It enables the client 1044 to obtain a new access token without having to go through the 1045 authorization flow again or involve the resource owner. 1047 The client includes the refresh token using the following parameters: 1049 refresh_token 1050 REQUIRED. The refresh token associated with the access token 1051 to be refreshed. 1053 For example, the client makes the following HTTPS request (line break 1054 are for display purposes only): 1056 POST /token HTTP/1.1 1057 Host: server.example.com 1058 Content-Type: application/x-www-form-urlencoded 1060 client_id=s6BhdRkqt3&client_secret=8eSEIpnqmM 1061 &refresh_token=n4E9O119d 1063 The authorization server MUST verify the client credentials, the 1064 validity of the refresh token, and that the resource owner's 1065 authorization is still valid. If the request is valid, the 1066 authorization server issues an access token response as described in 1067 Section 5.1.5. The authorization server MAY issue a new refresh 1068 token in which case the client MUST NOT use the previous refresh 1069 token and replace it with the newly issued refresh token. 1071 5.1.5. Access Token Response 1073 After receiving and verifying a valid and authorized access token 1074 request from the client, the authorization server issues the access 1075 token and optional refresh token, and constructs the response by 1076 adding the following parameters to the entity body of the HTTP 1077 response with a 200 status code (OK): 1079 The token response contains the following parameters: 1081 access_token 1082 REQUIRED. The access token issued by the authorization server. 1084 expires_in 1085 OPTIONAL. The duration in seconds of the access token 1086 lifetime. 1088 refresh_token 1089 OPTIONAL. The refresh token used to obtain new access tokens 1090 using the same end-user access grant as described in 1091 Section 5.1.4. 1093 scope 1094 OPTIONAL. The scope of the access token as a list of space- 1095 delimited strings. The value of the "scope" parameter is 1096 defined by the authorization server. If the value contains 1097 multiple space-delimited strings, their order does not matter, 1098 and each string adds an additional access range to the 1099 requested scope. 1101 The parameters are including in the entity body of the HTTP response 1102 using the "application/json" media type as defined by [RFC4627]. The 1103 parameters are serialized into a JSON structure by adding each 1104 parameter at the highest structure level. Parameter names and string 1105 values are included as JSON strings. Numerical values are included 1106 as JSON numbers. 1108 The authorization server MUST include the HTTP "Cache-Control" 1109 response header field with a value of "no-store" in any response 1110 containing tokens, secrets, or other sensitive information. 1112 For example: 1114 HTTP/1.1 200 OK 1115 Content-Type: application/json 1116 Cache-Control: no-store 1118 { 1119 "access_token":"SlAV32hkKG", 1120 "expires_in":3600, 1121 "refresh_token":"8xLOxBtZp8" 1122 } 1124 5.1.6. Error Response 1126 If the token request is invalid or unauthorized, the authorization 1127 server constructs the response by adding the following parameter to 1128 the entity body of the HTTP response with a a 400 status code (Bad 1129 Request) using the "application/json" media type: 1131 error 1132 REQUIRED. The error code as described in Section 5.1.6.1. 1134 For example: 1136 HTTP/1.1 400 Bad Request 1137 Content-Type: application/json 1138 Cache-Control: no-store 1140 { 1141 "error":"incorrect_client_credentials" 1142 } 1144 5.1.6.1. Error Codes 1146 [[ expalain each error code: ]] 1148 o "redirect_uri_mismatch" 1150 o "bad_verification_code" 1152 o "incorrect_client_credentials" 1154 o "unauthorized_client'" - The client is not permitted to use this 1155 authorization grant type. 1157 o "invalid_assertion" 1159 o "unknown_format" 1161 o "authorization_expired" 1163 6. Accessing a Protected Resource 1165 Clients access protected resources by presenting an access token to 1166 the resource server. 1168 For example: 1170 GET /resource HTTP/1.1 1171 Host: server.example.com 1172 Authorization: Token token="vF9dft4qmT" 1174 Access tokens act as bearer tokens, where the token string acts as a 1175 shared symmetric secret. This requires treating the access token 1176 with the same care as other secrets (e.g. end-user passwords). 1177 Access tokens SHOULD NOT be sent in the clear over an insecure 1178 channel. 1180 However, when it is necessary to transmit bearer tokens in the clear 1181 without a secure channel, authorization servers SHOULD issue access 1182 tokens with limited scope and lifetime to reduce the potential risk 1183 from a compromised access token. 1185 Clients SHOULD NOT make authenticated requests with an access token 1186 to unfamiliar resource servers, especially when using bearer tokens, 1187 regardless of the presence of a secure channel. 1189 The methods used by the resource server to validate the access token 1190 are beyond the scope of this specification, but generally involve an 1191 interaction or coordination between the resource server and 1192 authorization server. 1194 The resource server MUST validate the access token and ensure it has 1195 not expired and that its scope covers the requested resource. If the 1196 token expired or is invalid, the resource server MUST reply with an 1197 HTTP 401 status code (Unauthorized) and include the HTTP 1198 "WWW-Authenticate" response header as described in Section 7.1. 1200 For example: 1202 HTTP/1.1 401 Unauthorized 1203 WWW-Authenticate: Token realm='Service', error='token_expired' 1205 Clients make authenticated token requests using the "Authorization" 1206 request header field as described in Section 6.1. Alternatively, 1207 clients MAY include the access token using the HTTP request URI in 1208 the query component as described in Section 6.2, or in the HTTP body 1209 when using the "application/x-www-form-urlencoded" content type as 1210 described in Section 6.3. 1212 Clients SHOULD only use the request URI or body when the 1213 "Authorization" request header field is not available, and MUST NOT 1214 use more than one method in each request. [[ specify error ]] 1216 6.1. The Authorization Request Header 1218 The "Authorization" request header field is used by clients to make 1219 authenticated token requests. The client uses the "token" attribute 1220 to include the access token in the request. 1222 The "Authorization" header field uses the framework defined by 1223 [RFC2617] as follows: 1225 credentials = "Token" RWS access-token [ CS 1#auth-param ] 1226 access-token = "token" "=" <"> token <"> 1227 CS = OWS "," OWS 1229 6.2. URI Query Parameter 1231 When including the access token in the HTTP request URI, the client 1232 adds the access token to the request URI query component as defined 1233 by [RFC3986] using the "oauth_token" parameter. 1235 For example, the client makes the following HTTPS request: 1237 GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 1238 Host: server.example.com 1240 The HTTP request URI query can include other request-specific 1241 parameters, in which case, the "oauth_token" parameters SHOULD be 1242 appended following the request-specific parameters, properly 1243 separated by an "&" character (ASCII code 38). 1245 The resource server MUST validate the access token and ensure it has 1246 not expired and its scope includes the requested resource. If the 1247 resource expired or is not valid, the resource server MUST reply with 1248 an HTTP 401 status code (Unauthorized) and include the HTTP 1249 "WWW-Authenticate" response header as described in Section 7.1. 1251 6.3. Form-Encoded Body Parameter 1253 When including the access token in the HTTP request entity-body, the 1254 client adds the access token to the request body using the 1255 "oauth_token" parameter. The client can use this method only if the 1256 following REQUIRED conditions are met: 1258 o The entity-body is single-part. 1260 o The entity-body follows the encoding requirements of the 1261 "application/x-www-form-urlencoded" content-type as defined by 1262 [W3C.REC-html401-19991224]. 1264 o The HTTP request entity-header includes the "Content-Type" header 1265 field set to "application/x-www-form-urlencoded". 1267 o The HTTP request method is "POST", "PUT", or "DELETE". 1269 The entity-body can include other request-specific parameters, in 1270 which case, the "oauth_token" parameters SHOULD be appended following 1271 the request-specific parameters, properly separated by an "&" 1272 character (ASCII code 38). 1274 For example, the client makes the following HTTPS request: 1276 POST /resource HTTP/1.1 1277 Host: server.example.com 1278 Content-Type: application/x-www-form-urlencoded 1279 oauth_token=vF9dft4qmT 1281 The resource server MUST validate the access token and ensure it has 1282 not expired and its scope includes the requested resource. If the 1283 resource expired or is not valid, the resource server MUST reply with 1284 an HTTP 401 status code (Unauthorized) and include the HTTP 1285 "WWW-Authenticate" response header as described in Section 7.1. 1287 7. Identifying a Protected Resource 1289 Clients access protected resources after locating the appropriate 1290 end-user authorization endpoint and token endpoint and obtaining an 1291 access token. In many cases, interacting with a protected resource 1292 requires prior knowledge of the protected resource properties and 1293 methods, as well as its authentication requirements (i.e. 1294 establishing client identity, locating the end-user authorization and 1295 token endpoints). 1297 However, there are cases in which clients are unfamiliar with the 1298 protected resource, including whether the resource requires 1299 authentication. When clients attempt to access an unfamiliar 1300 protected resource without an access token, the resource server 1301 denies the request and informs the client of the required credentials 1302 using an HTTP authentication challenge. 1304 In addition, when receiving an invalid authenticated request, the 1305 resource server issues an authentication challenge including the 1306 error type and message. 1308 7.1. The WWW-Authenticate Response Header 1310 A resource server receiving a request for a protected resource 1311 without a valid access token MUST respond with a 401 (Unauthorized) 1312 or 403 (Forbidden) HTTP status code, and include at least one "Token" 1313 "WWW-Authenticate" response header field challenge. 1315 The "WWW-Authenticate" header field uses the framework defined by 1316 [RFC2617] as follows: 1318 challenge = "Token" RWS token-challenge 1320 token-challenge = realm 1321 [ CS error ] 1322 [ CS 1#auth-param ] 1324 error = "error" "=" <"> token <"> 1326 The "realm" attribute is used to provide the protected resources 1327 partition as defined by [RFC2617]. 1329 The "error" attribute is used to inform the client the reason why an 1330 access request was declined. [[ Add list of error codes ]] 1332 8. Security Considerations 1334 [[ Todo ]] 1336 9. IANA Considerations 1338 [[ Not Yet ]] 1340 Appendix A. Contributors 1342 The following people contributed to preliminary versions of this 1343 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland 1344 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 1345 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 1346 concepts within are a product of the OAuth community, WRAP community, 1347 and the OAuth Working Group. 1349 The OAuth Working Group has dozens of very active contributors who 1350 proposed ideas and wording for this document, including: [[ If your 1351 name is missing or you think someone should be added here, please 1352 send Eran a note - don't be shy ]] 1354 Michael Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah 1355 Culver, Igor Faynberg, George Fletcher, Evan Gilbert, Justin Hart, 1356 John Kemp, Torsten Lodderstedt, Eve Maler, James Manger, Chuck 1357 Mortimore, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, 1358 Marius Scurtescu, Justin Smith, and Franklin Tse. 1360 Appendix B. Acknowledgements 1362 [[ Add OAuth 1.0a authors + WG contributors ]] 1364 Appendix C. Document History 1366 [[ to be removed by RFC editor before publication as an RFC ]] 1368 -07 1370 o Major rewrite of entire document structure. 1372 o Removed device profile. 1374 o Added verification code support to user-agent flow. 1376 o Removed multiple formats support, leaving JSON as the only format. 1378 o Changed assertion "assertion_format" parameter to 1379 "assertion_type". 1381 o Removed "type" parameter from token endpoint. 1383 -06 1385 o Editorial changes, corrections, clarifications, etc. 1387 o Removed conformance section. 1389 o Moved authors section to contributors appendix. 1391 o Added section on native applications. 1393 o Changed error response to use the requested format. Added support 1394 for HTTP "Accept" header. 1396 o Flipped the order of the web server and user-agent flows. 1398 o Renamed assertion flow "format" parameter name to 1399 "assertion_format" to resolve conflict. 1401 o Removed the term identifier from token definitions. Added a 1402 cryptographic token definition. 1404 o Added figure titles. 1406 o Added server response 401 when client tried to authenticate using 1407 multiple credentials. 1409 o Clarified support for TLS alternatives, and added requirement for 1410 TLS 1.2 support for token endpoint. 1412 o Removed all signature and cryptography. 1414 o Removed all discovery. 1416 o Updated HTML4 reference. 1418 -05 1420 o Corrected device example. 1422 o Added client credentials parameters to the assertion flow as 1423 OPTIONAL. 1425 o Added the ability to send client credentials using an HTTP 1426 authentication scheme. 1428 o Initial text for the "WWW-Authenticate" header (also added scope 1429 support). 1431 o Change authorization endpoint to end-user endpoint. 1433 o In the device flow, change the "user_uri" parameter to 1434 "verification_uri" to avoid confusion with the end-user endpoint. 1436 o Add "format" request parameter and support for XML and form- 1437 encoded responses. 1439 -04 1441 o Changed all token endpoints to use "POST" 1443 o Clarified the authorization server's ability to issue a new 1444 refresh token when refreshing a token. 1446 o Changed the flow categories to clarify the autonomous group. 1448 o Changed client credentials language not to always be server- 1449 issued. 1451 o Added a "scope" response parameter. 1453 o Fixed typos. 1455 o Fixed broken document structure. 1457 -03 1458 o Fixed typo in JSON error examples. 1460 o Fixed general typos. 1462 o Moved all flows sections up one level. 1464 -02 1466 o Removed restriction on "redirect_uri" including a query. 1468 o Added "scope" parameter. 1470 o Initial proposal for a JSON-based token response format. 1472 -01 1474 o Editorial changes based on feedback from Brian Eaton, Bill Keenan, 1475 and Chuck Mortimore. 1477 o Changed device flow "type" parameter values and switch to use only 1478 the token endpoint. 1480 -00 1482 o Initial draft based on a combination of WRAP and OAuth 1.0a. 1484 10. References 1486 10.1. Normative References 1488 [I-D.ietf-httpbis-p1-messaging] 1489 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1490 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1491 "HTTP/1.1, part 1: URIs, Connections, and Message 1492 Parsing", draft-ietf-httpbis-p1-messaging-09 (work in 1493 progress), March 2010. 1495 [NIST FIPS-180-3] 1496 National Institute of Standards and Technology, "Secure 1497 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1499 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1500 Extensions (MIME) Part One: Format of Internet Message 1501 Bodies", RFC 2045, November 1996. 1503 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1504 Hashing for Message Authentication", RFC 2104, 1505 February 1997. 1507 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1508 Requirement Levels", BCP 14, RFC 2119, March 1997. 1510 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1511 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1512 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1514 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1515 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1516 Authentication: Basic and Digest Access Authentication", 1517 RFC 2617, June 1999. 1519 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1521 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1522 Types", RFC 3023, January 2001. 1524 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1525 Standards (PKCS) #1: RSA Cryptography Specifications 1526 Version 2.1", RFC 3447, February 2003. 1528 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1529 10646", STD 63, RFC 3629, November 2003. 1531 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1532 Resource Identifier (URI): Generic Syntax", STD 66, 1533 RFC 3986, January 2005. 1535 [RFC4627] Crockford, D., "The application/json Media Type for 1536 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1538 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1539 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1541 [W3C.REC-html401-19991224] 1542 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 1543 Specification", World Wide Web Consortium 1544 Recommendation REC-html401-19991224, December 1999, 1545 . 1547 10.2. Informative References 1549 [I-D.hammer-oauth] 1550 Hammer-Lahav, E., "The OAuth 1.0 Protocol", 1551 draft-hammer-oauth-10 (work in progress), February 2010. 1553 [I-D.hardt-oauth] 1554 Hardt, D., Tom, A., Eaton, B., and Y. Goland, "OAuth Web 1555 Resource Authorization Profiles", draft-hardt-oauth-01 1556 (work in progress), January 2010. 1558 [OASIS.saml-core-2.0-os] 1559 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1560 "Assertions and Protocol for the OASIS Security Assertion 1561 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1562 2.0-os, March 2005. 1564 Authors' Addresses 1566 Eran Hammer-Lahav (editor) 1567 Yahoo! 1569 Email: eran@hueniverse.com 1570 URI: http://hueniverse.com 1572 David Recordon 1573 Facebook 1575 Email: davidrecordon@facebook.com 1576 URI: http://www.davidrecordon.com/ 1578 Dick Hardt 1579 Microsoft 1581 Email: dick.hardt@gmail.com 1582 URI: http://dickhardt.org/