idnits 2.17.1 draft-ietf-oauth-v2-10.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC5849, but the abstract doesn't seem to mention this, which it should. 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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: If the request lacks any authentication information (i.e. the client was unaware authentication is necessary or attempted using an unsupported authentication method), the resource server SHOULD not include an error code or other error information. -- The document date (July 11, 2010) is 5032 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 1838, but no explicit reference was found in the text == Unused Reference: 'RFC2045' is defined on line 1842, but no explicit reference was found in the text == Unused Reference: 'RFC2104' is defined on line 1846, but no explicit reference was found in the text == Unused Reference: 'RFC3023' is defined on line 1864, but no explicit reference was found in the text == Unused Reference: 'RFC3447' is defined on line 1867, but no explicit reference was found in the text == Unused Reference: 'RFC3629' is defined on line 1871, but no explicit reference was found in the text == Unused Reference: 'I-D.hammer-oauth' is defined on line 1899, but no explicit reference was found in the text == Unused Reference: 'I-D.hardt-oauth' is defined on line 1903, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-09 -- 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) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** 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 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5849 (Obsoleted by RFC 6749) Summary: 10 errors (**), 0 flaws (~~), 12 warnings (==), 4 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 Obsoletes: 5849 (if approved) D. Recordon 5 Intended status: Standards Track Facebook 6 Expires: January 12, 2011 D. Hardt 7 Microsoft 8 July 11, 2010 10 The OAuth 2.0 Protocol 11 draft-ietf-oauth-v2-10 13 Abstract 15 This specification describes the OAuth 2.0 protocol. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 12, 2011. 34 Copyright Notice 36 Copyright (c) 2010 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 7 55 1.4. Client Profiles . . . . . . . . . . . . . . . . . . . . . 10 56 1.4.1. Web Server . . . . . . . . . . . . . . . . . . . . . . 10 57 1.4.2. User-Agent . . . . . . . . . . . . . . . . . . . . . . 11 58 1.4.3. Native Application . . . . . . . . . . . . . . . . . . 13 59 1.4.4. Autonomous . . . . . . . . . . . . . . . . . . . . . . 14 60 2. Client Credentials . . . . . . . . . . . . . . . . . . . . . . 14 61 2.1. Client Password Credentials . . . . . . . . . . . . . . . 15 62 3. Obtaining End-User Authorization . . . . . . . . . . . . . . . 16 63 3.1. Authorization Response . . . . . . . . . . . . . . . . . . 18 64 3.2. Error Response . . . . . . . . . . . . . . . . . . . . . . 20 65 3.2.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 21 66 4. Obtaining an Access Token . . . . . . . . . . . . . . . . . . 21 67 4.1. Access Grant Types . . . . . . . . . . . . . . . . . . . . 23 68 4.1.1. Authorization Code . . . . . . . . . . . . . . . . . . 23 69 4.1.2. Resource Owner Password Credentials . . . . . . . . . 24 70 4.1.3. Assertion . . . . . . . . . . . . . . . . . . . . . . 24 71 4.1.4. Refresh Token . . . . . . . . . . . . . . . . . . . . 25 72 4.2. Access Token Response . . . . . . . . . . . . . . . . . . 26 73 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 27 74 4.3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 28 75 5. Accessing a Protected Resource . . . . . . . . . . . . . . . . 29 76 5.1. Authenticated Requests . . . . . . . . . . . . . . . . . . 29 77 5.1.1. The Authorization Request Header Field . . . . . . . . 30 78 5.1.2. URI Query Parameter . . . . . . . . . . . . . . . . . 30 79 5.1.3. Form-Encoded Body Parameter . . . . . . . . . . . . . 31 80 5.2. The WWW-Authenticate Response Header Field . . . . . . . . 32 81 5.2.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 33 82 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 34 83 6.1. Defining New Client Credentials Types . . . . . . . . . . 34 84 6.2. Defining New Endpoint Parameters . . . . . . . . . . . . . 34 85 6.3. Defining New Header Field Parameters . . . . . . . . . . . 35 86 6.4. Defining New Access Grant Types . . . . . . . . . . . . . 35 87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 89 8.1. The OAuth Parameters Registry . . . . . . . . . . . . . . 35 90 8.1.1. Registration Template . . . . . . . . . . . . . . . . 36 91 8.1.2. Example . . . . . . . . . . . . . . . . . . . . . . . 36 92 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 37 93 Appendix B. Contributors . . . . . . . . . . . . . . . . . . . . 37 94 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 37 95 Appendix D. Document History . . . . . . . . . . . . . . . . . . 38 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 97 9.1. Normative References . . . . . . . . . . . . . . . . . . . 42 98 9.2. Informative References . . . . . . . . . . . . . . . . . . 43 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 43 101 1. Introduction 103 With the increasing use of distributed web services and cloud 104 computing, third-party applications require access to server-hosted 105 resources. These resources are usually protected and require 106 authentication using the resource owner's credentials (typically a 107 username and password). 109 In the traditional client-server authentication model, the client 110 accesses a protected resource on the server by authenticating with 111 the server using the resource owner's credentials. In order to 112 provide third-party applications access to protected resources, the 113 resource owner shares its credentials with the third-party. This 114 creates several problems and limitations: 116 o Third-party applications are required to store the resource- 117 owner's credentials for future use, typically a password in clear- 118 text. 120 o Servers are required to support password (symmetric) 121 authentication, despite the security weaknesses created by 122 passwords. 124 o Third-party applications gain overly broad access to the resource- 125 owner's protected resources, leaving resource owners without any 126 ability to restrict access to a limited subset of resources, to 127 limit access duration, or to limit access to the methods supported 128 by these resources. 130 o Resource owners cannot revoke access to an individual third-party 131 without revoking access to all third-parties, and must do so by 132 changing their password. 134 OAuth address these issues by separating the role of the client from 135 that of the resource owner. In OAuth, the client (which is usually 136 not the resource owner, but is acting on the resource owner's behalf) 137 requests access to resources controlled by the resource owner and 138 hosted by the resource server, and is issued a different set of 139 credentials than those of the resource owner. 141 Instead of using the resource owner's credentials to access protected 142 resources, clients obtain an access token (a string which denotes a 143 specific scope, duration, and other attributes). The format and 144 structure of access tokens is beyond the scope of this specification. 146 Tokens are issued to third-party clients by an authorization server 147 with the approval of the resource owner. The client uses the access 148 token to access the protected resources hosted by the resource 149 server. The interaction between the authorization server and 150 resource server is beyond the scope of this specification. 152 For example, a web user (resource owner) can grant a printing service 153 (client) access to her protected photos stored at a photo sharing 154 service (resource server), without sharing her username and password 155 with the printing service. Instead, she authenticates directly with 156 an authentication service trusted by the photo sharing service 157 (authorization server) which issues the printing service delegation- 158 specific credentials (token). 160 This specification defines the use of OAuth over HTTP [RFC2616] (or 161 HTTP over TLS as defined by [RFC2818]). Other specifications may 162 extend it for use with other transport protocols. 164 1.1. Notational Conventions 166 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 167 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 168 document are to be interpreted as described in [RFC2119]. 170 This document uses the Augmented Backus-Naur Form (ABNF) notation of 171 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 172 are included from [RFC2617]: realm, auth-param; from [RFC3986]: URI- 173 Reference; and from [I-D.ietf-httpbis-p1-messaging]: OWS, RWS, and 174 quoted-string. 176 Unless otherwise noted, all the protocol parameter names and values 177 are case sensitive. 179 1.2. Terminology 181 protected resource 182 An access-restricted resource which can be obtained using an 183 OAuth-authenticated request. 185 resource server 186 A server capable of accepting and responding to protected 187 resource requests. 189 client 190 An application obtaining authorization and making protected 191 resource requests. 193 resource owner 194 An entity capable of granting access to a protected resource. 196 end-user 197 A human resource owner. 199 token 200 A string representing an access authorization issued to the 201 client. The string is usually opaque to the client. Tokens 202 represent specific scopes and durations of access, granted by 203 the resource owner, and enforced by the resource server and 204 authorization servers. The token may denote an identifier used 205 to retrieve the authorization information, or self-contain the 206 authorization information in a verifiable manner (i.e. a token 207 string consisting of some data and a signature). Tokens may be 208 pure capabilities. Specific additional authentication 209 credentials may be required in order for a client to use a 210 token. 212 access token 213 A token used by the client to make authenticated requests on 214 behalf of the resource owner. 216 refresh token 217 A token used by the client to obtain a new access token without 218 having to involve the resource owner. 220 authorization code A short-lived token representing the access grant 221 provided by the end-user. The authorization code is used to 222 obtain an access token and a refresh token. 224 authorization server 225 A server capable of issuing tokens after successfully 226 authenticating the resource owner and obtaining authorization. 227 The authorization server may be the same server as the resource 228 server, or a separate entity. 230 end-user authorization endpoint 231 The authorization server's HTTP endpoint capable of 232 authenticating the end-user and obtaining authorization. The 233 end-user authorization endpoint is described in Section 3. 235 token endpoint 236 The authorization server's HTTP endpoint capable of issuing 237 tokens and refreshing expired tokens. The token endpoint is 238 described in Section 4. 240 client identifier 241 A unique identifier issued to the client to identify itself to 242 the authorization server. Client identifiers may have a 243 matching secret. The client identifier is described in 244 Section 2. 246 1.3. Overview 248 OAuth provides a method for clients to access a protected resource on 249 behalf of a resource owner. Before a client can access a protected 250 resource, it must first obtain authorization from the resource owner, 251 then exchange the access grant for an access token (representing the 252 grant's scope, duration, and other attributes). The client accesses 253 the protected resource by presenting the access token to the resource 254 server. 256 +--------+ +---------------+ 257 | |--(A)-- Authorization Request --->| Resource | 258 | | | Owner | 259 | |<-(B)------ Access Grant ---------| | 260 | | +---------------+ 261 | | 262 | | Client Credentials & +---------------+ 263 | |--(C)------ Access Grant -------->| Authorization | 264 | Client | | Server | 265 | |<-(D)------ Access Token ---------| | 266 | | (w/ Optional Refresh Token) +---------------+ 267 | | 268 | | +---------------+ 269 | |--(E)------ Access Token -------->| Resource | 270 | | | Server | 271 | |<-(F)---- Protected Resource -----| | 272 +--------+ +---------------+ 274 Figure 1: Abstract Protocol Flow 276 The abstract flow illustrated in Figure 1 includes the following 277 steps: 279 (A) The client requests authorization from the resource owner. The 280 client should not request the resource owner's credentials 281 directly. Instead, it should request authorization via an 282 authorization server or other entities. For example, the client 283 directs the resource owner to the authorization server which in 284 turn issues it an access grant. When unavoidable, the client 285 interacts directly with the end-user, asking for the end-user's 286 username and password. If the client is acting autonomously, 287 the authorization request is beyond the scope of this 288 specification. 290 (B) The client is issued an access grant which represents the 291 authorization provided by the resource owner. The access grant 292 can be expressed as: 294 * Authorization code - an access grant obtained via an 295 authorization server. Section 3 describes how to obtain an 296 authorization code when the end-user is present and using a 297 user-agent. 299 * Assertion - an access grant obtained using a different trust 300 framework. Assertions enable the client to utilize existing 301 trust relationships to obtain an access token. They provide 302 a bridge between OAuth and other trust frameworks. The 303 access grant represented by an assertion depends on the 304 assertion type, its content, and how it was issued, which are 305 beyond the scope of this specification. 307 * Resource owner password credentials - obtained when 308 interacting directly with a resource-owner. Resource owner 309 password credentials (i.e. a username and password) should 310 only be used when there is a high degree of trust between the 311 resource owner and the client (e.g. its computer operating 312 system or a highly privileged application). However, unlike 313 the HTTP Basic authentication scheme defined in [RFC2617], 314 the resource owner's credentials are used for a single 315 request and are exchanged for an access token and refresh 316 token. This eliminates the need for the client to store the 317 resource-owner's credentials for future use. 319 (C) The client requests an access token by authenticating with the 320 authorization server, and presenting the access grant. The 321 token request is described in Section 4. 323 (D) The authorization server validates the client credentials and 324 the access grant, and issues an access token with an optional 325 refresh token. Access tokens usually have a shorter lifetime 326 than the access grant. Refresh tokens usually have a lifetime 327 equal to the duration of the access grant. When an access token 328 expires, the refresh token is used to obtain a new access token 329 without having to request another access grant from the resource 330 owner. 332 (E) The client makes a protected resource request to the resource 333 server, and presents the access token in order to gain access. 334 Accessing a protected resource is described in Section 5. 336 (F) The resource server validates the access token, and if valid, 337 serves the request. 339 When the client is acting on its own behalf (the client is also the 340 resource owner), the client does not obtain an access grant. The 341 simplified protocol flow is illustrated in Figure 2: 343 +--------+ +---------------+ 344 | |--(C)--- Client Credentials ----->| Authorization | 345 | | | Server | 346 | |<-(D)------ Access Token ---------| | 347 | | +---------------+ 348 | Client | 349 | | +---------------+ 350 | |--(E)------ Access Token -------->| Resource | 351 | | | Server | 352 | |<-(F)---- Protected Resource -----| | 353 +--------+ +---------------+ 355 Figure 2: Protocol Flow for Client Acting On Its Own Behalf 357 When the client uses the user-agent profile (described in 358 Section 1.4.2), the authorization request results in an access token, 359 as illustrated in Figure 3: 361 +--------+ +----------+ +---------------+ 362 | |--(A)-- Authorization --+- -+-->| | 363 | | Request | Resource | | Authorization | 364 | | | Owner | | Server | 365 | |<-(D)-- Access Token ---+- -+---| | 366 | | +----------+ +---------------+ 367 | Client | 368 | | +---------------+ 369 | |--(E)-------- Access Token ----------->| Resource | 370 | | | Server | 371 | |<-(F)------ Protected Resource --------| | 372 +--------+ +---------------+ 374 Figure 3: Indirect Access Grant Protocol Flow 376 1.4. Client Profiles 378 OAuth supports a wide range of client types by providing a rich and 379 extensible framework for establishing authorization and exchanging it 380 for an access token. The methods detailed in this specification were 381 designed to accommodate four client types: web servers, user-agents, 382 native applications, and autonomous clients. Additional 383 authorization flows and client profiles may be defined by other 384 specifications to cover additional scenarios and client types. 386 1.4.1. Web Server 388 The web server profile is suitable for clients capable of interacting 389 with the end-user's user-agent (typically a web browser) and capable 390 of receiving incoming requests from the authorization server (capable 391 of acting as an HTTP server). 393 +----------+ Client Identifier +---------------+ 394 | -+----(A)--- & Redirect URI ------>| | 395 | End-user | | Authorization | 396 | at |<---(B)-- User authenticates --->| Server | 397 | Browser | | | 398 | -+----(C)-- Authorization Code ---<| | 399 +-|----|---+ +---------------+ 400 | | ^ v 401 (A) (C) | | 402 | | | | 403 ^ v | | 404 +---------+ | | 405 | |>---(D)-- Client Credentials, --------' | 406 | Web | Authorization Code, | 407 | Client | & Redirect URI | 408 | | | 409 | |<---(E)----- Access Token -------------------' 410 +---------+ (w/ Optional Refresh Token) 412 Figure 4: Web Server Flow 414 The web server flow illustrated in Figure 4 includes the following 415 steps: 417 (A) The web client initiates the flow by redirecting the end-user's 418 user-agent to the end-user authorization endpoint as described 419 in Section 3. The client includes its client identifier, 420 requested scope, local state, and a redirect URI to which the 421 authorization server will send the end-user back once access is 422 granted (or denied). 424 (B) The authorization server authenticates the end-user (via the 425 user-agent) and establishes whether the end-user grants or 426 denies the client's access request. 428 (C) Assuming the end-user granted access, the authorization server 429 redirects the user-agent back to the client to the redirection 430 URI provided earlier. The authorization includes an 431 authorization code for the client to use to obtain an access 432 token. 434 (D) The client requests an access token from the authorization 435 server by authenticating and including the authorization code 436 received in the previous step as described in Section 4. 438 (E) The authorization server validates the client credentials and 439 the authorization code and responds back with the access token. 441 1.4.2. User-Agent 443 The user-agent profile is suitable for client applications residing 444 in a user-agent, typically implemented in a browser using a scripting 445 language such as JavaScript. These clients cannot keep client 446 secrets confidential and the authentication of the client is based on 447 the user-agent's same-origin policy. 449 Unlike other profiles in which the client makes separate requests for 450 end-user authorization and access token, the client receives the 451 access token as a result of the end-user authorization request in the 452 form of an HTTP redirection. The client requests the authorization 453 server to redirect the user-agent to another web server or local 454 resource accessible to the user-agent which is capable of extracting 455 the access token from the response and passing it to the client. 457 This user-agent profile does not utilize the client secret since the 458 client executables reside on the end-user's computer or device which 459 makes the client secret accessible and exploitable. Because the 460 access token is encoded into the redirection URI, it may be exposed 461 to the end-user and other applications residing on the computer or 462 device. 464 +----------+ Client Identifier +----------------+ 465 | |>---(A)-- & Redirection URI --->| | 466 | | | | 467 End <--+ - - - +----(B)-- User authenticates -->| Authorization | 468 User | | | Server | 469 | |<---(C)--- Redirect URI -------<| | 470 | Client | with Access Token | | 471 | in | in Fragment +----------------+ 472 | Browser | 473 | | +----------------+ 474 | |>---(D)--- Redirect URI ------->| | 475 | | without Fragment | Web Server | 476 | | | with Client | 477 | (F) |<---(E)--- Web Page with ------<| Resource | 478 | Access | Script | | 479 | Token | +----------------+ 480 +----------+ 482 Figure 5: User-Agent Flow 484 The user-agent flow illustrated in Figure 5 includes the following 485 steps: 487 (A) The client sends the user-agent to the end-user authorization 488 endpoint as described in Section 3. The client includes its 489 client identifier, requested scope, local state, and a redirect 490 URI to which the authorization server will send the end-user 491 back once authorization is granted (or denied). 493 (B) The authorization server authenticates the end-user (via the 494 user-agent) and establishes whether the end-user grants or 495 denies the client's access request. 497 (C) If the end-user granted access, the authorization server 498 redirects the user-agent to the redirection URI provided 499 earlier. The redirection URI includes the access token in the 500 URI fragment. 502 (D) The user-agent follows the redirection instructions by making a 503 request to the web server which does not include the fragment. 504 The user-agent retains the fragment information locally. 506 (E) The web server returns a web page (typically an HTML page with 507 an embedded script) capable of accessing the full redirection 508 URI including the fragment retained by the user-agent, and 509 extracting the access token (and other parameters) contained in 510 the fragment. 512 (F) The user-agent executes the script provided by the web server 513 locally, which extracts the access token and passes it to the 514 client. 516 1.4.3. Native Application 518 Native application are clients running as native code on the end- 519 user's computer or device (i.e. executing outside a user-agent or as 520 a desktop program). These clients are often capable of interacting 521 with (or embedding) the end-user's user-agent but are limited in how 522 such interaction affects their end-user experience. In many cases, 523 native applications are incapable of receiving direct callback 524 requests from the server (e.g. firewall, operating system 525 restrictions). 527 Native application clients can be implemented in different ways based 528 on their requirements and desired end-user experience. Native 529 application clients can: 531 o Utilize the end-user authorization endpoint as described in 532 Section 3 by launching an external user-agent. The client can 533 capture the response by providing a redirection URI with a custom 534 URI scheme (registered with the operating system to invoke the 535 client application), or by providing a redirection URI pointing to 536 a server-hosted resource under the client's control which makes 537 the response available to the client (e.g. using the window title 538 or other locations accessible from outside the user-agent). 540 o Utilize the end-user authorization endpoint as described in 541 Section 3 by using an embedded user-agent. The client obtains the 542 response by directly communicating with the embedded user-agent. 544 o Prompt end-users for their password and use them directly to 545 obtain an access token. This is generally discouraged, as it 546 hands the end-user's password directly to the third-party client 547 which in turn has to store it in clear-text. It also requires the 548 server to support password-based authentication. 550 When choosing between launching an external browser and an embedded 551 user-agent, developers should consider the following: 553 o External user-agents may improve completion rate as the end-user 554 may already be logged-in and not have to re-authenticate. 556 o Embedded user-agents often offer a better end-user flow, as they 557 remove the need to switch context and open new windows. 559 o Embedded user-agents pose a security challenge because users are 560 authenticating in an unidentified window without access to the 561 visual protections offered by many user-agents. 563 1.4.4. Autonomous 565 Autonomous clients utilize an existing trust relationship or 566 framework to establish authorization. Autonomous clients can be 567 implemented in different ways based on their requirements and the 568 existing trust framework they rely upon. Autonomous clients can: 570 o Obtain an access token by authenticating with the authorization 571 server using their client credentials. The scope of the access 572 token is limited to the protected resources under the control of 573 the client, or that of another resource owner previously arranged 574 with the authorization server. 576 o Use an existing access grant expressed as an assertion using an 577 assertion format supported by the authorization server. Using 578 assertions requires the client to obtain a assertion (such as a 579 SAML [OASIS.saml-core-2.0-os] assertion) from an assertion issuer 580 or to self-issue an assertion. The assertion format, the process 581 by which the assertion is obtained, and the method of validating 582 the assertion are defined by the assertion issuer and the 583 authorization server, and are beyond the scope of this 584 specification. 586 2. Client Credentials 588 When interacting with the authorization server, the client identifies 589 itself using a client identifier and authenticates using a set of 590 client credentials. This specification provides one mechanism for 591 authenticating the client using password credentials. 593 The means through which the client obtains its credentials are beyond 594 the scope of this specification, but usually involve registration 595 with the authorization server. [[ OAuth Discovery provides one way of 596 obtaining a client password ]] 598 Due to the nature of some clients, authorization servers SHOULD NOT 599 make assumptions about the confidentiality of client secrets without 600 establishing trust with the client operator. Authorization servers 601 SHOULD NOT issue client secrets to clients incapable of keeping their 602 secrets confidential. 604 The authorization server MAY authenticate the client using any 605 appropriate set of credentials and authentication scheme. The client 606 MUST NOT utilize more than one set of credentials or authentication 607 mechanism with each request. 609 2.1. Client Password Credentials 611 The client password credentials use a shared symmetric secret to 612 authenticate the client. The client identifier and password are 613 included in the request using the HTTP Basic authentication scheme as 614 defined in [RFC2617] by including the client identifier as the 615 username and client password as the password. 617 For example (line breaks are for display purposes only): 619 POST /token HTTP/1.1 620 Host: server.example.com 621 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 622 Content-Type: application/x-www-form-urlencoded 624 grant_type=authorization_code&client_id=s6BhdRkqt3&code=i1WsRn1uB1& 625 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 627 Alternatively, the client MAY include the password in the request 628 body using the following parameter: 630 client_secret REQUIRED. The client password. 632 For example (line breaks are for display purposes only): 634 POST /token HTTP/1.1 635 Host: server.example.com 636 Content-Type: application/x-www-form-urlencoded 638 grant_type=authorization_code&client_id=s6BhdRkqt3& 639 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 640 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 642 The authorization server MUST accept the client credentials using 643 both the request parameter, and the HTTP Basic authentication scheme. 644 The authorization server MAY support additional authentication 645 schemes suitable for the transmission of a password. 647 3. Obtaining End-User Authorization 649 When the client interacts with an end-user, the end-user MUST first 650 grant the client authorization to access its protected resources. 651 Once obtained, the end-user access grant is expressed as an 652 authorization code which the client uses to obtain an access token. 653 To obtain an end-user authorization, the client sends the end-user to 654 the end-user authorization endpoint. 656 At the end-user authorization endpoint, the end-user first 657 authenticates with the authorization server, and then grants or 658 denies the access request. The way in which the authorization server 659 authenticates the end-user (e.g. username and password login, OpenID, 660 session cookies) and in which the authorization server obtains the 661 end-user's authorization, including whether it uses a secure channel 662 such as TLS, is beyond the scope of this specification. However, the 663 authorization server MUST first verify the identity of the end-user. 665 The location of the end-user authorization endpoint can be found in 666 the service documentation, or can be obtained by using [[ OAuth 667 Discovery ]]. The end-user authorization endpoint URI MAY include a 668 query component as defined by [RFC3986] section 3, which must be 669 retained when adding additional query parameters. 671 Since requests to the end-user authorization endpoint result in user 672 authentication and the transmission of sensitive information, the 673 authorization server SHOULD require the use of a transport-layer 674 security mechanism such as TLS when sending requests to the end-user 675 authorization endpoint. 677 In order to direct the end-user's user-agent to the authorization 678 server, the client constructs the request URI by adding the following 679 parameters to the end-user authorization endpoint URI query component 680 using the "application/x-www-form-urlencoded" format as defined by 681 [W3C.REC-html401-19991224]: 683 response_type 684 REQUIRED. The requested response: an access token, an 685 authorization code, or both. The parameter value MUST be set 686 to "token" for requesting an access token, "code" for 687 requesting an authorization code, or "code_and_token" to 688 request both. The authorization server MAY decline to provide 689 one or more of these response types. [[ The 'code_and_token' 690 type is pending use cases and may be removed for the 691 specification ]] 693 client_id 694 REQUIRED. The client identifier as described in Section 2. 696 redirect_uri 697 REQUIRED, unless a redirection URI has been established between 698 the client and authorization server via other means. An 699 absolute URI to which the authorization server will redirect 700 the user-agent to when the end-user authorization step is 701 completed. The authorization server SHOULD require the client 702 to pre-register their redirection URI. 704 scope 705 OPTIONAL. The scope of the access request expressed as a list 706 of space-delimited strings. The value of the "scope" parameter 707 is defined by the authorization server. If the value contains 708 multiple space-delimited strings, their order does not matter, 709 and each string adds an additional access range to the 710 requested scope. 712 state 713 OPTIONAL. An opaque value used by the client to maintain state 714 between the request and callback. The authorization server 715 includes this value when redirecting the user-agent back to the 716 client. 718 The client directs the end-user to the constructed URI using an HTTP 719 redirection response, or by other means available to it via the end- 720 user's user-agent. The authorization server MUST support the use of 721 the HTTP "GET" method for the end-user authorization endpoint, and 722 MAY support the use of the "POST" method as well. 724 For example, the client directs the end-user's user-agent to make the 725 following HTTP request using transport-layer security (line breaks 726 are for display purposes only): 728 GET /authorize?response_type=code&client_id=s6BhdRkqt3& 729 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 730 Host: server.example.com 732 If the client has previously registered a redirection URI with the 733 authorization server, the authorization server MUST verify that the 734 redirection URI received matches the registered URI associated with 735 the client identifier. [[ provide guidance on how to perform matching 736 ]] 738 Parameters sent without a value MUST be treated as if they were 739 omitted from the request. The authorization server SHOULD ignore 740 unrecognized request parameters. 742 The authorization server validates the request to ensure all required 743 parameters are present and valid. If the request is invalid, the 744 authorization server immediately redirects the user-agent back to the 745 client using the redirection URI provided with the appropriate error 746 code as described in Section 3.2. 748 The authorization server authenticates the end-user and obtains an 749 authorization decision (by asking the end-user or by establishing 750 approval via other means). When a decision has been established, the 751 authorization server directs the end-user's user-agent to the 752 provided client redirection URI using an HTTP redirection response, 753 or by other means available to it via the end-user's user-agent. 755 3.1. Authorization Response 757 If the end-user grants the access request, the authorization server 758 issues an access token, an authorization code, or both, and delivers 759 them to the client by adding the following parameters to the 760 redirection URI (as described below): 762 code 763 REQUIRED if the response type is "code" or "code_and_token", 764 otherwise MUST NOT be included. The authorization code 765 generated by the authorization server. The authorization code 766 SHOULD expire shortly after it is issued. The authorization 767 server MUST invalidate the authorization code after a single 768 usage. The authorization code is bound to the client 769 identifier and redirection URI. 771 access_token 772 REQUIRED if the response type is "token" or "code_and_token", 773 otherwise MUST NOT be included. The access token issued by the 774 authorization server. The access token string MUST comply with 775 the access-token rule defined in Section 5.1.1. 777 expires_in 778 OPTIONAL. The duration in seconds of the access token lifetime 779 if an access token is included. For example, the value "3600" 780 denotes that the access token will expire in one hour from the 781 time the response was generated by the authorization server. 783 scope 784 OPTIONAL. The scope of the access token as a list of space- 785 delimited strings if an access token is included. The value of 786 the "scope" parameter is defined by the authorization server. 788 If the value contains multiple space-delimited strings, their 789 order does not matter, and each string adds an additional 790 access range to the requested scope. The authorization server 791 SHOULD include the parameter if the requested scope is 792 different from the one requested by the client. 794 state 795 REQUIRED if the "state" parameter was present in the client 796 authorization request. Set to the exact value received from 797 the client. 799 The method in which the authorization server adds the parameter to 800 the redirection URI is determined by the response type requested by 801 the client in the authorization request using the "response_type" 802 parameter. 804 If the response type is "code", the authorization server adds the 805 parameters to the redirection URI query component using the 806 "application/x-www-form-urlencoded" format as defined by 807 [W3C.REC-html401-19991224]. 809 For example, the authorization server redirects the end-user's user- 810 agent by sending the following HTTP response: 812 HTTP/1.1 302 Found 813 Location: https://client.example.com/cb?code=i1WsRn1uB1 815 If the response type is "token", the authorization server adds the 816 parameters to the redirection URI fragment component using the 817 "application/x-www-form-urlencoded" format as defined by 818 [W3C.REC-html401-19991224]. 820 For example, the authorization server redirects the end-user's user- 821 agent by sending the following HTTP response: 823 HTTP/1.1 302 Found 824 Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600 826 If the response type is "code_and_token", the authorization server 827 adds the "code" and "state" parameters to the redirection URI query 828 component and the "access_token", "scope", and "expires_in" to the 829 redirection URI fragment using the 830 "application/x-www-form-urlencoded" format as defined by 831 [W3C.REC-html401-19991224]. 833 For example, the authorization server redirects the end-user's user- 834 agent by sending the following HTTP response (line breaks are for 835 display purposes only): 837 HTTP/1.1 302 Found 838 Location: http://example.com/rd?code=i1WsRn1uB1 839 #access_token=FJQbwq9&expires_in=3600 841 Clients SHOULD ignore unrecognized response parameters. The sizes of 842 tokens and other values received from the authorization server, are 843 left undefined by this specification. Clients should avoid making 844 assumptions about value sizes. Servers should document the expected 845 size of any value they issue. 847 3.2. Error Response 849 If the end-user denies the access request or if the request is 850 invalid, the authorization server informs the client by adding the 851 following parameters to the redirection URI query component using the 852 "application/x-www-form-urlencoded" format as defined by 853 [W3C.REC-html401-19991224]: 855 error 856 REQUIRED. A single error code as described in Section 3.2.1. 858 error_description OPTIONAL. A human-readable text providing 859 additional information, used to assist in the understanding and 860 resolution of the error occurred. 862 error_uri OPTIONAL. A URI identifying a human-readable web page 863 with information about the error, used to provide the end-user 864 with additional information about the error. 866 state 867 REQUIRED if the "state" parameter was present in the client 868 authorization request. Set to the exact value received from 869 the client. 871 For example, the authorization server redirects the end-user's user- 872 agent by sending the following HTTP response: 874 HTTP/1.1 302 Found 875 Location: https://client.example.com/cb?error=access-denied 877 3.2.1. Error Codes 879 The authorization server includes one of the following error codes 880 with the error response: 882 invalid_request 883 The request is missing a required parameter, includes an 884 unsupported parameter or parameter value, or is otherwise 885 malformed. 887 invalid_client 888 The client identifier provided is invalid. 890 unauthorized_client 891 The client is not authorized to use the requested response 892 type. 894 redirect_uri_mismatch 895 The redirection URI provided does not match a pre-registered 896 value. 898 access_denied 899 The end-user or authorization server denied the request. 901 unsupported_response_type 902 The requested response type is not supported by the 903 authorization server. 905 invalid_scope 906 The requested scope is invalid, unknown, or malformed. 908 [[ Add mechanism for extending error codes ]] 910 4. Obtaining an Access Token 912 The client obtains an access token by authenticating with the 913 authorization server and presenting its access grant (in the form of 914 an authorization code, resource owner credentials, an assertion, or a 915 refresh token). 917 Since requests to the token endpoint result in the transmission of 918 plain text credentials in the HTTP request and response, the 919 authorization server MUST require the use of a transport-layer 920 security mechanism when sending requests to the token endpoints. 921 Servers MUST support TLS 1.2 as defined in [RFC5246], and MAY support 922 additional transport-layer security mechanisms. 924 The client requests an access token by making an HTTP "POST" request 925 to the token endpoint. The location of the token endpoint can be 926 found in the service documentation, or can be obtained by using [[ 927 OAuth Discovery ]]. The token endpoint URI MAY include a query 928 component. 930 The client authenticates with the authorization server by adding its 931 client credentials to the request as described in Section 2. The 932 authorization server MAY allow unauthenticated access token requests 933 when the client identity does not matter (e.g. anonymous client) or 934 when the client identity is established via other means (e.g. using 935 an assertion access grant). 937 The client constructs the request by including the following 938 parameters using the "application/x-www-form-urlencoded" format in 939 the HTTP request entity-body: 941 grant_type 942 REQUIRED. The access grant type included in the request. 943 Value MUST be one of "authorization_code", "password", 944 "assertion", "refresh_token", or "none". 946 client_id 947 REQUIRED, unless the client identity can be establish via other 948 means (e.g. assertion). The client identifier as described in 949 Section 2. 951 scope 952 OPTIONAL. The scope of the access request expressed as a list 953 of space-delimited strings. The value of the "scope" parameter 954 is defined by the authorization server. If the value contains 955 multiple space-delimited strings, their order does not matter, 956 and each string adds an additional access range to the 957 requested scope. If the access grant being used already 958 represents an approved scope (e.g. authorization code, 959 assertion), the requested scope MUST be equal or lesser than 960 the scope previously granted. 962 In addition, the client MUST include the appropriate parameters 963 listed for the selected access grant type as described in 964 Section 4.1. 966 Parameters sent without a value MUST be treated as if they were 967 omitted from the request. The authorization server SHOULD ignore 968 unrecognized request parameters. 970 4.1. Access Grant Types 972 The client requests an access token using one of the four types of 973 access grants: authorization code, password credentials, assertion, 974 or refresh token. 976 When requesting an access token using the "none" access grant type 977 (no access grant is included), the client is requesting access to the 978 protected resources under its control, or those of another resource 979 owner which has been previously arranged with the authorization 980 server (the method of which is beyond the scope of this 981 specification). 983 4.1.1. Authorization Code 985 The client includes the authorization code using the 986 "authorization_code" access grant type and the following parameters: 988 code 989 REQUIRED. The authorization code received from the 990 authorization server. 992 redirect_uri 993 REQUIRED. The redirection URI used in the initial request. 995 For example, the client makes the following HTTP request by including 996 its client credentials via the "client_secret" parameter described in 997 Section 2 and using transport-layer security (line breaks are for 998 display purposes only): 1000 POST /token HTTP/1.1 1001 Host: server.example.com 1002 Content-Type: application/x-www-form-urlencoded 1004 grant_type=authorization_code&client_id=s6BhdRkqt3& 1005 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 1006 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1008 The authorization server MUST: 1010 o Validate the client credentials (if present) and ensure they match 1011 the authorization code. 1013 o Verify that the authorization code and redirection URI are all 1014 valid and match its stored association. 1016 If the request is valid, the authorization server issues a successful 1017 response as described in Section 4.2. 1019 4.1.2. Resource Owner Password Credentials 1021 The client includes the resource owner credentials using the 1022 "password" access grant type and the following parameters: [[ add 1023 internationalization consideration for username and password ]] 1025 username 1026 REQUIRED. The resource owner's username. 1028 password 1029 REQUIRED. The resource owner's password. 1031 For example, the client makes the following HTTP request by including 1032 its client credentials via the "client_secret" parameter described in 1033 Section 2 and using transport-layer security (line breaks are for 1034 display purposes only): 1036 POST /token HTTP/1.1 1037 Host: server.example.com 1038 Content-Type: application/x-www-form-urlencoded 1040 grant_type=password&client_id=s6BhdRkqt3& 1041 client_secret=47HDu8s&username=johndoe&password=A3ddj3w 1043 The authorization server MUST validate the client credentials (if 1044 present) and end-user credentials and if valid issue an access token 1045 response as described in Section 4.2. 1047 4.1.3. Assertion 1049 The client includes the assertion using the "assertion" access grant 1050 type and the following parameters: 1052 assertion_type 1053 REQUIRED. The format of the assertion as defined by the 1054 authorization server. The value MUST be an absolute URI. 1056 assertion 1057 REQUIRED. The assertion. 1059 For example, the client makes the following HTTP request using 1060 transport-layer security, and client authentication is achieved via 1061 the assertion (line breaks are for display purposes only): 1063 POST /token HTTP/1.1 1064 Host: server.example.com 1065 Content-Type: application/x-www-form-urlencoded 1067 grant_type=assertion& 1068 assertion_type=urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Aassertion& 1069 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D 1071 The authorization server MUST validate the client credentials (if 1072 present) and the assertion and if valid issues an access token 1073 response as described in Section 4.2. The authorization server 1074 SHOULD NOT issue a refresh token (instead, require the client to use 1075 the same or new assertion). 1077 Authorization servers SHOULD issue access tokens with a limited 1078 lifetime and require clients to refresh them by requesting a new 1079 access token using the same assertion if it is still valid. 1080 Otherwise the client MUST obtain a new valid assertion. 1082 4.1.4. Refresh Token 1084 The client includes the refresh token using the "refresh_token" 1085 access grant type and the following parameter: 1087 refresh_token 1088 REQUIRED. The refresh token associated with the access token 1089 to be refreshed. 1091 For example, the client makes the following HTTP request by including 1092 its client credentials via the "client_secret" parameter described in 1093 Section 2 and using transport-layer security (line breaks are for 1094 display purposes only): 1096 POST /token HTTP/1.1 1097 Host: server.example.com 1098 Content-Type: application/x-www-form-urlencoded 1100 grant_type=refresh_token&client_id=s6BhdRkqt3& 1101 client_secret=8eSEIpnqmM&refresh_token=n4E9O119d 1103 The authorization server MUST verify the client credentials (if 1104 present), the validity of the refresh token, and that the resource 1105 owner's authorization is still valid. If the request is valid, the 1106 authorization server issues an access token response as described in 1107 Section 4.2. The authorization server MAY issue a new refresh token. 1109 4.2. Access Token Response 1111 After receiving and verifying a valid and authorized access token 1112 request from the client, the authorization server issues the access 1113 token and optional refresh token, and constructs the response by 1114 adding the following parameters to the entity body of the HTTP 1115 response with a 200 (OK) status code: 1117 The token response contains the following parameters: 1119 access_token 1120 REQUIRED. The access token issued by the authorization server. 1121 The access token string MUST comply with the access-token rule 1122 defined in Section 5.1.1. 1124 expires_in 1125 OPTIONAL. The duration in seconds of the access token 1126 lifetime. For example, the value "3600" denotes that the 1127 access token will expire in one hour from the time the response 1128 was generated by the authorization server. 1130 refresh_token 1131 OPTIONAL. The refresh token used to obtain new access tokens 1132 using the same end-user access grant as described in 1133 Section 4.1.4. The authorization server SHOULD NOT issue a 1134 refresh token when the access grant type is set to "none". 1136 scope 1137 OPTIONAL. The scope of the access token as a list of space- 1138 delimited strings. The value of the "scope" parameter is 1139 defined by the authorization server. If the value contains 1140 multiple space-delimited strings, their order does not matter, 1141 and each string adds an additional access range to the 1142 requested scope. The authorization server SHOULD include the 1143 parameter if the requested scope is different from the one 1144 requested by the client. 1146 The parameters are including in the entity body of the HTTP response 1147 using the "application/json" media type as defined by [RFC4627]. The 1148 parameters are serialized into a JSON structure by adding each 1149 parameter at the highest structure level. Parameter names and string 1150 values are included as JSON strings. Numerical values are included 1151 as JSON numbers. 1153 The authorization server MUST include the HTTP "Cache-Control" 1154 response header field with a value of "no-store" in any response 1155 containing tokens, secrets, or other sensitive information. 1157 For example: 1159 HTTP/1.1 200 OK 1160 Content-Type: application/json 1161 Cache-Control: no-store 1163 { 1164 "access_token":"SlAV32hkKG", 1165 "expires_in":3600, 1166 "refresh_token":"8xLOxBtZp8" 1167 } 1169 Clients SHOULD ignore unrecognized response parameters. The sizes of 1170 tokens and other values received from the authorization server, are 1171 left undefined by this specification. Clients should avoid making 1172 assumptions about value sizes. Servers should document the expected 1173 size of any value they issue. 1175 4.3. Error Response 1177 If the token request is invalid or unauthorized, the authorization 1178 server constructs the response by adding the following parameter to 1179 the entity body of the HTTP response using the "application/json" 1180 media type: 1182 error 1183 REQUIRED. A single error code as described in Section 4.3.1. 1185 error_description OPTIONAL. A human-readable text providing 1186 additional information, used to assist in the understanding and 1187 resolution of the error occurred. 1189 error_uri OPTIONAL. A URI identifying a human-readable web page 1190 with information about the error, used to provide the end-user 1191 with additional information about the error. 1193 For example: 1195 HTTP/1.1 400 Bad Request 1196 Content-Type: application/json 1197 Cache-Control: no-store 1199 { 1200 "error":"invalid_request" 1201 } 1203 If the client provided invalid credentials using an HTTP 1204 authentication scheme via the "Authorization" request header field, 1205 the authorization server MUST respond with the HTTP 401 1206 (Unauthorized) status code. Otherwise, the authorization server 1207 SHALL respond with the HTTP 400 (Bad Request) status code. 1209 4.3.1. Error Codes 1211 The authorization server includes one of the following error codes 1212 with the error response: 1214 invalid_request 1215 The request is missing a required parameter, includes an 1216 unsupported parameter or parameter value, repeats a parameter, 1217 includes multiple credentials, utilizes more than one mechanism 1218 for authenticating the client, or is otherwise malformed. 1220 invalid_client 1221 The client identifier provided is invalid, the client failed to 1222 authenticate, the client did not include its credentials, 1223 provided multiple client credentials, or used unsupported 1224 credentials type. 1226 unauthorized_client 1227 The authenticated client is not authorized to use the access 1228 grant type provided. 1230 invalid_grant 1231 The provided access grant is invalid, expired, or revoked (e.g. 1232 invalid assertion, expired authorization token, bad end-user 1233 password credentials, or mismatching authorization code and 1234 redirection URI). 1236 unsupported_grant_type 1237 The access grant included - its type or another attribute - is 1238 not supported by the authorization server. 1240 invalid_scope 1241 The requested scope is invalid, unknown, malformed, or exceeds 1242 the previously granted scope. 1244 [[ Add mechanism for extending error codes ]] 1246 5. Accessing a Protected Resource 1248 Clients access protected resources by presenting an access token to 1249 the resource server. Access tokens act as bearer tokens, where the 1250 token string acts as a shared symmetric secret. This requires 1251 treating the access token with the same care as other secrets (e.g. 1252 end-user passwords). Access tokens SHOULD NOT be sent in the clear 1253 over an insecure channel. 1255 However, when it is necessary to transmit access tokens in the clear 1256 without a secure channel, authorization servers SHOULD issue access 1257 tokens with limited scope and lifetime to reduce the potential risk 1258 from a compromised access token. 1260 Clients MUST NOT make authenticated requests with an access token to 1261 unfamiliar resource servers, regardless of the presence of a secure 1262 channel. 1264 The resource server MUST validate the access token and ensure it has 1265 not expired and that its scope covers the requested resource. The 1266 methods used by the resource server to validate the access token are 1267 beyond the scope of this specification, but generally involve an 1268 interaction or coordination between the resource server and 1269 authorization server. 1271 5.1. Authenticated Requests 1273 Clients make authenticated token requests using the "Authorization" 1274 request header field. Resource servers MUST accept authenticated 1275 requests using the "OAuth" HTTP authentication scheme as described in 1276 Section 5.1.1, and MAY support additional methods. 1278 Alternatively, clients MAY attempt to include the access token using 1279 the HTTP request URI in the query component as described in 1280 Section 5.1.2, or in the HTTP body when using the 1281 "application/x-www-form-urlencoded" content type as described in 1282 Section 5.1.3. Resource server MAY support these alternative 1283 methods. 1285 Clients SHOULD only use the request URI or body when the 1286 "Authorization" request header field is not available, and MUST NOT 1287 use more than one method in each request. 1289 5.1.1. The Authorization Request Header Field 1291 The "Authorization" request header field is used by clients to make 1292 authenticated token requests. The client uses the "OAuth" 1293 authentication scheme to include the access token in the request. 1295 For example: 1297 GET /resource HTTP/1.1 1298 Host: server.example.com 1299 Authorization: OAuth vF9dft4qmT 1301 The "Authorization" header field uses the framework defined by 1302 [RFC2617] as follows: 1304 credentials = "OAuth" RWS access-token [ CS 1#auth-param ] 1305 access-token = 1*( quoted-char / <"> ) 1307 CS = OWS "," OWS 1309 quoted-char = "!" / "#" / "$" / "%" / "&" / "'" / "(" 1310 / ")" / "*" / "+" / "-" / "." / "/" / DIGIT 1311 / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA 1312 / "[" / "]" / "^" / "_" / "`" / "{" / "|" 1313 / "}" / "~" / "\" / "," / ";" 1315 NOTE: [RFC5849] defines a different format for the "OAuth" 1316 authentication scheme. Resource servers can differentiate between 1317 the two protocol versions based on the presence of the 1318 "oauth_signature_method" which is REQUIRED in the previous version 1319 and is not supported by this specification. 1321 5.1.2. URI Query Parameter 1323 When including the access token in the HTTP request URI, the client 1324 adds the access token to the request URI query component as defined 1325 by [RFC3986] using the "oauth_token" parameter. 1327 For example, the client makes the following HTTP request using 1328 transport-layer security: 1330 GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 1331 Host: server.example.com 1333 The HTTP request URI query can include other request-specific 1334 parameters, in which case, the "oauth_token" parameters SHOULD be 1335 appended following the request-specific parameters, properly 1336 separated by an "&" character (ASCII code 38). 1338 For example: 1340 http://example.com/resource?x=y&oauth_token=vF9dft4qmT 1342 NOTE: The "oauth_token" parameter is used by the previous version 1343 of the OAuth protocol as described in [RFC5849]. Resource servers 1344 can differentiate between the two protocol versions based on the 1345 presence of the "oauth_signature_method" which is REQUIRED in the 1346 previous version and is not supported by this specification. 1348 5.1.3. Form-Encoded Body Parameter 1350 When including the access token in the HTTP request entity-body, the 1351 client adds the access token to the request body using the 1352 "oauth_token" parameter. The client can use this method only if the 1353 following REQUIRED conditions are met: 1355 o The entity-body is single-part. 1357 o The entity-body follows the encoding requirements of the 1358 "application/x-www-form-urlencoded" content-type as defined by 1359 [W3C.REC-html401-19991224]. 1361 o The HTTP request entity-header includes the "Content-Type" header 1362 field set to "application/x-www-form-urlencoded". 1364 o The HTTP request method is "POST", "PUT", or "DELETE". 1366 The entity-body can include other request-specific parameters, in 1367 which case, the "oauth_token" parameters SHOULD be appended following 1368 the request-specific parameters, properly separated by an "&" 1369 character (ASCII code 38). 1371 For example, the client makes the following HTTP request using 1372 transport-layer security: 1374 POST /resource HTTP/1.1 1375 Host: server.example.com 1376 Content-Type: application/x-www-form-urlencoded 1378 oauth_token=vF9dft4qmT 1380 NOTE: The "oauth_token" parameter is used by the previous version 1381 of the OAuth protocol as described in [RFC5849]. Resource servers 1382 can differentiate between the two protocol versions based on the 1383 presence of the "oauth_signature_method" which is REQUIRED in the 1384 previous version and is not supported by this specification. 1386 5.2. The WWW-Authenticate Response Header Field 1388 If the protected resource request contains an invalid access token or 1389 is malformed, the resource server MUST include the HTTP 1390 "WWW-Authenticate" response header field. The "WWW-Authenticate" 1391 header field uses the framework defined by [RFC2617] as follows: 1393 challenge = "OAuth" RWS token-challenge 1395 token-challenge = realm 1396 [ CS error ] 1397 [ CS error-desc ] 1398 [ CS error-uri ] 1399 [ CS scope ] 1400 [ CS 1#auth-param ] 1402 error = "error" "=" <"> token <"> 1403 error-desc = "error_description" "=" quoted-string 1404 error-uri = "error_uri" = <"> URI-Reference <"> 1405 scope = quoted-value / 1406 <"> quoted-value *( 1*SP quoted-value ) <"> 1407 quoted-value = 1*quoted-char 1409 For example: 1411 HTTP/1.1 401 Unauthorized 1412 WWW-Authenticate: OAuth realm='Example Service', error='expired-token' 1413 The "realm" attribute is used to provide the protected resources 1414 partition as defined by [RFC2617]. [[ add explanation ]] 1416 The "error" attribute is used to provide the client with the reason 1417 why the access request was declined. The parameter values are 1418 described in Section 5.2.1. 1420 The "error_description" attribute provides a human-readable text 1421 containing additional information, used to assist in the 1422 understanding and resolution of the error occurred. 1424 The "error_uri" attribute provides a URI identifying a human-readable 1425 web page with information about the error, used to offer the end-user 1426 with additional information about the error. If the value is not an 1427 absolute URI, it is relative to the URI of the requested protected 1428 resource. 1430 The "scope" attribute is a space-delimited list of scope values 1431 indicating the required scope of the access token for accessing the 1432 requested resource. 1434 5.2.1. Error Codes 1436 The authorization server includes one of the following error codes 1437 with the error response: 1439 invalid_request 1440 The request is missing a required parameter, includes an 1441 unsupported parameter or parameter value, repeats the same 1442 parameter, uses more than one method for including an access 1443 token, or is otherwise malformed. The resource server MUST 1444 respond with the HTTP 400 (Bad Request) status code. 1446 invalid_token 1447 The access token provided is invalid. Resource servers SHOULD 1448 use this error code when receiving an expired token which 1449 cannot be refreshed to indicate to the client that a new 1450 authorization is necessary. The resource server MUST respond 1451 with the HTTP 401 (Unauthorized) status code. 1453 expired_token 1454 The access token provided has expired. Resource servers SHOULD 1455 only use this error code when the client is expected to be able 1456 to handle the response and request a new access token using the 1457 refresh token issued with the expired access token. The 1458 resource server MUST respond with the HTTP 401 (Unauthorized) 1459 status code. 1461 insufficient_scope 1462 The request requires higher privileges than provided by the 1463 access token. The resource server SHOULD respond with the HTTP 1464 403 (Forbidden) status code and MAY include the "scope" 1465 attribute with the scope necessary to access the protected 1466 resource. 1468 [[ Add mechanism for extending error codes ]] 1470 If the request lacks any authentication information (i.e. the client 1471 was unaware authentication is necessary or attempted using an 1472 unsupported authentication method), the resource server SHOULD not 1473 include an error code or other error information. 1475 For example: 1477 HTTP/1.1 401 Unauthorized 1478 WWW-Authenticate: OAuth realm='Example Service' 1480 6. Extensibility 1482 6.1. Defining New Client Credentials Types 1484 [[ TBD ]] 1486 6.2. Defining New Endpoint Parameters 1488 Applications that wish to define new request or response parameters 1489 for use with the end-user authorization endpoint or the token 1490 endpoint SHALL do so in one of two ways: register them in the 1491 parameters registry (following the procedures in Section 8.1), or use 1492 the "x_" parameter name prefix. 1494 Parameters utilizing the "x_" parameter name prefix MUST be limited 1495 to vendor-specific extensions that are not commonly applicable, and 1496 are specific to the implementation details of the authorization 1497 server where they are used. All other new parameters MUST be 1498 registered, and MUST NOT use the "x_" parameter name prefix. 1500 Parameter names MUST conform to the param-name ABNF, and parameter 1501 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1502 to the syntax of an existing parameter). 1504 param-name = 1*name-char 1505 name-char = "-" / "." / "_" / DIGIT / ALPHA 1507 6.3. Defining New Header Field Parameters 1509 Applications that wish to define new parameters for use in the OAuth 1510 "Authorization" or "WWW-Authenticate" header fields MUST register 1511 them in the parameters registry, following the procedures in 1512 Section 8.1. 1514 Parameter names MUST conform to the param-name ABNF and MUST NOT 1515 begin with "x_". Parameter values MUST conform to the param-value 1516 ABNF and their syntax MUST be well-defined (e.g., using ABNF, or a 1517 reference to the syntax of an existing parameter). 1519 param-value = quoted-value | quoted-string 1521 6.4. Defining New Access Grant Types 1523 The assertion access grant type was designed to allow the 1524 authorization server to accept additional access grants not 1525 specified. Applications that wish to define additional access grant 1526 types can do so by utilizing a new or existing assertion type and 1527 format. 1529 7. Security Considerations 1531 [[ TBD ]] 1533 8. IANA Considerations 1535 8.1. The OAuth Parameters Registry 1537 This document establishes the OAuth parameters registry. 1539 Additional parameters to be use in the end-user authorization 1540 endpoint request, the end-user authorization endpoint response, the 1541 token endpoint request, the token endpoint response, the 1542 "Authorization" header field, or the "WWW-Authenticate" header field, 1543 are registered on the advice of one or more Designated Experts 1544 (appointed by the IESG or their delegate), with a Specification 1545 Required (using terminology from [RFC5226]). However, to allow for 1546 the allocation of values prior to publication, the Designated 1547 Expert(s) may approve registration once they are satisfied that such 1548 a specification will be published. 1550 Registration requests should be sent to the [TBD]@ietf.org mailing 1551 list for review and comment, with an appropriate subject (e.g., 1552 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 1553 the mailing list should be determined in consultation with the IESG 1554 and IANA. Suggested name: oauth-ext-review. ]] 1556 Before a period of 14 days has passed, the Designated Expert(s) will 1557 either approve or deny the registration request, communicating this 1558 decision both to the review list and to IANA. Denials should include 1559 an explanation and, if applicable, suggestions as to how to make the 1560 request successful. Registration requests that are undetermined for 1561 a period longer than 21 days can be brought to the IESG's attention 1562 (using the iesg@iesg.org mailing list) for resolution. 1564 8.1.1. Registration Template 1566 Parameter name: The name requested (e.g., "example"). 1568 Parameter usage location: The location(s) where parameter can be 1569 used. The possible locations are: the end-user authorization 1570 endpoint request, the end-user authorization endpoint response, 1571 the token endpoint request, the token endpoint response, the 1572 "Authorization" header field, or the "WWW-Authenticate" header 1573 field. 1575 Change controller: For standards-track RFCs, state "IETF". For 1576 others, give the name of the responsible party. Other details 1577 (e.g., postal address, e-mail address, home page URI) may also be 1578 included. 1580 Specification document(s): Reference to document that specifies the 1581 parameter, preferably including a URI that can be used to retrieve 1582 a copy of the document. An indication of the relevant sections 1583 may also be included, but is not required. 1585 Related information: Optionally, citations to additional documents 1586 containing further relevant information. 1588 8.1.2. Example 1590 The following is the parameter registration request for the "scope" 1591 parameter as defined in this specification: 1593 Parameter name: scope 1595 Parameter usage location: The end-user authorization endpoint 1596 request, the end-user authorization endpoint response, the token 1597 endpoint request, the token endpoint response, and the 1598 "WWW-Authenticate" header field. 1600 Change controller: IETF 1602 Specification document(s): [[ this document ]] 1604 Related information: None 1606 Appendix A. Examples 1608 [[ TBD ]] 1610 Appendix B. Contributors 1612 The following people contributed to preliminary versions of this 1613 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland 1614 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 1615 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 1616 concepts within are a product of the OAuth community, WRAP community, 1617 and the OAuth Working Group. 1619 The OAuth Working Group has dozens of very active contributors who 1620 proposed ideas and wording for this document, including: [[ If your 1621 name is missing or you think someone should be added here, please 1622 send Eran a note - don't be shy ]] 1624 Michael Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah 1625 Culver, Brian Ellin, Igor Faynberg, George Fletcher, Evan Gilbert, 1626 Justin Hart, John Kemp, Chasen Le Hara, Torsten Lodderstedt, Eve 1627 Maler, James Manger, Laurence Miao, Chuck Mortimore, Justin Richer, 1628 Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Justin 1629 Smith, Jeremy Suriel, and Franklin Tse. 1631 Appendix C. Acknowledgements 1633 [[ Add OAuth 1.0a authors + WG contributors ]] 1635 Appendix D. Document History 1637 [[ to be removed by RFC editor before publication as an RFC ]] 1639 -10 1641 o Fixed typos. Many editorial changes. Rewrote introduction. 1642 removed terminology grouping. 1644 o Allowed POST for end-user authorization endpoint. 1646 o Fixed token endpoint to not require client authentication. 1648 o Made URI query and POST body 'oauth_token' parameter optional. 1650 o Moved all parameter names and values to use underscores. 1652 o Changed 'basic_credentials' to 'password', 1653 'invalid_client_credentials' and 'invalid_client_id' to 1654 'invalid_client'. 1656 o Added note that access token requests without an access grant 1657 should not include a refresh token. 1659 o Changed scheme name from 'Token' to 'OAuth', simplified request 1660 format to simple string for token instead of key=value pair (still 1661 supported for extensions). 1663 o Defined permitted access token string characters (suitable for 1664 inclusion in an HTTP header). 1666 o Added a note about conflicts with previous versions. 1668 o Moved 'client_id' definition from client authentication to access 1669 token endpoint. 1671 -09 1673 o Fixed typos, editorial changes. 1675 o Added token expiration example. 1677 o Added scope parameter to end-user authorization endpoint response. 1679 o Added note about parameters with empty values (same as omitted). 1681 o Changed parameter values to use '-' instead of '_'. Parameter 1682 names still use '_'. 1684 o Changed authorization endpoint client type to response type with 1685 values: code, token, and both. 1687 o Complete cleanup of error codes. Added support for error 1688 description and URI. 1690 o Add initial extensibility support. 1692 -08 1694 o Renamed verification code to authorization code. 1696 o Revised terminology, structured section, added new terms. 1698 o Changed flows to profiles and moved to introduction. 1700 o Added support for access token rescoping. 1702 o Cleaned up client credentials section. 1704 o New introduction overview. 1706 o Added error code for invalid username and password, and renamed 1707 error code to be more consistent. 1709 o Added access grant type parameter to token endpoint. 1711 -07 1713 o Major rewrite of entire document structure. 1715 o Removed device profile. 1717 o Added verification code support to user-agent flow. 1719 o Removed multiple formats support, leaving JSON as the only format. 1721 o Changed assertion "assertion_format" parameter to 1722 "assertion_type". 1724 o Removed "type" parameter from token endpoint. 1726 -06 1728 o Editorial changes, corrections, clarifications, etc. 1730 o Removed conformance section. 1732 o Moved authors section to contributors appendix. 1734 o Added section on native applications. 1736 o Changed error response to use the requested format. Added support 1737 for HTTP "Accept" header. 1739 o Flipped the order of the web server and user-agent flows. 1741 o Renamed assertion flow "format" parameter name to 1742 "assertion_format" to resolve conflict. 1744 o Removed the term identifier from token definitions. Added a 1745 cryptographic token definition. 1747 o Added figure titles. 1749 o Added server response 401 when client tried to authenticate using 1750 multiple credentials. 1752 o Clarified support for TLS alternatives, and added requirement for 1753 TLS 1.2 support for token endpoint. 1755 o Removed all signature and cryptography. 1757 o Removed all discovery. 1759 o Updated HTML4 reference. 1761 -05 1763 o Corrected device example. 1765 o Added client credentials parameters to the assertion flow as 1766 OPTIONAL. 1768 o Added the ability to send client credentials using an HTTP 1769 authentication scheme. 1771 o Initial text for the "WWW-Authenticate" header (also added scope 1772 support). 1774 o Change authorization endpoint to end-user endpoint. 1776 o In the device flow, change the "user_uri" parameter to 1777 "verification_uri" to avoid confusion with the end-user endpoint. 1779 o Add "format" request parameter and support for XML and form- 1780 encoded responses. 1782 -04 1784 o Changed all token endpoints to use "POST" 1786 o Clarified the authorization server's ability to issue a new 1787 refresh token when refreshing a token. 1789 o Changed the flow categories to clarify the autonomous group. 1791 o Changed client credentials language not to always be server- 1792 issued. 1794 o Added a "scope" response parameter. 1796 o Fixed typos. 1798 o Fixed broken document structure. 1800 -03 1802 o Fixed typo in JSON error examples. 1804 o Fixed general typos. 1806 o Moved all flows sections up one level. 1808 -02 1810 o Removed restriction on "redirect_uri" including a query. 1812 o Added "scope" parameter. 1814 o Initial proposal for a JSON-based token response format. 1816 -01 1818 o Editorial changes based on feedback from Brian Eaton, Bill Keenan, 1819 and Chuck Mortimore. 1821 o Changed device flow "type" parameter values and switch to use only 1822 the token endpoint. 1824 -00 1825 o Initial draft based on a combination of WRAP and OAuth 1.0a. 1827 9. References 1829 9.1. Normative References 1831 [I-D.ietf-httpbis-p1-messaging] 1832 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1833 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1834 "HTTP/1.1, part 1: URIs, Connections, and Message 1835 Parsing", draft-ietf-httpbis-p1-messaging-09 (work in 1836 progress), March 2010. 1838 [NIST FIPS-180-3] 1839 National Institute of Standards and Technology, "Secure 1840 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1842 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1843 Extensions (MIME) Part One: Format of Internet Message 1844 Bodies", RFC 2045, November 1996. 1846 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1847 Hashing for Message Authentication", RFC 2104, 1848 February 1997. 1850 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1851 Requirement Levels", BCP 14, RFC 2119, March 1997. 1853 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1854 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1855 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1857 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1858 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1859 Authentication: Basic and Digest Access Authentication", 1860 RFC 2617, June 1999. 1862 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1864 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1865 Types", RFC 3023, January 2001. 1867 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1868 Standards (PKCS) #1: RSA Cryptography Specifications 1869 Version 2.1", RFC 3447, February 2003. 1871 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1872 10646", STD 63, RFC 3629, November 2003. 1874 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1875 Resource Identifier (URI): Generic Syntax", STD 66, 1876 RFC 3986, January 2005. 1878 [RFC4627] Crockford, D., "The application/json Media Type for 1879 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1881 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1882 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1883 May 2008. 1885 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1886 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1888 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1889 April 2010. 1891 [W3C.REC-html401-19991224] 1892 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 1893 Specification", World Wide Web Consortium 1894 Recommendation REC-html401-19991224, December 1999, 1895 . 1897 9.2. Informative References 1899 [I-D.hammer-oauth] 1900 Hammer-Lahav, E., "The OAuth 1.0 Protocol", 1901 draft-hammer-oauth-10 (work in progress), February 2010. 1903 [I-D.hardt-oauth] 1904 Hardt, D., Tom, A., Eaton, B., and Y. Goland, "OAuth Web 1905 Resource Authorization Profiles", draft-hardt-oauth-01 1906 (work in progress), January 2010. 1908 [OASIS.saml-core-2.0-os] 1909 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1910 "Assertions and Protocol for the OASIS Security Assertion 1911 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1912 2.0-os, March 2005. 1914 Authors' Addresses 1916 Eran Hammer-Lahav (editor) 1917 Yahoo! 1919 Email: eran@hueniverse.com 1920 URI: http://hueniverse.com 1922 David Recordon 1923 Facebook 1925 Email: davidrecordon@facebook.com 1926 URI: http://www.davidrecordon.com/ 1928 Dick Hardt 1929 Microsoft 1931 Email: dick.hardt@gmail.com 1932 URI: http://dickhardt.org/