idnits 2.17.1 draft-ietf-oauth-v2-09.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). == 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), the resource server SHOULD not include an error code or other error information. -- The document date (June 29, 2010) is 5047 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 1733, but no explicit reference was found in the text == Unused Reference: 'RFC2045' is defined on line 1737, but no explicit reference was found in the text == Unused Reference: 'RFC2104' is defined on line 1741, but no explicit reference was found in the text == Unused Reference: 'RFC3023' is defined on line 1759, but no explicit reference was found in the text == Unused Reference: 'RFC3447' is defined on line 1762, but no explicit reference was found in the text == Unused Reference: 'RFC3629' is defined on line 1766, but no explicit reference was found in the text == Unused Reference: 'I-D.hammer-oauth' is defined on line 1791, but no explicit reference was found in the text == Unused Reference: 'I-D.hardt-oauth' is defined on line 1795, 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) Summary: 9 errors (**), 0 flaws (~~), 12 warnings (==), 3 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 31, 2010 Facebook 6 D. Hardt 7 Microsoft 8 June 29, 2010 10 The OAuth 2.0 Protocol 11 draft-ietf-oauth-v2-09 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 December 31, 2010. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 6 55 1.4. Client Profiles . . . . . . . . . . . . . . . . . . . . . 9 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. Basic Client 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 . . . . . . . . . . . . . . . . . . . . 22 68 4.1.1. Authorization Code . . . . . . . . . . . . . . . . . . 23 69 4.1.2. Resource Owner Basic Credentials . . . . . . . . . . . 23 70 4.1.3. Assertion . . . . . . . . . . . . . . . . . . . . . . 24 71 4.1.4. Refresh Token . . . . . . . . . . . . . . . . . . . . 25 72 4.2. Access Token Response . . . . . . . . . . . . . . . . . . 25 73 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 27 74 4.3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 27 75 5. Accessing a Protected Resource . . . . . . . . . . . . . . . . 28 76 5.1. Authenticated Requests . . . . . . . . . . . . . . . . . . 29 77 5.1.1. The Authorization Request Header Field . . . . . . . . 29 78 5.1.2. URI Query Parameter . . . . . . . . . . . . . . . . . 29 79 5.1.3. Form-Encoded Body Parameter . . . . . . . . . . . . . 30 80 5.2. The WWW-Authenticate Response Header Field . . . . . . . . 31 81 5.2.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 32 82 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 33 83 6.1. Defining New Client Credentials Types . . . . . . . . . . 33 84 6.2. Defining New Endpoint Parameters . . . . . . . . . . . . . 33 85 6.3. Defining New Header Field Parameters . . . . . . . . . . . 34 86 6.4. Defining New Access Grant Types . . . . . . . . . . . . . 34 87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 34 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 89 8.1. The OAuth Parameters Registry . . . . . . . . . . . . . . 34 90 8.1.1. Registration Template . . . . . . . . . . . . . . . . 35 91 8.1.2. Example . . . . . . . . . . . . . . . . . . . . . . . 35 92 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 36 93 Appendix B. Contributors . . . . . . . . . . . . . . . . . . . . 36 94 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 36 95 Appendix D. Document History . . . . . . . . . . . . . . . . . . 36 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 40 97 9.1. Normative References . . . . . . . . . . . . . . . . . . . 40 98 9.2. Informative References . . . . . . . . . . . . . . . . . . 41 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 42 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 presenting the 111 resource owner's credentials in order to authenticate and gain 112 access. OAuth introduces a third role to the traditional model: the 113 resource owner. In OAuth, the client (which is usually not the 114 resource owner, but is acting on its behalf) requests access to 115 resources controlled by the resource owner and hosted by the resource 116 server. 118 In addition to removing the need for resource owners to share their 119 credentials, resource owners require the ability to restrict access 120 to a limited subset of the resources they control, to limit access 121 duration, or to limit access to the methods supported by these 122 resources. 124 Instead of using the resource owner's credentials to access protected 125 resources, clients obtain an access token (a string which denotes a 126 specific scope, duration, and other attributes). The format and 127 structure of access tokens is beyond the scope of this specification. 129 Tokens are issued to third-party clients by an authorization server 130 with the approval of the resource owner. The client uses the access 131 token to access the protected resources hosted by the resource 132 server. The interaction between the authorization server and 133 resource server is beyond the scope of this specification. 135 For example, a web user (resource owner) can grant a printing service 136 (client) access to her protected photos stored at a photo sharing 137 service (resource server), without sharing her username and password 138 with the printing service. Instead, she authenticates directly with 139 the photo sharing service (authorization server) which issues the 140 printing service delegation-specific credentials (token). 142 This specification defines the use of OAuth over HTTP [RFC2616] (or 143 HTTP over TLS as defined by [RFC2818]). Other specifications may 144 extend it for use with other transport protocols. 146 1.1. Notational Conventions 148 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 149 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 150 document are to be interpreted as described in [RFC2119]. 152 This document uses the Augmented Backus-Naur Form (ABNF) notation of 153 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 154 are included from [RFC2617]: realm, auth-param; from [RFC3986]: URI- 155 Reference; and from [I-D.ietf-httpbis-p1-messaging]: OWS, RWS, and 156 quoted-string. 158 Unless otherwise noted, all the protocol parameter names and values 159 are case sensitive. 161 1.2. Terminology 163 protected resource 164 An access-restricted resource which can be obtained using an 165 OAuth-authenticated request. 167 resource server 168 A server capable of accepting and responding to protected 169 resource requests. 171 client 172 An application obtaining authorization and making protected 173 resource requests. 175 resource owner 176 An entity capable of granting access to a protected resource. 178 end-user 179 A human resource owner. 181 token 182 A string representing an access authorization issued to the 183 client. The string is usually opaque to the client and can 184 self-contain the authorization information in a verifiable 185 manner (i.e. signed), or denotes an identifier used to retrieve 186 the information. Tokens represent a specific scope, duration, 187 and other authorization attributes granted by the resource 188 owner and enforced by the resource server and authorization 189 servers. 191 access token 192 A token used by the client to make authenticated requests 193 on behalf of the resource owner. 195 refresh token 196 A token used by the client to obtain a new access token 197 without having to involve the resource owner. 199 authorization code A short-lived token representing the access 200 grant provided by the end-user. The authorization code 201 is used to obtain an access token and a refresh token. 203 authorization server 204 A server capable of issuing tokens after successfully 205 authenticating the resource owner and obtaining authorization. 206 The authorization server may be the same server as the resource 207 server, or a separate entity. 209 end-user authorization endpoint 210 The authorization server's HTTP endpoint capable of 211 authenticating the end-user and obtaining authorization. The 212 end-user authorization endpoint is described in Section 3. 214 token endpoint 215 The authorization server's HTTP endpoint capable of issuing 216 tokens and refreshing expired tokens. The token endpoint is 217 described in Section 4. 219 client identifier 220 An unique identifier issued to the client to identify itself to 221 the authorization server. Client identifiers may have a 222 matching secret. The client identifier is described in 223 Section 2. 225 1.3. Overview 227 OAuth provides a method for clients to access a protected resource on 228 behalf of a resource owner. Before a client can access a protected 229 resource, it must first obtain authorization from the resource owner, 230 then exchange the access grant for an access token (representing the 231 grant's scope, duration, and other attributes). The client accesses 232 the protected resource by presenting the access token to the resource 233 server. 235 +--------+ +---------------+ 236 | |--(A)-- Authorization Request --->| Resource | 237 | | | Owner | 238 | |<-(B)------ Access Grant ---------| | 239 | | +---------------+ 240 | | 241 | | Client Credentials & +---------------+ 242 | |--(C)------ Access Grant -------->| Authorization | 243 | Client | | Server | 244 | |<-(D)------ Access Token ---------| | 245 | | (w/ Optional Refresh Token) +---------------+ 246 | | 247 | | +---------------+ 248 | |--(E)------ Access Token -------->| Resource | 249 | | | Server | 250 | |<-(F)---- Protected Resource -----| | 251 +--------+ +---------------+ 253 Figure 1: Abstract Protocol Flow 255 The abstract flow illustrated in Figure 1 includes the following 256 steps: 258 (A) The client requests authorization from the resource owner. The 259 client should not interact directly with the resource owner 260 (since that would expose the resource owner's credentials to the 261 client), but instead request authorization via an authorization 262 server or other entities. For example, the client directs the 263 resource owner to the authorization server which in turn issues 264 it an access grant. When unavoidable, the client interacts 265 directly with the end-user, asking for the end-user's username 266 and password. If the client is acting autonomously, the 267 authorization request is beyond the scope of this specification. 269 (B) The client is issued an access grant which represents the 270 authorization provided by the resource owner. The access grant 271 can be expressed as: 273 * Authorization code - an access grant obtained via an 274 authorization server. The process used to obtain an 275 authorization code utilized the end-user's user-agent and is 276 described in Section 3. 278 * Assertion - an access grant obtained using a different trust 279 framework. Assertions enable the client to utilize existing 280 trust relationships to obtain an access token. They provide 281 a bridge between OAuth and other trust frameworks. The 282 access grant represented by an assertion depends on the 283 assertion type, its content, and how it was issued, which are 284 beyond the scope of this specification. 286 * Resource owner basic credentials - obtained when interacting 287 directly with a resource-owner. Resource owner basic 288 credentials (i.e. a username and password) should only be 289 used when there is a high degree of trust between the 290 resource owner and the client (e.g. its computer operating 291 system or a highly privileged application). However, unlike 292 the HTTP Basic authentication scheme defined in [RFC2617], 293 the resource owner's credentials are used for a single 294 request and are exchanged for an access token and refresh 295 token. This eliminates the need for the client to store the 296 resource-owner's credentials for future use. 298 (C) The client requests an access token by authenticating with the 299 authorization server, and presenting the access grant. The 300 token request is described in Section 4. 302 (D) The authorization server validates the client credentials and 303 the access grant, and issues an access token with an optional 304 refresh token. Access tokens usually have a shorter lifetime 305 than the access grant. Refresh tokens usually have a lifetime 306 equal to the duration of the access grant. When an access token 307 expires, the refresh token is used to obtain a new access token 308 without having to request another access grant from the resource 309 owner. 311 (E) The client makes a protected resource request to the resource 312 server, and presents the access token in order to gain access. 313 Accessing a protected resource is described in Section 5. 315 (F) The resource server validates the access token, and if valid, 316 serves the request. 318 When the client is acting on its own behalf (the client is also the 319 resource owner), the client does not obtain an access grant. The 320 simplified protocol flow is illustrated in Figure 2: 322 +--------+ +---------------+ 323 | |--(C)--- Client Credentials ----->| Authorization | 324 | | | Server | 325 | |<-(D)------ Access Token ---------| | 326 | | (w/ Optional Refresh Token) +---------------+ 327 | Client | 328 | | +---------------+ 329 | |--(E)------ Access Token -------->| Resource | 330 | | | Server | 331 | |<-(F)---- Protected Resource -----| | 332 +--------+ +---------------+ 334 Figure 2: Protocol Flow for Client Acting On Its Own Behalf 336 When the client uses the user-agent profile (described in 337 Section 1.4.2), the authorization request results in an access token, 338 as illustrated in Figure 3: 340 +--------+ +----------+ +---------------+ 341 | |--(A)-- Authorization --+- -+-->| | 342 | | Request | Resource | | Authorization | 343 | | | Owner | | Server | 344 | |<-(D)-- Access Token ---+- -+---| | 345 | | +----------+ +---------------+ 346 | Client | 347 | | +---------------+ 348 | |--(E)-------- Access Token ----------->| Resource | 349 | | | Server | 350 | |<-(F)------ Protected Resource --------| | 351 +--------+ +---------------+ 353 Figure 3: Indirect Access Grant Protocol Flow 355 1.4. Client Profiles 357 OAuth supports a wide range of client types by providing a rich and 358 extensible framework for establishing authorization and exchanging it 359 for an access token. The methods detailed in this specification were 360 designed to accommodate four client types: web servers, user-agents, 361 native applications, and autonomous clients. Additional 362 authorization flows and client profiles may be defined by other 363 specifications to cover additional scenarios and client types. 365 1.4.1. Web Server 367 The web server profile is suitable for clients capable of interacting 368 with the end-user's user-agent (typically a web browser) and capable 369 of receiving incoming requests from the authorization server (capable 370 of acting as an HTTP server). 372 +----------+ Client Identifier +---------------+ 373 | -+----(A)--- & Redirect URI ------>| | 374 | End-user | | Authorization | 375 | at |<---(B)-- User authenticates --->| Server | 376 | Browser | | | 377 | -+----(C)-- Authorization Code ---<| | 378 +-|----|---+ +---------------+ 379 | | ^ v 380 (A) (C) | | 381 | | | | 382 ^ v | | 383 +---------+ | | 384 | |>---(D)-- Client Credentials, --------' | 385 | Web | Authorization Code, | 386 | Client | & Redirect URI | 387 | | | 388 | |<---(E)----- Access Token -------------------' 389 +---------+ (w/ Optional Refresh Token) 391 Figure 4: Web Server Flow 393 The web server flow illustrated in Figure 4 includes the following 394 steps: 396 (A) The web client initiates the flow by redirecting the end-user's 397 user-agent to the end-user authorization endpoint as described 398 in Section 3 The client includes its client identifier, 399 requested scope, local state, and a redirect URI to which the 400 authorization server will send the end-user back once access is 401 granted (or denied). 403 (B) The authorization server authenticates the end-user (via the 404 user-agent) and establishes whether the end-user grants or 405 denies the client's access request. 407 (C) Assuming the end-user granted access, the authorization server 408 redirects the user-agent back to the client to the redirection 409 URI provided earlier. The authorization includes an 410 authorization code for the client to use to obtain an access 411 token. 413 (D) The client requests an access token from the authorization 414 server by authenticating and including the authorization code 415 received in the previous step as described in Section 4. 417 (E) The authorization server validates the client credentials and 418 the authorization code and responds back with the access token. 420 1.4.2. User-Agent 422 The user-agent profile is suitable for client applications residing 423 in a user-agent, typically implemented in a browser using a scripting 424 language such as JavaScript. These clients cannot keep client 425 secrets confidential and the authentication of the client is based on 426 the user-agent's same-origin policy. 428 Unlike other profiles in which the client makes a separate end-user 429 authorization request and an access token requests, the client 430 receives the access token as a result of the end-user authorization 431 request in the form of an HTTP redirection. The client requests the 432 authorization server to redirect the user-agent to another web server 433 or local resource accessible to the user-agent which is capable of 434 extracting the access token from the response and passing it to the 435 client. 437 This user-agent profile does not utilize the client secret since the 438 client executables reside on the end-user's computer or device which 439 makes the client secret accessible and exploitable. Because the 440 access token is encoded into the redirection URI, it may be exposed 441 to the end-user and other applications residing on the computer or 442 device. 444 +----------+ Client Identifier +----------------+ 445 | |>---(A)-- & Redirection URI --->| | 446 | | | | 447 End <--+ - - - +----(B)-- User authenticates -->| Authorization | 448 User | | | Server | 449 | |<---(C)--- Redirect URI -------<| | 450 | Client | with Access Token | | 451 | in | in Fragment +----------------+ 452 | Browser | 453 | | +----------------+ 454 | |>---(D)--- Redirect URI ------->| | 455 | | without Fragment | Web Server | 456 | | | with Client | 457 | (F) |<---(E)--- Web Page with ------<| Resource | 458 | Access | Script | | 459 | Token | +----------------+ 460 +----------+ 462 Figure 5: User-Agent Flow 464 The user-agent flow illustrated in Figure 5 includes the following 465 steps: 467 (A) The client sends the user-agent to the end-user authorization 468 endpoint as described in Section 3. The client includes its 469 client identifier, requested scope, local state, and a redirect 470 URI to which the authorization server will send the end-user 471 back once authorization is granted (or denied). 473 (B) The authorization server authenticates the end-user (via the 474 user-agent) and establishes whether the end-user grants or 475 denies the client's access request. 477 (C) If the end-user granted access, the authorization server 478 redirects the user-agent to the redirection URI provided 479 earlier. The redirection URI includes the access token in the 480 URI fragment. 482 (D) The user-agent follows the redirection instructions by making a 483 request to the web server which does not include the fragment. 484 The user-agent retains the fragment information locally. 486 (E) The web server returns a web page (typically an HTML page with 487 an embedded script) capable of accessing the full redirection 488 URI including the fragment retained by the user-agent, and 489 extracting the access token (and other parameters) contained in 490 the fragment. 492 (F) The user-agent executes the script provided by the web server 493 locally, which extracts the access token and passes it to the 494 client. 496 1.4.3. Native Application 498 Native application are clients running as native code on the end- 499 user's computer or device (i.e. executing outside a user-agent or as 500 a desktop program). These clients are often capable of interacting 501 with (or embedding) the end-user's user-agent but are limited in how 502 such interaction affects their end-user experience. In many cases, 503 native applications are incapable of receiving direct callback 504 requests from the server (e.g. firewall, operating system 505 restrictions). 507 Native application clients can be implemented in different ways based 508 on their requirements and desired end-user experience. Native 509 application clients can: 511 o Utilize the end-user authorization endpoint as described in 512 Section 3 by launching an external user-agent. The client can 513 capture the response by providing a redirection URI with a custom 514 URI scheme (registered with the operating system to invoke the 515 client application), or by providing a redirection URI pointing to 516 a server-hosted resource under the client's control which makes 517 the response available to the client (e.g. using the window title 518 or other locations accessible from outside the user-agent). 520 o Utilize the end-user authorization endpoint as described in 521 Section 3 by using an embedded user-agent. The client obtains the 522 response by directly communicating with the embedded user-agent. 524 o Prompt end-users for their basic credentials (username and 525 password) and use them directly to obtain an access token. This 526 is generally discouraged as it hands the end-user's password 527 directly to the 3rd party and is limited to basic credentials. 529 When choosing between launching an external browser and an embedded 530 user-agent, developers should consider the following: 532 o External user-agents may improve completion rate as the end-user 533 may already be logged-in and not have to re-authenticate. 535 o Embedded user-agents often offer a better end-user flow, as they 536 remove the need to switch context and open new windows. 538 o Embedded user-agents pose a security challenge because users are 539 authenticating in an unidentified window without access to the 540 visual protections offered by many user-agents. 542 1.4.4. Autonomous 544 Autonomous clients utilize an existing trust relationship or 545 framework to establish authorization. Autonomous clients can be 546 implemented in different ways based on their requirements and the 547 existing trust framework they rely upon. Autonomous clients can: 549 o Obtain an access token by authenticating with the authorization 550 server using their client credentials. The scope of the access 551 token is limited to the protected resources under the control of 552 the client, or that of another resource owner previously arranged 553 with the authorization server. 555 o Use an existing access grant expressed as an assertion using an 556 assertion format supported by the authorization server. Using 557 assertions requires the client to obtain a assertion (such as a 558 SAML [OASIS.saml-core-2.0-os] assertion) from an assertion issuer 559 or to self-issue an assertion. The assertion format, the process 560 by which the assertion is obtained, and the method of validating 561 the assertion are defined by the assertion issuer and the 562 authorization server, and are beyond the scope of this 563 specification. 565 2. Client Credentials 567 When interacting with the authorization server, the client identifies 568 itself using a set of client credentials. The client credentials 569 include a client identifier and MAY include a secret or other means 570 for the authorization server to authenticate the client. 572 The means through which the client obtains its credentials are beyond 573 the scope of this specification, but usually involve registration 574 with the authorization server. [[ OAuth Discovery provides one way of 575 obtaining basic client credentials ]] 577 Due to the nature of some clients, authorization servers SHOULD NOT 578 make assumptions about the confidentiality of client credentials 579 without establishing trust with the client operator. Authorization 580 servers SHOULD NOT issue client secrets to clients incapable of 581 keeping their secrets confidential. 583 This specification provides one mechanism for authenticating the 584 client using a set of basic client credentials. The authorization 585 server MAY authenticate the client using any desired authentication 586 scheme. 588 The client MUST NOT include more than one set of client credentials 589 with each request, and MUST NOT utilize more than one mechanism to 590 authenticate each request (regardless whether the credentials are 591 identical). 593 2.1. Basic Client Credentials 595 The basic client credentials include a client identifier and an 596 OPTIONAL matching shared symmetric secret. The client identifier and 597 secret are included in the request using the HTTP Basic 598 authentication scheme as defined in [RFC2617] by including the client 599 identifier as the username and secret as the password. 601 For example (line breaks are for display purposes only): 603 POST /token HTTP/1.1 604 Host: server.example.com 605 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 606 Content-Type: application/x-www-form-urlencoded 608 type=web-server&code=i1WsRn1uB1& 609 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 611 Alternatively, the client MAY include the credentials using the 612 following request parameters: 614 client_id 615 REQUIRED. The client identifier. 617 client_secret REQUIRED if the client identifier has a matching 618 secret. 620 For example (line breaks are for display purposes only): 622 POST /token HTTP/1.1 623 Host: server.example.com 624 Content-Type: application/x-www-form-urlencoded 626 type=web-server&client_id=s6BhdRkqt3& 627 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 628 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 630 The authorization server MUST accept the client credentials using 631 both the request parameters, and the HTTP Basic authentication 632 scheme. The authorization server MAY support additional 633 authentication schemes suitable for the transmission of a username 634 and password. 636 3. Obtaining End-User Authorization 638 When the client interacts with an end-user, the end-user MUST first 639 grant the client authorization to access its protected resources. 640 Once obtained, the end-user access grant is expressed as an 641 authorization code which the client uses to obtain an access token. 642 To obtain an end-user authorization, the client sends the end-user to 643 the end-user authorization endpoint. 645 At the end-user authorization endpoint, the end-user first 646 authenticates with the authorization server, and then grants or 647 denies the access request. The way in which the authorization server 648 authenticates the end-user (e.g. username and password login, OpenID, 649 session cookies) and in which the authorization server obtains the 650 end-user's authorization, including whether it uses a secure channel 651 such as TLS, is beyond the scope of this specification. However, the 652 authorization server MUST first verify the identity of the end-user. 654 The location of the end-user authorization endpoint can be found in 655 the service documentation, or can be obtained by using [[ OAuth 656 Discovery ]]. The end-user authorization endpoint URI MAY include a 657 query component as defined by [RFC3986] section 3, which must be 658 retained when adding additional query parameters. 660 Since requests to the end-user authorization endpoint result in user 661 authentication and the transmission of sensitive information, the 662 authorization server SHOULD require the use of a transport-layer 663 security mechanism such as TLS when sending requests to the end-user 664 authorization endpoint. 666 In order to direct the end-user's user-agent to the authorization 667 server, the client constructs the request URI by adding the following 668 parameters to the end-user authorization endpoint URI query component 669 using the "application/x-www-form-urlencoded" format as defined by 670 [W3C.REC-html401-19991224]: 672 response_type 673 REQUIRED. The requested response: an access token, an 674 authorization code, or both. The parameter value MUST be set 675 to "token" for requesting an access token, "code" for 676 requesting an authorization code, or "code-and-token" to 677 request both. The authorization server MAY decline to provide 678 one or more of these response types. [[ The 'code-and-token' 679 type is pending use cases and may be removed for the 680 specification ]] 682 client_id 683 REQUIRED. The client identifier as described in Section 2. 685 redirect_uri 686 REQUIRED, unless a redirection URI has been established between 687 the client and authorization server via other means. An 688 absolute URI to which the authorization server will redirect 689 the user-agent to when the end-user authorization step is 690 completed. The authorization server SHOULD require the client 691 to pre-register their redirection URI. 693 scope 694 OPTIONAL. The scope of the access request expressed as a list 695 of space-delimited strings. The value of the "scope" parameter 696 is defined by the authorization server. If the value contains 697 multiple space-delimited strings, their order does not matter, 698 and each string adds an additional access range to the 699 requested scope. 701 state 702 OPTIONAL. An opaque value used by the client to maintain state 703 between the request and callback. The authorization server 704 includes this value when redirecting the user-agent back to the 705 client. 707 The client directs the end-user to the constructed URI using an HTTP 708 redirection response, or by other means available to it via the end- 709 user's user-agent. The request MUST use the HTTP "GET" method. 711 For example, the client directs the end-user's user-agent to make the 712 following HTTP request using transport-layer security (line breaks 713 are for display purposes only): 715 GET /authorize?response_type=code&client_id=s6BhdRkqt3& 716 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 717 Host: server.example.com 719 If the client has previously registered a redirection URI with the 720 authorization server, the authorization server MUST verify that the 721 redirection URI received matches the registered URI associated with 722 the client identifier. [[ provide guidance on how to perform matching 723 ]] 724 Parameters sent without a value MUST be treated as if they were 725 omitted from the request. 727 The authorization server validates the request to ensure all required 728 parameters are present and valid. If the request is invalid, the 729 authorization server immediately redirects the user-agent back to the 730 client using the redirection URI provided with the appropriate error 731 code as described in Section 3.2. 733 The authorization server authenticates the end-user and obtains an 734 authorization decision (by asking the end-user or by establishing 735 approval via other means). When a decision has been established, the 736 authorization server directs the end-user's user-agent to the 737 provided client redirection URI using an HTTP redirection response, 738 or by other means available to it via the end-user's user-agent. 740 3.1. Authorization Response 742 If the end-user grants the access request, the authorization server 743 issues an access token, an authorization code, or both, and delivers 744 them to the client by adding the following parameters to the 745 redirection URI (as described below): 747 code 748 REQUIRED if the response type is "token" or "code-and-token", 749 otherwise MUST NOT be included. The authorization code 750 generated by the authorization server. The authorization code 751 SHOULD expire shortly after it is issued. The authorization 752 server MUST invalidate the authorization code after a single 753 usage. The authorization code is bound to the client 754 identifier and redirection URI. 756 access_token 757 REQUIRED if the response type is "token" or "code-and-token", 758 otherwise MUST NOT be included. The access token. 760 expires_in 761 OPTIONAL. The duration in seconds of the access token lifetime 762 if an access token is included. For example, the value "3600" 763 denotes that the access token will expire in one hour from the 764 time the response was generated by the authorization server. 766 scope 767 OPTIONAL. The scope of the access token as a list of space- 768 delimited strings if an access token is included. The value of 769 the "scope" parameter is defined by the authorization server. 770 If the value contains multiple space-delimited strings, their 771 order does not matter, and each string adds an additional 772 access range to the requested scope. 774 state 775 REQUIRED if the "state" parameter was present in the client 776 authorization request. Set to the exact value received from 777 the client. 779 The method in which the authorization server adds the parameter to 780 the redirection URI is determined by the response type requested by 781 the client in the authorization request using the "response_type" 782 parameter. 784 If the response type is "code", the authorization server adds the 785 parameters to the redirection URI query component using the 786 "application/x-www-form-urlencoded" format as defined by 787 [W3C.REC-html401-19991224]. 789 For example, the authorization server redirects the end-user's user- 790 agent by sending the following HTTP response: 792 HTTP/1.1 302 Found 793 Location: https://client.example.com/cb?code=i1WsRn1uB1 795 If the response type is "token", the authorization server adds the 796 parameters to the redirection URI fragment component using the 797 "application/x-www-form-urlencoded" format as defined by 798 [W3C.REC-html401-19991224]. 800 For example, the authorization server redirects the end-user's user- 801 agent by sending the following HTTP response: 803 HTTP/1.1 302 Found 804 Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600 806 If the response type is "code-and-token", the authorization server 807 adds the "code" and "state" parameters to the redirection URI query 808 component and the "access_token", "scope", and "expires_in" to the 809 redirection URI fragment using the 810 "application/x-www-form-urlencoded" format as defined by 811 [W3C.REC-html401-19991224]. 813 For example, the authorization server redirects the end-user's user- 814 agent by sending the following HTTP response (line breaks are for 815 display purposes only): 817 HTTP/1.1 302 Found 818 Location: http://example.com/rd?code=i1WsRn1uB1 819 #access_token=FJQbwq9&expires_in=3600 821 The sizes of tokens and other values received from the authorization 822 server, are left undefined by this specification. Clients should 823 avoid making assumptions about value sizes. Servers should document 824 the expected size of any value they issue. 826 3.2. Error Response 828 If the end-user denies the access request or if the request is 829 invalid, the authorization server informs the client by adding the 830 following parameters to the redirection URI query component using the 831 "application/x-www-form-urlencoded" format as defined by 832 [W3C.REC-html401-19991224]: 834 error 835 REQUIRED. A single error code as described in Section 3.2.1. 837 error_description OPTIONAL. A human-readable text providing 838 additional information, used to assist in the understanding and 839 resolution of the error occurred. 841 error_uri OPTIONAL. A URI identifying a human-readable web page 842 with information about the error, used to provide the end-user 843 with additional information about the error. 845 state 846 REQUIRED if the "state" parameter was present in the client 847 authorization request. Set to the exact value received from 848 the client. 850 For example, the authorization server redirects the end-user's user- 851 agent by sending the following HTTP response: 853 HTTP/1.1 302 Found 854 Location: https://client.example.com/cb?error=access-denied 856 3.2.1. Error Codes 858 The authorization server includes one of the following error codes 859 with the error response: 861 invalid-request 862 The request is missing a required parameter, includes an 863 unknown parameter or parameter value, or is otherwise 864 malformed. 866 invalid-client-id 867 The client identifier provided is invalid. 869 unauthorized-client 870 The client is not authorized to use the requested response 871 type. 873 redirect-uri-mismatch 874 The redirection URI provided does not match a pre-registered 875 value. 877 access-denied 878 The end-user or authorization server denied the request. 880 unsupported-response-type 881 The requested response type is not supported by the 882 authorization server. 884 invalid_scope 885 The requested scope is invalid, unknown, or malformed. 887 [[ Add mechanism for extending error codes ]] 889 4. Obtaining an Access Token 891 The client obtains an access token by authenticating with the 892 authorization server and presenting its access grant. 894 After establishing resource owner authorization, clients request an 895 access token from the authorization server's token endpoint. When 896 requesting an access token, the client authenticates with the 897 authorization server and includes the access grant (in the form of an 898 authorization code, resource owner credentials, an assertion, or a 899 refresh token). 901 The location of the token endpoint can be found in the service 902 documentation, or can be obtained by using [[ OAuth Discovery ]]. 904 The token endpoint URI MAY include a query component. 906 Since requests to the token endpoint result in the transmission of 907 plain text credentials in the HTTP request and response, the 908 authorization server MUST require the use of a transport-layer 909 security mechanism when sending requests to the token endpoints. 910 Servers MUST support TLS 1.2 as defined in [RFC5246], and MAY support 911 additional transport-layer security mechanisms. 913 The client requests an access token by constructing a token request 914 and making an HTTP "POST" request. The client constructs the request 915 URI by adding its client credentials to the request as described in 916 Section 2, and includes the following parameters using the 917 "application/x-www-form-urlencoded" format in the HTTP request 918 entity-body: 920 grant_type 921 REQUIRED. The access grant type included in the request. 922 Value MUST be one of "authorization-code", "basic-credentials", 923 "assertion", "refresh-token", or "none". 925 scope 926 OPTIONAL. The scope of the access request expressed as a list 927 of space-delimited strings. The value of the "scope" parameter 928 is defined by the authorization server. If the value contains 929 multiple space-delimited strings, their order does not matter, 930 and each string adds an additional access range to the 931 requested scope. If the access grant being used already 932 represents an approved scope (e.g. authorization code, 933 assertion), the requested scope MUST be equal or lesser than 934 the scope previously granted. 936 In addition, the client MUST include the appropriate parameters 937 listed for the selected access grant type as described in 938 Section 4.1. 940 Parameters sent without a value MUST be treated as if they were 941 omitted from the request. 943 4.1. Access Grant Types 945 The client requests an access token using one of the four types of 946 access grants: authorization code, basic credentials, assertion, or 947 refresh token. 949 When requesting an access token using the "none" access grant type 950 (no access grant is included), the client is requesting access to the 951 protected resources under its control, or those of another resource 952 owner which has been previously arranged with the authorization 953 server (the method of which is beyond the scope of this 954 specification). 956 4.1.1. Authorization Code 958 The client includes the authorization code using the 959 "authorization-code" access grant type and the following parameters: 961 code 962 REQUIRED. The authorization code received from the 963 authorization server. 965 redirect_uri 966 REQUIRED. The redirection URI used in the initial request. 968 For example, the client makes the following HTTP request using 969 transport-layer security (line breaks are for display purposes only): 971 POST /token HTTP/1.1 972 Host: server.example.com 973 Content-Type: application/x-www-form-urlencoded 975 grant_type=authorization-code&client_id=s6BhdRkqt3& 976 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 977 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 979 The authorization server MUST verify that the authorization code, 980 client identity, client secret, and redirection URI are all valid and 981 match its stored association. If the request is valid, the 982 authorization server issues a successful response as described in 983 Section 4.2. 985 4.1.2. Resource Owner Basic Credentials 987 The client includes the resource owner credentials using the 988 "basic-credentials" access grant type and the following parameters: 989 [[ add internationalization consideration for username and password 990 ]] 992 username 993 REQUIRED. The end-user's username. 995 password 996 REQUIRED. The end-user's password. 998 For example, the client makes the following HTTP request using 999 transport-layer security (line breaks are for display purposes only): 1001 POST /token HTTP/1.1 1002 Host: server.example.com 1003 Content-Type: application/x-www-form-urlencoded 1005 grant_type=basic-credentials&client_id=s6BhdRkqt3& 1006 client_secret=47HDu8s&username=johndoe&password=A3ddj3w 1008 The authorization server MUST validate the client credentials and 1009 end-user credentials and if valid issues an access token response as 1010 described in Section 4.2. 1012 4.1.3. Assertion 1014 The client includes the assertion using the "assertion" access grant 1015 type and the following parameters: 1017 assertion_type 1018 REQUIRED. The format of the assertion as defined by the 1019 authorization server. The value MUST be an absolute URI. 1021 assertion 1022 REQUIRED. The assertion. 1024 For example, the client makes the following HTTP request using 1025 transport-layer security (line breaks are for display purposes only): 1027 POST /token HTTP/1.1 1028 Host: server.example.com 1029 Content-Type: application/x-www-form-urlencoded 1031 grant_type=assertion&client_id=s6BhdRkqt3&client_secret=diejdsks& 1032 assertion_type=urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Aassertion& 1033 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D 1035 The authorization server MUST validate the assertion and if valid 1036 issues an access token response as described in Section 4.2. The 1037 authorization server SHOULD NOT issue a refresh token. 1039 Authorization servers SHOULD issue access tokens with a limited 1040 lifetime and require clients to refresh them by requesting a new 1041 access token using the same assertion if it is still valid. 1042 Otherwise the client MUST obtain a new valid assertion. 1044 4.1.4. Refresh Token 1046 The client includes the refresh token using the "refresh-token" 1047 access grant type and the following parameter: 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 HTTP request using 1054 transport-layer security (line break 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 grant_type=refresh-token&client_id=s6BhdRkqt3& 1061 client_secret=8eSEIpnqmM&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 4.2. The authorization server MAY issue a new refresh token. 1069 4.2. Access Token Response 1071 After receiving and verifying a valid and authorized access token 1072 request from the client, the authorization server issues the access 1073 token and optional refresh token, and constructs the response by 1074 adding the following parameters to the entity body of the HTTP 1075 response with a 200 (OK) status code: 1077 The token response contains the following parameters: 1079 access_token 1080 REQUIRED. The access token issued by the authorization server. 1082 expires_in 1083 OPTIONAL. The duration in seconds of the access token 1084 lifetime. For example, the value "3600" denotes that the 1085 access token will expire in one hour from the time the response 1086 was generated by the authorization server. 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 4.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 The sizes of tokens and other values received from the authorization 1125 server, are left undefined by this specification. Clients should 1126 avoid making assumptions about value sizes. Servers should document 1127 the expected size of any value they issue. 1129 4.3. Error Response 1131 If the token request is invalid or unauthorized, the authorization 1132 server constructs the response by adding the following parameter to 1133 the entity body of the HTTP response using the "application/json" 1134 media type: 1136 error 1137 REQUIRED. A single error code as described in Section 4.3.1. 1139 error_description OPTIONAL. A human-readable text providing 1140 additional information, used to assist in the understanding and 1141 resolution of the error occurred. 1143 error_uri OPTIONAL. A URI identifying a human-readable web page 1144 with information about the error, used to provide the end-user 1145 with additional information about the error. 1147 For example: 1149 HTTP/1.1 400 Bad Request 1150 Content-Type: application/json 1151 Cache-Control: no-store 1153 { 1154 "error":"invalid-request" 1155 } 1157 If the client provided invalid credentials using an HTTP 1158 authentication scheme via the "Authorization" request header field, 1159 the authorization server MUST respond with the HTTP 401 1160 (Unauthorized) status code. Otherwise, the authorization server 1161 SHALL respond with the HTTP 400 (Bad Request) status code. 1163 4.3.1. Error Codes 1165 The authorization server includes one of the following error codes 1166 with the error response: 1168 invalid-request 1169 The request is missing a required parameter, includes an 1170 unknown parameter or parameter value, repeats a parameter, 1171 includes multiple credentials, utilizes more than one mechanism 1172 for authenticating the client, or is otherwise malformed. 1174 invalid-client-credentials 1175 The client identifier provided is invalid, the client failed to 1176 authenticate, or the client provided multiple client 1177 credentials. 1179 unauthorized-client 1180 The client is not authorized to use the access grant type 1181 provided. 1183 invalid-grant 1184 The provided access grant is invalid, expired, or revoked (e.g. 1185 invalid assertion, expired authorization token, bad end-user 1186 basic credentials, or mismatching authorization code and 1187 redirection URI). 1189 unsupported-grant-type 1190 The access grant included - its type or another attribute - is 1191 not supported by the authorization server. 1193 invalid-scope 1194 The requested scope is invalid, unknown, malformed, or exceeds 1195 the previously granted scope. 1197 [[ Add mechanism for extending error codes ]] 1199 5. Accessing a Protected Resource 1201 Clients access protected resources by presenting an access token to 1202 the resource server. Access tokens act as bearer tokens, where the 1203 token string acts as a shared symmetric secret. This requires 1204 treating the access token with the same care as other secrets (e.g. 1205 end-user passwords). Access tokens SHOULD NOT be sent in the clear 1206 over an insecure channel. 1208 However, when it is necessary to transmit access tokens in the clear 1209 without a secure channel, authorization servers SHOULD issue access 1210 tokens with limited scope and lifetime to reduce the potential risk 1211 from a compromised access token. 1213 Clients MUST NOT make authenticated requests with an access token to 1214 unfamiliar resource servers, regardless of the presence of a secure 1215 channel. 1217 The resource server MUST validate the access token and ensure it has 1218 not expired and that its scope covers the requested resource. The 1219 methods used by the resource server to validate the access token are 1220 beyond the scope of this specification, but generally involve an 1221 interaction or coordination between the resource server and 1222 authorization server. 1224 5.1. Authenticated Requests 1226 Clients make authenticated token requests using the "Authorization" 1227 request header field as described in Section 5.1.1. Alternatively, 1228 clients MAY include the access token using the HTTP request URI in 1229 the query component as described in Section 5.1.2, or in the HTTP 1230 body when using the "application/x-www-form-urlencoded" content type 1231 as described in Section 5.1.3. 1233 Clients SHOULD only use the request URI or body when the 1234 "Authorization" request header field is not available, and MUST NOT 1235 use more than one method in each request. 1237 5.1.1. The Authorization Request Header Field 1239 The "Authorization" request header field is used by clients to make 1240 authenticated token requests. The client uses the "token" attribute 1241 to include the access token in the request. 1243 For example: 1245 GET /resource HTTP/1.1 1246 Host: server.example.com 1247 Authorization: Token token="vF9dft4qmT" 1249 The "Authorization" header field uses the framework defined by 1250 [RFC2617] as follows: 1252 credentials = "Token" RWS access-token [ CS 1#auth-param ] 1253 access-token = "token" "=" <"> token <"> 1254 CS = OWS "," OWS 1256 5.1.2. URI Query Parameter 1258 When including the access token in the HTTP request URI, the client 1259 adds the access token to the request URI query component as defined 1260 by [RFC3986] using the "oauth_token" parameter. 1262 For example, the client makes the following HTTP request using 1263 transport-layer security: 1265 GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 1266 Host: server.example.com 1268 The HTTP request URI query can include other request-specific 1269 parameters, in which case, the "oauth_token" parameters SHOULD be 1270 appended following the request-specific parameters, properly 1271 separated by an "&" character (ASCII code 38). 1273 For example: 1275 http://example.com/resource?x=y&oauth_token=vF9dft4qmT 1277 5.1.3. Form-Encoded Body Parameter 1279 When including the access token in the HTTP request entity-body, the 1280 client adds the access token to the request body using the 1281 "oauth_token" parameter. The client can use this method only if the 1282 following REQUIRED conditions are met: 1284 o The entity-body is single-part. 1286 o The entity-body follows the encoding requirements of the 1287 "application/x-www-form-urlencoded" content-type as defined by 1288 [W3C.REC-html401-19991224]. 1290 o The HTTP request entity-header includes the "Content-Type" header 1291 field set to "application/x-www-form-urlencoded". 1293 o The HTTP request method is "POST", "PUT", or "DELETE". 1295 The entity-body can include other request-specific parameters, in 1296 which case, the "oauth_token" parameters SHOULD be appended following 1297 the request-specific parameters, properly separated by an "&" 1298 character (ASCII code 38). 1300 For example, the client makes the following HTTP request using 1301 transport-layer security: 1303 POST /resource HTTP/1.1 1304 Host: server.example.com 1305 Content-Type: application/x-www-form-urlencoded 1307 oauth_token=vF9dft4qmT 1309 5.2. The WWW-Authenticate Response Header Field 1311 If the protected resource request contains an invalid access token or 1312 is malformed, the resource server MUST include the HTTP 1313 "WWW-Authenticate" response header field. The "WWW-Authenticate" 1314 header field uses the framework defined by [RFC2617] as follows: 1316 challenge = "Token" RWS token-challenge 1318 token-challenge = realm 1319 [ CS error ] 1320 [ CS error-desc ] 1321 [ CS error-uri ] 1322 [ CS scope ] 1323 [ CS 1#auth-param ] 1325 error = "error" "=" <"> token <"> 1326 error-desc = "error-description" "=" quoted-string 1327 error-uri = "error-uri" = <"> URI-Reference <"> 1328 scope = ptoken / <"> ptoken *( 1*SP ptoken ) <"> 1330 ptoken = 1*ptokenchar 1331 ptokenchar = "!" / "#" / "$" / "%" / "&" / "'" / "(" 1332 / ")" / "*" / "+" / "-" / "." / "/" / DIGIT 1333 / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA 1334 / "[" / "]" / "^" / "_" / "`" / "{" / "|" 1335 / "}" / "~" 1337 For example: 1339 HTTP/1.1 401 Unauthorized 1340 WWW-Authenticate: Token realm='Example Service', error='expired-token' 1341 The "realm" attribute is used to provide the protected resources 1342 partition as defined by [RFC2617]. [[ add explanation ]] 1344 The "error" attribute is used to provide the client with the reason 1345 why the access request was declined. The parameter values are 1346 described in Section 5.2.1. 1348 The "error-description" attribute provides a human-readable text 1349 containing additional information, used to assist in the 1350 understanding and resolution of the error occurred. 1352 The "error-uri" attribute provides a URI identifying a human-readable 1353 web page with information about the error, used to offer the end-user 1354 with additional information about the error. If the value is not an 1355 absolute URI, it is relative to the URI of the requested protected 1356 resource. 1358 The "scope" attribute is a space-delimited list of scope values 1359 indicating the required scope of the access token for accessing the 1360 requested resource. 1362 5.2.1. Error Codes 1364 The authorization server includes one of the following error codes 1365 with the error response: 1367 invalid-request 1368 The request is missing a required parameter, includes an 1369 unknown parameter or parameter value, repeats the same 1370 parameter, uses more than one method for including an access 1371 token, or is otherwise malformed. The resource server MUST 1372 respond with the HTTP 400 (Bad Request) status code. 1374 invalid-token 1375 The access token provided is invalid. Resource servers SHOULD 1376 use this error code when receiving an expired token which 1377 cannot be refreshed to indicate to the client that a new 1378 authorization is necessary. The resource server MUST respond 1379 with the HTTP 401 (Unauthorized) status code. 1381 expired-token 1382 The access token provided has expired. Resource servers SHOULD 1383 only use this error code when the client is expected to be able 1384 to handle the response and request a new access token using the 1385 refresh token issued with the expired access token. The 1386 resource server MUST respond with the HTTP 401 (Unauthorized) 1387 status code. 1389 insufficient-scope 1390 The request requires higher privileges than provided by the 1391 access token. The resource server SHOULD respond with the HTTP 1392 403 (Forbidden) status code and MAY include the "scope" 1393 attribute with the scope necessary to access the protected 1394 resource. 1396 [[ Add mechanism for extending error codes ]] 1398 If the request lacks any authentication information (i.e. the client 1399 was unaware authentication is necessary), the resource server SHOULD 1400 not include an error code or other error information. 1402 For example: 1404 HTTP/1.1 401 Unauthorized 1405 WWW-Authenticate: Token realm='Example Service' 1407 6. Extensibility 1409 6.1. Defining New Client Credentials Types 1411 [[ TBD ]] 1413 6.2. Defining New Endpoint Parameters 1415 Applications that wish to define new request or response parameters 1416 for use with the end-user authorization endpoint or the token 1417 endpoint SHALL do so in one of two ways: register them in the 1418 parameters registry (following the procedures in Section 8.1), or use 1419 the "x_" parameter name prefix. 1421 Parameters utilizing the "x_" parameter name prefix MUST be limited 1422 to vendor-specific extensions that are not commonly applicable, and 1423 are specific to the implementation details of the authorization 1424 server where they are used. All other new parameters MUST be 1425 registered, and MUST NOT use the "x_" parameter name prefix. 1427 Parameter names MUST conform to the param-name ABNF, and parameter 1428 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1429 to the syntax of an existing parameter). 1431 param-name = 1*fchar 1432 fchar = "-" / "." / "_" / DIGIT / ALPHA 1434 6.3. Defining New Header Field Parameters 1436 Applications that wish to define new parameters for use in the OAuth 1437 "Authorization" or "WWW-Authenticate" header fields MUST register 1438 them in the parameters registry, following the procedures in 1439 Section 8.1. 1441 Parameter names MUST conform to the param-name ABNF and MUST NOT 1442 begin with "x_". Parameter values MUST conform to the param-value 1443 ABNF and their syntax MUST be well-defined (e.g., using ABNF, or a 1444 reference to the syntax of an existing parameter). 1446 param-value = ptoken | quoted-string 1448 6.4. Defining New Access Grant Types 1450 The assertion access grant type was designed to allow the 1451 authorization server to accept additional access grants not 1452 specified. Applications that wish to define additional access grant 1453 types can do so by utilizing a new or existing assertion type and 1454 format. 1456 7. Security Considerations 1458 [[ TBD ]] 1460 8. IANA Considerations 1462 8.1. The OAuth Parameters Registry 1464 This document establishes the OAuth parameters registry. 1466 Additional parameters to be use in the end-user authorization 1467 endpoint request, the end-user authorization endpoint response, the 1468 token endpoint request, the token endpoint response, the 1469 "Authorization" header field, or the "WWW-Authenticate" header field, 1470 are registered on the advice of one or more Designated Experts 1471 (appointed by the IESG or their delegate), with a Specification 1472 Required (using terminology from [RFC5226]). However, to allow for 1473 the allocation of values prior to publication, the Designated 1474 Expert(s) may approve registration once they are satisfied that such 1475 a specification will be published. 1477 Registration requests should be sent to the [TBD]@ietf.org mailing 1478 list for review and comment, with an appropriate subject (e.g., 1479 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 1480 the mailing list should be determined in consultation with the IESG 1481 and IANA. Suggested name: oauth-ext-review. ]] 1483 Before a period of 14 days has passed, the Designated Expert(s) will 1484 either approve or deny the registration request, communicating this 1485 decision both to the review list and to IANA. Denials should include 1486 an explanation and, if applicable, suggestions as to how to make the 1487 request successful. Registration requests that are undetermined for 1488 a period longer than 21 days can be brought to the IESG's attention 1489 (using the iesg@iesg.org mailing list) for resolution. 1491 8.1.1. Registration Template 1493 Parameter name: The name requested (e.g., "example"). 1495 Parameter usage location: The location(s) where parameter can be 1496 used. The possible locations are: the end-user authorization 1497 endpoint request, the end-user authorization endpoint response, 1498 the token endpoint request, the token endpoint response, the 1499 "Authorization" header field, or the "WWW-Authenticate" header 1500 field. 1502 Change controller: For standards-track RFCs, state "IETF". For 1503 others, give the name of the responsible party. Other details 1504 (e.g., postal address, e-mail address, home page URI) may also be 1505 included. 1507 Specification document(s): Reference to document that specifies the 1508 parameter, preferably including a URI that can be used to retrieve 1509 a copy of the document. An indication of the relevant sections 1510 may also be included, but is not required. 1512 Related information: Optionally, citations to additional documents 1513 containing further relevant information. 1515 8.1.2. Example 1517 The following is the parameter registration request for the "scope" 1518 parameter as defined in this specification: 1520 Parameter name: scope 1522 Parameter usage location: The end-user authorization endpoint 1523 request, the end-user authorization endpoint response, the token 1524 endpoint request, the token endpoint response, and the 1525 "WWW-Authenticate" header field. 1527 Change controller: IETF 1529 Specification document(s): [[ this document ]] 1531 Related information: None 1533 Appendix A. Examples 1535 [[ TBD ]] 1537 Appendix B. Contributors 1539 The following people contributed to preliminary versions of this 1540 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland 1541 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 1542 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 1543 concepts within are a product of the OAuth community, WRAP community, 1544 and the OAuth Working Group. 1546 The OAuth Working Group has dozens of very active contributors who 1547 proposed ideas and wording for this document, including: [[ If your 1548 name is missing or you think someone should be added here, please 1549 send Eran a note - don't be shy ]] 1551 Michael Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah 1552 Culver, Brian Ellin, Igor Faynberg, George Fletcher, Evan Gilbert, 1553 Justin Hart, John Kemp, Chasen Le Hara, Torsten Lodderstedt, Eve 1554 Maler, James Manger, Laurence Miao, Chuck Mortimore, Justin Richer, 1555 Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Justin 1556 Smith, Jeremy Suriel, and Franklin Tse. 1558 Appendix C. Acknowledgements 1560 [[ Add OAuth 1.0a authors + WG contributors ]] 1562 Appendix D. Document History 1564 [[ to be removed by RFC editor before publication as an RFC ]] 1566 -09 1568 o Fixed typos, editorial changes. 1570 o Added token expiration example. 1572 o Added scope parameter to end-user authorization endpoint response. 1574 o Added note about parameters with empty values (same as omitted). 1576 o Changed parameter values to use '-' instead of '_'. Parameter 1577 names still use '_'. 1579 o Changed authorization endpoint client type to response type with 1580 values: code, token, and both. 1582 o Complete cleanup of error codes. Added support for error 1583 description and URI. 1585 o Add initial extensibility support. 1587 -08 1589 o Renamed verification code to authorization code. 1591 o Revised terminology, structured section, added new terms. 1593 o Changed flows to profiles and moved to introduction. 1595 o Added support for access token rescoping. 1597 o Cleaned up client credentials section. 1599 o New introduction overview. 1601 o Added error code for invalid username and password, and renamed 1602 error code to be more consistent. 1604 o Added access grant type parameter to token endpoint. 1606 -07 1608 o Major rewrite of entire document structure. 1610 o Removed device profile. 1612 o Added verification code support to user-agent flow. 1614 o Removed multiple formats support, leaving JSON as the only format. 1616 o Changed assertion "assertion_format" parameter to 1617 "assertion_type". 1619 o Removed "type" parameter from token endpoint. 1621 -06 1623 o Editorial changes, corrections, clarifications, etc. 1625 o Removed conformance section. 1627 o Moved authors section to contributors appendix. 1629 o Added section on native applications. 1631 o Changed error response to use the requested format. Added support 1632 for HTTP "Accept" header. 1634 o Flipped the order of the web server and user-agent flows. 1636 o Renamed assertion flow "format" parameter name to 1637 "assertion_format" to resolve conflict. 1639 o Removed the term identifier from token definitions. Added a 1640 cryptographic token definition. 1642 o Added figure titles. 1644 o Added server response 401 when client tried to authenticate using 1645 multiple credentials. 1647 o Clarified support for TLS alternatives, and added requirement for 1648 TLS 1.2 support for token endpoint. 1650 o Removed all signature and cryptography. 1652 o Removed all discovery. 1654 o Updated HTML4 reference. 1656 -05 1658 o Corrected device example. 1660 o Added client credentials parameters to the assertion flow as 1661 OPTIONAL. 1663 o Added the ability to send client credentials using an HTTP 1664 authentication scheme. 1666 o Initial text for the "WWW-Authenticate" header (also added scope 1667 support). 1669 o Change authorization endpoint to end-user endpoint. 1671 o In the device flow, change the "user_uri" parameter to 1672 "verification_uri" to avoid confusion with the end-user endpoint. 1674 o Add "format" request parameter and support for XML and form- 1675 encoded responses. 1677 -04 1679 o Changed all token endpoints to use "POST" 1681 o Clarified the authorization server's ability to issue a new 1682 refresh token when refreshing a token. 1684 o Changed the flow categories to clarify the autonomous group. 1686 o Changed client credentials language not to always be server- 1687 issued. 1689 o Added a "scope" response parameter. 1691 o Fixed typos. 1693 o Fixed broken document structure. 1695 -03 1697 o Fixed typo in JSON error examples. 1699 o Fixed general typos. 1701 o Moved all flows sections up one level. 1703 -02 1705 o Removed restriction on "redirect_uri" including a query. 1707 o Added "scope" parameter. 1709 o Initial proposal for a JSON-based token response format. 1711 -01 1712 o Editorial changes based on feedback from Brian Eaton, Bill Keenan, 1713 and Chuck Mortimore. 1715 o Changed device flow "type" parameter values and switch to use only 1716 the token endpoint. 1718 -00 1720 o Initial draft based on a combination of WRAP and OAuth 1.0a. 1722 9. References 1724 9.1. Normative References 1726 [I-D.ietf-httpbis-p1-messaging] 1727 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 1728 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 1729 "HTTP/1.1, part 1: URIs, Connections, and Message 1730 Parsing", draft-ietf-httpbis-p1-messaging-09 (work in 1731 progress), March 2010. 1733 [NIST FIPS-180-3] 1734 National Institute of Standards and Technology, "Secure 1735 Hash Standard (SHS). FIPS PUB 180-3, October 2008". 1737 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1738 Extensions (MIME) Part One: Format of Internet Message 1739 Bodies", RFC 2045, November 1996. 1741 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1742 Hashing for Message Authentication", RFC 2104, 1743 February 1997. 1745 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1746 Requirement Levels", BCP 14, RFC 2119, March 1997. 1748 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1749 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1750 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1752 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1753 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1754 Authentication: Basic and Digest Access Authentication", 1755 RFC 2617, June 1999. 1757 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1759 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 1760 Types", RFC 3023, January 2001. 1762 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1763 Standards (PKCS) #1: RSA Cryptography Specifications 1764 Version 2.1", RFC 3447, February 2003. 1766 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1767 10646", STD 63, RFC 3629, November 2003. 1769 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1770 Resource Identifier (URI): Generic Syntax", STD 66, 1771 RFC 3986, January 2005. 1773 [RFC4627] Crockford, D., "The application/json Media Type for 1774 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1776 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1777 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1778 May 2008. 1780 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1781 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1783 [W3C.REC-html401-19991224] 1784 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 1785 Specification", World Wide Web Consortium 1786 Recommendation REC-html401-19991224, December 1999, 1787 . 1789 9.2. Informative References 1791 [I-D.hammer-oauth] 1792 Hammer-Lahav, E., "The OAuth 1.0 Protocol", 1793 draft-hammer-oauth-10 (work in progress), February 2010. 1795 [I-D.hardt-oauth] 1796 Hardt, D., Tom, A., Eaton, B., and Y. Goland, "OAuth Web 1797 Resource Authorization Profiles", draft-hardt-oauth-01 1798 (work in progress), January 2010. 1800 [OASIS.saml-core-2.0-os] 1801 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1802 "Assertions and Protocol for the OASIS Security Assertion 1803 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1804 2.0-os, March 2005. 1806 Authors' Addresses 1808 Eran Hammer-Lahav (editor) 1809 Yahoo! 1811 Email: eran@hueniverse.com 1812 URI: http://hueniverse.com 1814 David Recordon 1815 Facebook 1817 Email: davidrecordon@facebook.com 1818 URI: http://www.davidrecordon.com/ 1820 Dick Hardt 1821 Microsoft 1823 Email: dick.hardt@gmail.com 1824 URI: http://dickhardt.org/