idnits 2.17.00 (12 Aug 2021) /tmp/idnits18678/draft-hardt-oauth-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 == Line 674 has weird spacing: '...itional par...' == Line 693 has weird spacing: '...itional par...' == Line 785 has weird spacing: '...itional par...' == Line 891 has weird spacing: '...itional par...' == Line 987 has weird spacing: '...itional par...' == (3 more instances...) == 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 'MUST not' in this paragraph: the Verification Code MUST not have expired -- The document date (January 15, 2010) is 4502 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.narten-iana-considerations-rfc2434bis' is defined on line 1479, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) == Outdated reference: draft-narten-iana-considerations-rfc2434bis has been published as RFC 5226 Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force D. Hardt, Ed. 3 Internet-Draft Microsoft 4 Intended status: Informational A. Tom 5 Expires: July 19, 2010 Yahoo! 6 B. Eaton 7 Google 8 Y. Goland 9 Microsoft 10 January 15, 2010 12 OAuth Web Resource Authorization Profiles 13 draft-hardt-oauth-01 15 Abstract 17 The OAuth Web Resource Authorization Profiles (OAuth WRAP) allow a 18 server hosting a Protected Resource to delegate authorization to one 19 or more authorities. An application (Client) accesses the Protected 20 Resource by presenting a short lived, opaque, bearer token (Access 21 Token) obtained from an authority (Authorization Server). There are 22 Profiles for how a Client may obtain an Access Token when acting 23 autonomously or on behalf of a User. 25 Status of this Memo 27 This Internet-Draft is submitted to IETF in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF), its areas, and its working groups. Note that 32 other groups may also distribute working documents as Internet- 33 Drafts. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 The list of current Internet-Drafts can be accessed at 41 http://www.ietf.org/ietf/1id-abstracts.txt. 43 The list of Internet-Draft Shadow Directories can be accessed at 44 http://www.ietf.org/shadow.html. 46 This Internet-Draft will expire on July 19, 2010. 48 Copyright Notice 49 Copyright (c) 2010 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the BSD License. 62 Table of Contents 64 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 1.1. Accessing a Protected Resource . . . . . . . . . . . . . . 5 66 1.2. Autonomous Client Profiles . . . . . . . . . . . . . . . . 6 67 1.3. User Delegation Profiles . . . . . . . . . . . . . . . . . 7 68 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 9 69 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 3.1. URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 4. Accessing a Protected Resource . . . . . . . . . . . . . . . . 11 72 4.1. Access Token . . . . . . . . . . . . . . . . . . . . . . . 11 73 4.2. Acquiring an Access Token . . . . . . . . . . . . . . . . 11 74 4.3. Client Calls Protected Resource Using HTTP Header . . . . 12 75 4.4. Client Calls Protected Resource Using URL Query 76 Parameter . . . . . . . . . . . . . . . . . . . . . . . . 12 77 4.5. Client Calls Protected Resource Using Post Parameter . . . 13 78 5. Acquiring an Access Token: Autonomous Client Profiles . . . . 13 79 5.1. Client Account and Password Profile . . . . . . . . . . . 13 80 5.1.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 13 81 5.1.2. Client Requests Access Token . . . . . . . . . . . . . 13 82 5.1.3. Successful Access Token Response from 83 Authorization Server . . . . . . . . . . . . . . . . 14 84 5.1.4. Unsuccessful Access Token Response from 85 Authorization Server . . . . . . . . . . . . . . . . . 14 86 5.1.5. Client Refreshes Access Token . . . . . . . . . . . . 15 87 5.2. Assertion Profile . . . . . . . . . . . . . . . . . . . . 15 88 5.2.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 15 89 5.2.2. Client Obtains Assertion . . . . . . . . . . . . . . . 15 90 5.2.3. Client Requests Access Token . . . . . . . . . . . . . 15 91 5.2.4. Successful Access Token Response from 92 Authorization Server . . . . . . . . . . . . . . . . . 16 93 5.2.5. Unsuccessful Access Token Response from 94 Authorization Server . . . . . . . . . . . . . . . . . 16 95 5.2.6. Client Refreshes Access Token . . . . . . . . . . . . 16 97 6. Acquiring an Access Token: User Delegation Profiles . . . . . 17 98 6.1. Username and Password Profile . . . . . . . . . . . . . . 17 99 6.1.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 17 100 6.1.2. Client Obtains Username and Password . . . . . . 17 101 6.1.3. Client Requests Access Token . . . . . . . . . . . . . 17 102 6.1.4. Successful Access Token Response from 103 Authorization Server . . . . . . . . . . . . . . . . . 18 104 6.1.5. Unsuccessful Access Token Response from 105 Authorization Server . . . . . . . . . . . . . . . . . 18 106 6.1.6. Verification URL Response from Authorization Server . 18 107 6.1.7. CAPTCHA Response from Authorization Server . . . . . . 19 108 6.1.8. Client Refreshes Access Token . . . . . . . . . . . . 19 109 6.1.9. Successful Access Token Refresh . . . . . . . . . . . 20 110 6.1.10. Unsuccessful Access Token Refresh . . . . . . . . . . 20 111 6.2. Web App Profile . . . . . . . . . . . . . . . . . . . . . 20 112 6.2.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 21 113 6.2.2. Client Directs the User to the Authorization 114 Server . . . . . . . . . . . . . . . . . . . . . . . . 21 115 6.2.3. Authorization Server Confirms Authorization 116 Request with User . . . . . . . . . . . . . . . . . . 21 117 6.2.4. Authorization Server Directs User back to the 118 Client . . . . . . . . . . . . . . . . . . . . . . . . 22 119 6.2.5. Client Requests Access Token . . . . . . . . . . . . . 22 120 6.2.6. Successful Access Token Response from 121 Authorization Server . . . . . . . . . . . . . . . . . 23 122 6.2.7. Unsuccessful Access Token Response from 123 Authorization Server . . . . . . . . . . . . . . . . . 24 124 6.2.8. Client Refreshes Access Token . . . . . . . . . . . . 25 125 6.2.9. Successful Access Token Refresh . . . . . . . . . . . 25 126 6.2.10. Unsuccessful Access Token Refresh . . . . . . . . . . 26 127 6.3. Rich App Profile . . . . . . . . . . . . . . . . . . . . . 26 128 6.3.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 26 129 6.3.2. Client Directs the User to the Authorization 130 Server . . . . . . . . . . . . . . . . . . . . . . . . 26 131 6.3.3. Authorization Server Confirms Authorization 132 Request with User . . . . . . . . . . . . . . . . . . 27 133 6.3.4. Client Requests Access Token . . . . . . . . . . . . . 28 134 6.3.5. Successful Access Token Response from 135 Authorization Server . . . . . . . . . . . . . . . . . 29 136 6.3.6. Unsuccessful Access Token Response from 137 Authorization Server . . . . . . . . . . . . . . . . . 29 138 6.3.7. Client Refreshes Access Token . . . . . . . . . . . . 30 139 6.3.8. Successful Access Token Refresh . . . . . . . . . . . 30 140 6.3.9. Unsuccessful Access Token Refresh . . . . . . . . . . 30 141 7. Parameter Considerations . . . . . . . . . . . . . . . . . . . 31 142 7.1. Authorization Server Request / Response Parameter 143 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 31 144 7.2. Parameter Size . . . . . . . . . . . . . . . . . . . . . . 31 145 7.3. Access Token Format . . . . . . . . . . . . . . . . . . . 31 146 7.4. Refresh Token Format . . . . . . . . . . . . . . . . . . . 32 147 7.5. Additional Authorization Server Parameters . . . . . . . . 32 148 7.6. Parameter Names and Order . . . . . . . . . . . . . . . . 32 149 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 150 9. Security Considerations . . . . . . . . . . . . . . . . . . . 32 151 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32 152 10.1. Normative References . . . . . . . . . . . . . . . . . . . 32 153 10.2. Informative References . . . . . . . . . . . . . . . . . . 33 154 Appendix A. Client Account and Password Profile Example . . . . . 33 155 A.1. Provisioning . . . . . . . . . . . . . . . . . . . . . . . 33 156 A.2. Client Requests Access Token . . . . . . . . . . . . . . . 34 157 A.3. Successful Access Token Response from Authorization 158 Server . . . . . . . . . . . . . . . . . . . . . . . . . . 34 159 A.4. Client Calls Protected Resource . . . . . . . . . . . . . 35 160 Appendix B. Web App Profile Example . . . . . . . . . . . . . . . 35 161 B.1. Provisioning . . . . . . . . . . . . . . . . . . . . . . . 35 162 B.2. Client Directs the User to the Server . . . . . . . . . . 36 163 B.3. Authorization Server Confirms Delegation Request with 164 User . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 165 B.4. Server Directs User back to the Client . . . . . . . . . . 36 166 B.5. Client Requests Access Token . . . . . . . . . . . . . . . 37 167 B.6. Successful Access Token Response from Authorization 168 Server . . . . . . . . . . . . . . . . . . . . . . . . . . 37 169 B.7. Client Calls Protected Resource . . . . . . . . . . . . . 38 170 B.8. Client Refreshes Access Token . . . . . . . . . . . . . . 38 171 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39 173 1. Overview 175 As the internet has evolved, there is a growing trend for a variety 176 of applications (Clients) to access resources through an API over 177 HTTP or other protocols. Often these resources require authorization 178 for access and are Protected Resources. The systems that are trusted 179 to make authorization decisions may be independent from the Protected 180 Resources for scale and security reasons. The OAuth Web Resource 181 Authorization Profiles (OAuth WRAP) enable a Protected Resource to 182 delegate the authorization to access a Protected Resource to one or 183 more trusted authorities. 185 Clients that wish to access a Protected Resource first obtain 186 authorization from a trusted authority (Authorization Server). 187 Different credentials and profiles can be used to obtain this 188 authorization, but once authorized, the Client is provided an Access 189 Token, and possible a Refresh Token to obtain new Access Tokens. The 190 Authorization Server typically includes authorization information in 191 the Access Token and digitally signs the Access Token. Protected 192 Resource can verify that an Access Token received from a Client was 193 issued by a trusted Authorization Server and is valid. The Protected 194 Resource can then examine the contents of the Access Token to 195 determine the authorization that has been granted to the Client. 197 1.1. Accessing a Protected Resource 199 The Access Token is opaque to the Client, and can be any format 200 agreed to between the Authorization Server and the Protected Resource 201 enabling existing systems to reuse suitable tokens, or use a standard 202 token format such as a Simple Web Token or JSON Web Token. Since the 203 Access Token provides the Client authorization to the Protected 204 Resource for the life of the Access Token, the Authorization Server 205 should issue Access Tokens that expire within an appropriate time. 206 When an Access Token expires, the Client requests a new Access Token 207 from the Authorization Server, which once again computes the Client's 208 authorization, and issues a new Access Token. Figure 1 below shows 209 the flow between the Client and Authorization Server (A,B); and then 210 between the Client and Protected Resource (C,D): 212 +---+ +---------------+ 213 | C |--(A)------ credentials --------->| Authorization | 214 | l |<-(B)------ Access Token ---------| Server | 215 | i | +---------------+ 216 | e | 217 | n | Access Token +-----------+ 218 | t |--(C)----- in HTTP header ------->| Protected | 219 | |<-(D)------ API response ---------| Resource | 220 +---+ +-----------+ 222 Figure 1 224 In step A, the Client presents credentials to the Authorization 225 Server in exchange for an Access Token. 227 A Profile specifies the credentials to be provided in step A, and how 228 the Client obtains them. This specification defines a number of 229 Profiles; additional Profiles may be defined to support additional 230 scenarios. The Profiles in this specification are separated into two 231 groups: autonomous profiles where the Client as acting for itself, 232 and user delegation profiles where the Client is acting on behalf of 233 a User. 235 1.2. Autonomous Client Profiles 237 The following two Profiles (see Section 5) are recommended for 238 scenarios involving a Client acting autonomously. 240 Client Account and Password Profile (Section 5.1): This is the 241 simplest Profile. The Client is provisioned with an account name and 242 corresponding password by the Authorization Server. The Client 243 presents the account name and password to the Access Token URL at the 244 Authorization Server in exchange for an Access Token. This Profile 245 is not intended for a Client acting on behalf of a User. See the 246 User Delegation Profiles. 248 Assertion Profile (Section 5.2): This profile enables a Client with a 249 SAML [OASIS.saml-core-2.0-os] or other assertion recognized by the 250 Authorization Server. The Client presents the assertion to the 251 Access Token URL at the Authorization Server in exchange for an 252 Access Token. How the Client obtains the assertion is out of scope 253 of OAuth WRAP. 255 Access Tokens are short lived bearer tokens. When the Protected 256 Resource is presented with an expired Access Token by the Client, the 257 Protected Resource returns an error. The Client presents the 258 assertion once again to the Authorization Server to obtain a new 259 Access Token. 261 1.3. User Delegation Profiles 263 Common scenarios involve the User delegating to a Client to act on 264 the User's behalf, adding another party (the User) to the protocol. 265 In these Profiles (see Section 6), the Client receives a Refresh 266 Token when it acquires the first Access Token. When an Access Token 267 expires, the Client presents the Refresh Token to acquire a new 268 Access Token. Refresh Tokens are sensitive as they represent long- 269 lived permissions to access a Protected Resource and are always 270 transmitted using HTTPS. 272 Username and Password Profile (Section 6.1): While the User may use a 273 username and password to authenticate to the Authorization Server, it 274 is undesirable for the Client to store the User's username and 275 password. In this profile the User provides their username and 276 password to an application (Client) they have installed on their 277 device. The Client presents a Client Identifier, the username and 278 password (credentials) to the Access Token URL at the Authorization 279 Server in exchange for an Access Token and a Refresh Token as 280 depicted in Figure 2 below. 282 +---+ +---------------+ 283 | C |--(A)------ credentials --------->| Authorization | 284 | l |<-(B)------ Access Token ---------| Server | 285 | i | Refresh Token +---------------+ 286 | e | 287 | n | Access Token +-----------+ 288 | t |--(C)----- in HTTP header ------->| Protected | 289 | |<-(D)------ API response ---------| Resource | 290 +---+ +-----------+ 292 Figure 2 294 When the Access Token expires, the Client presents the Refresh Token 295 to the Refresh Token URL at the Authorization Server in exchange for 296 a new Access Token (Figure 3, steps A and B). The Client then uses 297 the new Access Token to access the Protected Resource (Figure 3, 298 steps C and D). 300 +---+ +---------------+ 301 | C |--(A)----- Refresh Token -------->| Authorization | 302 | l |<-(B)------ Access Token ---------| Server | 303 | i | +---------------+ 304 | e | 305 | n | Access Token +-----------+ 306 | t |--(C)----- in HTTP header ------->| Protected | 307 | |<-(D)------ API response ---------| Resource | 308 +---+ +-----------+ 310 Figure 3 312 Web App Profile (Section 6.2): It is undesirable for a User to 313 provide their Authorization Server username and password to web 314 applications. Additionally, the User may authenticate to the 315 Authorization Server using other mechanisms than a username and 316 password. In this profile, a web application (Client) has been 317 provisioned with a Client Identifier and Client Secret and may have 318 registered a Callback URL. Figure 4 below illustrates the protocol. 319 (A) The Client initiates the protocol by redirecting the User to the 320 User Authorization URL at the Authorization Server passing the Client 321 Identifier and the Callback URL. (B) The Authorization Server 322 authenticates the User, confirms the User would like to authorize the 323 Client to access the Protected Resource, and generates a Verification 324 Code. (C) The Authorization Server then redirects the User to the 325 Callback URL at the Client passing along the Verification Code. 327 +---------+ 328 | Web App | 329 | Client | 330 +---------+ 331 v ^ 332 | | 333 (A) (C) 334 | | 335 \ \ 336 +---------+ +---------------+ 337 | |\---(C)-- Verification Code ----<| | 338 | User | | Authorization | 339 | at |<---(B)-- User authenticates --->| Server | 340 | Browser | | | 341 | |\---(A)-- Client Identifier ---->| | 342 +---------+ +---------------+ 344 Figure 4 346 Similar to step A in Figure 2, the Client then presents the Client 347 Identifier, Client Secret, Callback URL and Verification code 348 (credentials) to the Access Token URL at the Authorization Server for 349 an Access Token and a Refresh Token. 351 Rich App Profile (Section 6.3): This profile is suitable when the 352 Client is an application the User has installed on their device and a 353 web browser is available, but it is undesirable for the User to 354 provide their username and password to an application, or the user 355 may not be using a username and password to authenticate to the 356 Authorization Server. 358 The Client initiates the protocol by directing the User's browser to 359 the Authorization URL at the Authorization Server passing the Client 360 Identifier and potentially a Callback URL. The Authorization Server 361 authenticates the User, confirms the User would like to authorize the 362 Client to access the Protected Resource, and generates a Verification 363 Code. The Verification Code may be communicated back to the Client 364 in a number of ways: 366 a. the Authorization Server presents the Verification Code to the 367 User, who is instructed to enter the Verification Code directly 368 in the Client; 370 b. the Client reads the Verification Code from the title of the web 371 page presented by the Authorization Server; 373 c. the Authorization Server redirects the User to the Callback URL 374 that presents Client specific language for the User to enter the 375 Verification Code into the Client; or 377 d. the Client has registered a custom scheme and the Authorization 378 Server redirects the browser to the custom scheme that causes the 379 User's browser to load the Client application with the 380 Verification Code as a parameter. 382 Similar to step A in Figure 2, the Client then presents the Client 383 Identifier, Callback URL (if provided) and Verification code 384 (credentials) to the Access Token URL at the Authorization Server for 385 an Access Token and a Refresh Token. 387 2. Requirements Language 389 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 390 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 391 document are to be interpreted as described in [RFC2119]. Domain 392 name examples use [RFC2606]. 394 3. Definitions 396 Access Token: a short lived bearer token issued by the Authorization 397 Server to the Client. The Access Token is presented by the 398 Client to the Protected Resource to access protected resources. 400 Authorization Server: an authorization resource that issues Access 401 Tokens to Clients after successful authorization. May be the 402 same entity as the Protected Resource. 404 Client: an application that would like access to a Protected 405 Resource. Client Identifier:"> a value used by a Client to 406 identify itself to the Authorization Server. This may be a 407 human readable string or an opaque identifier. 409 Client Secret: a secret used by a web application Client to 410 establish ownership of the Client Identifier. 412 Profile: a mechanism for a Client to obtain an Access Token from an 413 Authorization Server. 415 Protected Resource: a protected API that allows access via OAuth 416 WRAP. May be the same entity as the Authorization Server. 417 Refresh Token:"> a long lived bearer token used by a Client to 418 acquire an Access Token from an Authorization Server. 420 User: an individual who has an account with the Authorization Server. 422 Verification Code: a code used by a Client to verify the User has 423 authorized the Client to have specific access to a Protected 424 Resource. 426 3.1. URLs 428 Access Token URL: the Authorization Server URL at which an Access 429 Token is requested by the Client. The URL may accept a variety 430 of parameters depending on the Profile. A Refresh Token may 431 also be returned to the Client. This URL MUST be an HTTPS URL 432 and MUST always be called with POST. 434 Callback URL: the Client URL where the User will be redirected after 435 an authorization request to the Authorization Server. 437 Refresh Token URL: the Authorization Server URL at which a Refresh 438 Token is presented in exchange for a new Access Token is 439 requested. This URL MUST be an HTTPS URL and MUST always be 440 called with POST. 442 User Authorization URL: the Authorization Server URL where the 443 Client redirects the User to make an authorization request. 445 4. Accessing a Protected Resource 447 Clients always present an Access Token to access a Protected 448 Resource. Use of the Authorization header is RECOMMENDED, since HTTP 449 implementations are aware that Authorization headers have special 450 security properties and may require special treatment in caches and 451 logs. Protected Resources SHOULD take precautions to insure that 452 Access Tokens are not inadvertently logged or captured. In addition 453 to the methods presented here, the Protected Resource MAY allow the 454 Client to present the Access Token using any scheme agreed on by the 455 Client and Protected Resource. 457 4.1. Access Token 459 The exact format of the Access Token is opaque to Clients and is out 460 of scope of this specification. However, Protected Resources MUST be 461 able to verify that the Access Token was issued by a trusted 462 Authorization Server and is still valid. Access Tokens SHOULD 463 periodically expire. The expiry time of Access Tokens is determined 464 as an appropriate balance between excessive resource utilization if 465 too short and unauthorized access if too long. 467 4.2. Acquiring an Access Token 469 An Authorization Server may support one or more protocol profiles 470 that enable a Client to obtain an Access Token that can be used to 471 access a Protected Resource. 473 Client developers only need to implement the profile(s) that align 474 with how their application will be deployed and are supported by the 475 Authorization Server. 477 Authorization Server developers only need to implement the profile(s) 478 that are appropriate for them. 480 Protected Resource developers do not implement a profile as the 481 Client always interacts with the Protected Resource by presenting an 482 Access Token. 484 Section 7 has general information about parameters passed to and from 485 the Authorization Server. 487 See Section 5 for how the Client acquires an Access Token when acting 488 autonomously, and Section 6 for how the Client acquires an Access 489 Token when acting acting on behalf of a User. 491 4.3. Client Calls Protected Resource Using HTTP Header 493 The Protected Resource SHOULD enable Clients to access the Protected 494 Resource by including the Access Token in the HTTP Authorization 495 header using the OAuth WRAP scheme with the following parameter: 497 access_token 498 REQUIRED. The value of the Access Token 500 For example, if the Access Token is the string 123456789, the HTTP 501 header would be: 503 Authorization: WRAP access_token="123456789" 505 Note that per section 1.2 of [RFC2617] that the following header is 506 also valid: 508 Authorization: WRAP access_token = 123456789 510 If the Access Token has expired or is invalid, the Protected Resource 511 MUST return: 513 HTTP 401 Unauthorized 515 and the HTTP header: 517 WWW-Authenticate: WRAP 519 4.4. Client Calls Protected Resource Using URL Query Parameter 521 The Protected Resource MAY allow the Client to access protected 522 resources at the Protected Resource by including the following HTTP 523 URL query parameter in the URL: 525 access_token 526 REQUIRED. The value of the Access Token 528 If the Access Token has expired or is invalid, the Protected Resource 529 MUST return: 531 HTTP 401 Unauthorized 533 and the HTTP header: 535 WWW-Authenticate: WRAP 537 4.5. Client Calls Protected Resource Using Post Parameter 539 The Protected Resource MAY allow the Client to access protected 540 resources at the Protected Resource by including the following 541 parameter in the body of a HTTP post message formatted as 542 application/x-www-form-urlencoded per 17.13.4 of HTML 4.01 543 [W3C.REC-html40-19980424]: 545 access_token 546 REQUIRED. The value of the Access Token 548 If the Access Token has expired or is invalid, the Protected Resource 549 MUST return: 551 HTTP 401 Unauthorized 553 and the HTTP header: 555 WWW-Authenticate: WRAP 557 5. Acquiring an Access Token: Autonomous Client Profiles 559 These are the profiles the Client uses when acting autonomously. 561 5.1. Client Account and Password Profile 563 This profile is suitable when the Client is an application calling 564 the Protected Resource on behalf of an organization and the 565 Authorization Server accepts account passwords for authentication. 566 This enables the Authorization Server to use an existing 567 authentication mechanism. This profile SHOULD NOT be used when the 568 Client is acting on behalf of a user. Profiles 6.1, 6.2 or 6.3 are 569 RECOMMENDED when a Client is acting on behalf of a User. 571 5.1.1. Provisioning 573 Prior to initiating this protocol profile, the Client MUST have 574 obtained an account name and account password from the Authorization 575 Server. 577 5.1.2. Client Requests Access Token 579 The Client makes an HTTPS request to the Authorization Server's 580 Access Token URL using POST. The request contains the following 581 parameters: 583 wrap_name 584 REQUIRED. The account name. 586 wrap_password 587 REQUIRED. The account password. 589 wrap_scope 590 OPTIONAL. The Authorization Server MAY define authorization scope 591 values for the Client to include. 593 Additional parameters 594 Any additional parameters, as defined by the Authorization Server. 596 5.1.3. Successful Access Token Response from Authorization Server 598 If successful, the Authorization Server returns: 600 HTTP 200 OK 602 with the Refresh Token and an Access Token in the response body. The 603 response body contains the following parameters: 605 wrap_refresh_token 606 REQUIRED. The Refresh Token. 608 wrap_access_token 609 REQUIRED. The Access Token. 611 wrap_access_token_expires_in 612 OPTIONAL. The lifetime of the Access Token in seconds. For 613 example, 3600 represents one hour. 615 Additional parameters 616 Any additional parameters, as defined by the Authorization Server. 618 The Client may now use the Access Token to access the Protected 619 Resource per Section 4 621 5.1.4. Unsuccessful Access Token Response from Authorization Server 623 If the Client account name and password are invalid, the 624 Authorization Server MUST respond with: 626 HTTP 401 Unauthorized 628 and the HTTP header: 630 WWW-Authenticate: WRAP 632 The Client MUST obtain a valid account name and password before 633 retrying the request. 635 5.1.5. Client Refreshes Access Token 637 Authorization Servers SHOULD issue Access Tokens that expire and 638 require Clients to refresh them. Upon receiving the HTTP 401 639 response when accessing protected resources per Section 4, the Client 640 should request a new Access Token by repeating Section 5.1.2 642 5.2. Assertion Profile 644 5.2.1. Provisioning 646 Prior to initiating this protocol profile, the Client MUST have a 647 mechanism for obtained an assertion from an assertion issuer that can 648 be presented to the Authorization Server for access to the Protected 649 Resource. 651 5.2.2. Client Obtains Assertion 653 The Client obtains an assertion. The process for obtaining the 654 assertion is defined by the assertion issuer and the Authorization 655 Server, and is out of scope of this specification. 657 5.2.3. Client Requests Access Token 659 The Client makes an HTTPS request to the Authorization Server's 660 Access Token URL using POST. The request contains the following 661 parameters: 663 wrap_assertion_format 664 REQUIRED. The format of the assertion as defined by the 665 Authorization Server. 667 wrap_assertion 668 REQUIRED. The assertion. 670 wrap_scope 671 OPTIONAL. The Authorization Server MAY define authorization scope 672 values for the Client to include 674 Additional parameters 675 Any additional parameters, as defined by the Authorization Server. 677 5.2.4. Successful Access Token Response from Authorization Server 679 If successful, the Authorization Server returns: 681 HTTP 200 OK 683 with the Access Token in the response body. The response body 684 contains the following parameters: 686 wrap_access_token 687 REQUIRED. The Access Token. 689 wrap_access_token_expires_in 690 OPTIONAL. The lifetime of the Access Token in seconds. For 691 example, 3600 represents one hour. 693 Additional parameters 694 Any additional parameters, as defined by the Authorization Server. 696 The Client may now use the Access Token to access the Protected 697 Resource per Section 4. 699 5.2.5. Unsuccessful Access Token Response from Authorization Server 701 If the assertion is not valid, the Authorization Server MUST respond 702 with: 704 HTTP 401 Unauthorized 706 and the HTTP header: 708 WWW-Authenticate: WRAP 710 The Client MUST obtain a valid assertion by repeating Section 5.2.2 711 before retrying the request. 713 5.2.6. Client Refreshes Access Token 715 Authorization Servers SHOULD issue Access Tokens that expire and 716 require Clients to refresh them. Upon receiving the HTTP 401 717 response when accessing protected resources per Section 4, the Client 718 should request a new Access Token by repeating Section 5.2.3 if the 719 assertion is still valid, otherwise the Client MUST obtain a new, 720 valid assertion by repeating Section 5.2.2. 722 6. Acquiring an Access Token: User Delegation Profiles 724 These are the profiles the Client uses when acting on behalf of a 725 User. 727 6.1. Username and Password Profile 729 This profile is suitable where the Client is an application the User 730 has installed on their computer and the User uses a username and 731 password to authenticate to the Authorization Server. This profile 732 enables a Client to act on behalf of the User without having to 733 permanently store the User's username and password. 735 6.1.1. Provisioning 737 Prior to initiating this protocol profile, the Authorization Server 738 MAY have required the Client to have obtained a Client Identifier 739 from the Authorization Server. 741 6.1.2. Client Obtains Username and Password 743 The Client obtains the User's username and password from the user. 744 The Client MUST discard the username and password once an Access 745 Token has been obtained. 747 6.1.3. Client Requests Access Token 749 The Client makes an HTTPS request to the Authorization Server's 750 Access Token URL using POST. The request contains the following 751 parameters: 753 wrap_client_id 754 REQUIRED. The Client Identifier. 756 wrap_username 757 REQUIRED. The User's username. 759 wrap_password 760 REQUIRED. The User's password. 762 wrap_scope 763 OPTIONAL. The Authorization Server MAY define authorization scope 764 values for the Client to include. 766 Additional parameters 767 Any additional parameters, as defined by the Authorization Server. 769 6.1.4. Successful Access Token Response from Authorization Server 771 If successful, the Authorization Server returns: 773 HTTP 200 OK 775 with the Access Token in the response body. The response body 776 contains the following parameters: 778 wrap_access_token 779 REQUIRED. The Access Token. 781 wrap_access_token_expires_in 782 OPTIONAL. The lifetime of the Access Token in seconds. For 783 example, 3600 represents one hour. 785 Additional parameters 786 Any additional parameters, as defined by the Authorization Server. 788 The Client MUST discard the User's username and password. The Client 789 securely stores the Refresh Token for later use. The Client may now 790 use the Access Token to access the Protected Resource per Section 4. 792 6.1.5. Unsuccessful Access Token Response from Authorization Server 794 The Authorization Server MUST verify User's username and password. 795 If the verification fails, the Authorization Server MUST respond 796 with: 798 HTTP 401 Unauthorized 800 and the HTTP header: 802 WWW-Authenticate: WRAP 804 The Client needs to obtain a valid username and password from the 805 User per Section 6.1.2 before retrying the request. 807 6.1.6. Verification URL Response from Authorization Server 809 If the Authorization Server determines that the Client may be 810 malicious, the Authorization Server MAY require the Client to 811 instruct the User to visit a Verification URL. The Authorization 812 Server communicates its requirement by responding to the Client's 813 Access Token request with the following: 815 HTTP 400 Bad Request 817 and the body of the Authorization Server response contains the 818 following parameter: 820 wrap_verification_url 821 REQUIRED. The verification URL that the Client MUST either load 822 in the User's browser, or display for the User to enter into a 823 browser. 825 The Client MUST then wait for the User to indicate they have 826 successfully completed the verification process at the Authorization 827 Server and attempt to obtain an Access Token Refresh Token per 828 Section 6.1.3 again. 830 6.1.7. CAPTCHA Response from Authorization Server 832 If the Authorization Server determines that the Client may be 833 malicious, the Authorization Server MAY require the Client to have 834 the User solve a CAPTCHA Puzzle. The Authorization Server 835 communicates its requirement by responding to the Client's Access 836 Token request with the following: 838 HTTP 400 Bad Request 840 and the body of the Authorization Server response contains the 841 following parameter: 843 wrap_captcha_url 844 REQUIRED. The URL to the CAPTCHA puzzle image. 846 The Client MUST present the User with the CAPTCHA puzzle and prompt 847 for a solution. The Client then MAY attempt to obtain an Access 848 Token per Section 6.1.3 again, including the following additional 849 parameter: 851 wrap_captcha_url 852 REQUIRED. The URL to the CAPTCHA puzzle received from the 853 Authorization Server. 855 wrap_captcha_solution 856 REQUIRED. The solution string to the CAPTCHA puzzle as defined by 857 the Authorization Server. 859 6.1.8. Client Refreshes Access Token 861 Refreshing an Access Token is the same in Section 6.1, Section 6.2, 862 and Section 6.3. Authorization Servers SHOULD issue Access Tokens 863 that expire and require Clients to refresh them. Upon receiving the 864 HTTP 401 response when accessing protected resources per Section 4, 865 the Client makes an HTTPS request to the Authorization Server's 866 Refresh Token URL using POST. The request contains the following 867 parameters: 869 wrap_refresh_token 870 REQUIRED. The Refresh Token that was received in Section 6.1.3 872 Additional parameters: 873 Any additional parameters, as defined by the Authorization Server. 875 6.1.9. Successful Access Token Refresh 877 If successful, the Authorization Server returns: 879 HTTP 200 OK 881 with the Access Token in the response body. The response body 882 contains the following parameters: 884 wrap_access_token 885 REQUIRED. The Access Token. 887 wrap_access_token_expires_in 888 OPTIONAL. The lifetime of the Access Token in seconds. For 889 example, 3600 represents one hour. 891 Additional parameters 892 Any additional parameters, as defined by the Authorization Server. 894 6.1.10. Unsuccessful Access Token Refresh 896 The Authorization Server MUST verify the Refresh Token. If the 897 verification fails, the Authorization Server MUST respond with 899 HTTP 401 Unauthorized 901 and the HTTP header: 903 WWW-Authenticate: WRAP 905 The Client MUST again request authorization from the User by 906 prompting for the User's username and password per Section 6.1.2 907 before retrying the request. 909 6.2. Web App Profile 911 This profile is suitable when the Client is a web application calling 912 the Protected Resource on behalf of a User. This profile enables a 913 Client to act on behalf of the User without acquiring a User's 914 credentials. 916 6.2.1. Provisioning 918 Prior to initiating this protocol profile, the Client MUST have 919 obtained a Client Identifier and Client Secret from the Authorization 920 Server. The Authorization Server MAY have also required the Client 921 to register the Callback URL. 923 6.2.2. Client Directs the User to the Authorization Server 925 The Client initiates an authorization request by redirecting the 926 User's browser to the Authorization Server's User Authorization URL, 927 with the following parameters: 929 wrap_client_id 930 REQUIRED. The Client Identifier. 932 wrap_callback 933 REQUIRED. The Callback URL. An absolute URL to which the 934 Authorization Server will redirect the User back after the User 935 has approved the authorization request. Authorization Servers MAY 936 require that the wrap_callback URL match the previously registered 937 value for the Client Identifier. 939 wrap_client_state 940 OPTIONAL. An opaque value that Clients can use to maintain state 941 associated with this request. If this value is present, the 942 Authorization Server MUST return it to the Client's Callback URL. 944 wrap_scope 945 OPTIONAL. The Authorization Server MAY define authorization scope 946 values for the Client to include. 948 Additional parameters 949 Any additional parameters, as defined by the Authorization Server. 951 6.2.3. Authorization Server Confirms Authorization Request with User 953 Upon receiving an authorization request from the Client by a 954 redirection of the User's browser, the Authorization Server 955 authenticates the user, presents the User with the Protected Resource 956 access that will be granted to the Client, and prompts the User to 957 confirm the request. 959 If the User denies the request, the Authorization Server MAY allow 960 the User to return to the Client Callback URL with the following 961 parameters added: 963 wrap_error_reason 964 REQUIRED. Value is user_denied 966 wrap_client_state 967 REQUIRED if the Client sent the value in the authorization request 968 in Section 6.2.2 970 If the User approves the request, the Authorization Server generates 971 a Verification Code and associates it with the Client Identifier and 972 Callback URL. 974 6.2.4. Authorization Server Directs User back to the Client 976 If the User approved the request, the Authorization Server MUST 977 redirect the User back to the Callback URL, with the following 978 parameters added: 980 wrap_verification_code 981 REQUIRED. The Verification Code. 983 wrap_client_state 984 REQUIRED if the Client sent the value in the authorization request 985 in Section 6.2.2 987 Additional parameters: 988 Any additional parameters, as defined by the Authorization Server. 990 6.2.5. Client Requests Access Token 992 The Client makes an HTTPS request to the Authorization Server's 993 Access Token URL, using POST. The request contains the following 994 parameters in the body of the request: 996 wrap_client_id 997 REQUIRED. The Client Identifier 999 wrap_client_secret 1000 REQUIRED. The Client Secret 1002 wrap_verification_code 1003 REQUIRED. The Verification Code. 1005 wrap_callback 1006 REQUIRED. The Callback URL used to obtain the Verification Code. 1008 Additional parameters: 1009 Any additional parameters, as defined by the Authorization Server. 1011 6.2.6. Successful Access Token Response from Authorization Server 1013 After receiving the Access Token request, the Authorization Server 1014 verifies the request as follows: 1016 the Client Secret MUST match the Client Identifer 1018 the Client Identifier MUST match the Client Identifier from the 1019 authorization redirect 1021 the Verification Code MUST match the Client Identifier from the 1022 authorization redirect 1024 the Callback URL MUST match the Callback URL from the 1025 authorization redirect 1027 if the Callback URL or Callback URL pattern was registered with 1028 the Authorization Server, the Callback URL MUST match the Callback 1029 URL or Callback URL pattern as defined by the Authorization Server 1031 the Verification Code MUST not have expired 1033 The Authorization Server MAY also require that a Verification Code is 1034 not reused. 1036 If verification is successful, the Authorization Server returns: 1038 HTTP 200 OK 1040 with the Refresh Token and the Access Token in the response body. 1041 The response body contains the following parameters: 1043 wrap_refresh_token 1044 REQUIRED. The Refresh Token. 1046 wrap_access_token 1047 REQUIRED. The Access Token. 1049 wrap_access_token_expires_in 1050 OPTIONAL. The lifetime of the Access Token in seconds. For 1051 example, 3600 represents one hour. 1053 Additional parameters 1054 Any additional parameters, as defined by the Authorization Server. 1056 The Client securely stores the Refresh Token for later use. The 1057 Client may now use the Access Token to access the Protected Resource 1058 per Section 4. 1060 6.2.7. Unsuccessful Access Token Response from Authorization Server 1062 The Authorization Server MUST first verify the Client Identifier and 1063 Client Secret. If they are invalid, the Authorization Server MUST 1064 respond with: 1066 HTTP 401 Unauthorized 1068 and the HTTP header: 1070 WWW-Authenticate: WRAP 1072 The Client MUST obtain a valid Client Identifier and Client Secret 1073 before retrying the request. 1075 The Authorization Server MUST then verify that the Callback URL and 1076 Verification Code are associated with the Client Identifier. If the 1077 verification fails, the Authorization Server MUST respond with: 1079 HTTP 400 Bad Request 1081 and the body of the Authorization Server response contains the 1082 following parameters: 1084 wrap_error_reason 1085 OPTIONAL. If all the parameters are valid except that the 1086 Verification Code has expired or been revoked, then it is 1087 RECOMMENDED that this parameter be included and if so, then the 1088 value MUST be: 1090 expired_verification_code 1092 This enables the Client to detect it needs a new Verification Code 1093 and to direct the User to the Authorization Server per 1094 Section 6.2.2 1095 If the Callback URL is invalid, the value MUST be: 1097 invalid_callback 1099 Additional parameters 1100 Any additional parameters, as defined by the Authorization Server. 1102 6.2.8. Client Refreshes Access Token 1104 Refreshing an Access Token is the same in Section 6.1, Section 6.2, 1105 and Section 6.3. Authorization Servers SHOULD issue Access Tokens 1106 that expire and require Clients to refresh them. Upon receiving the 1107 HTTP 401 response when accessing protected resources per Section 4, 1108 the Client makes an HTTPS request to the Authorization Server's 1109 Refresh Token URL using POST. The request contains the following 1110 parameters: 1112 wrap_refresh_token 1113 REQUIRED. The Refresh Token that was received in Section 6.2.5 1115 Additional parameters: 1116 Any additional parameters, as defined by the Authorization Server. 1118 6.2.9. Successful Access Token Refresh 1120 If successful, the Authorization Server returns: 1122 HTTP 200 OK 1124 with the Access Token in the response body. The response body 1125 contains the following parameters: 1127 wrap_access_token 1128 REQUIRED. The Access Token. 1130 wrap_access_token_expires_in 1131 OPTIONAL. The lifetime of the Access Token in seconds. For 1132 example, 3600 represents one hour. 1134 Additional parameters 1135 Any additional parameters, as defined by the Authorization Server. 1137 6.2.10. Unsuccessful Access Token Refresh 1139 The Authorization Server MUST verify the Refresh Token. If the 1140 verification fails, the Authorization Server MUST respond with 1142 HTTP 401 Unauthorized 1144 and the HTTP header: 1146 WWW-Authenticate: WRAP 1148 The Client MUST again request authorization from the User per 1149 Section 6.2.2. 1151 6.3. Rich App Profile 1153 This profile is suitable where the Client is an application the User 1154 has installed on their computer and there is a browser available for 1155 the Client to launch. This profile enables a Client to act on behalf 1156 of the User regardless of how the User authenticates to the Server 1157 and without access to the User's credentials. 1159 6.3.1. Provisioning 1161 Prior to initiating this protocol profile, the Client MAY be required 1162 to register the Client Identifier and/or the Callback URL with the 1163 Server. 1165 6.3.2. Client Directs the User to the Authorization Server 1167 The Client initiates an authorization request by opening the User's 1168 browser with the Server's User Authorization URL, and including the 1169 following parameters: 1171 wrap_client_id 1172 REQUIRED. The Client Identifier. 1174 wrap_callback 1175 OPTIONAL. A Callback URL where the Authorization Server MAY 1176 redirect the User's browser after the User responds to the 1177 authorization request. 1179 wrap_client_state 1180 OPTIONAL. An opaque value that Clients can use to maintain state 1181 associated with this request. If this value is present, the 1182 Authorization Server MUST return it to the Client's Callback URL. 1184 wrap_scope 1185 OPTIONAL. The Authorization Server MAY define authorization scope 1186 values for the Client to include. 1188 Additional parameters 1189 Any additional parameters, as defined by the Authorization Server. 1191 6.3.3. Authorization Server Confirms Authorization Request with User 1193 Upon receiving an authorization request from the Client by way of the 1194 User's browser, the Authorization Server authenticates the user, 1195 presents the User with the Protected Resource access that will be 1196 granted to the Client, and prompts the User to confirm the request. 1197 If the User approves the request, the Authorization Server generates 1198 a Verification Code. If the User denied access, the Authorization 1199 Server MAY set the Verification Code to the reserved value: 1201 user_denied 1203 It is RECOMMENDED the Verification Code be single use, and expire 1204 within minutes of issue. There are a number of mechanisms for the 1205 Authorization Server to transmit the Verification Code to the Client, 1206 specified below. 1208 Rich Application interaction with the User and the Authorization 1209 Server is an area of active research and development. If the Rich 1210 Application is able to retrieve the verifier directly from the 1211 callback URL returned by the Authorization Server, an improved user 1212 experience is possible. However, not all applications are able to 1213 interact with the Authorization Server in this manner. 1215 6.3.3.1. Applications with Callback URLs 1217 Rich Applications may be able to receive callback URLs in any of 1218 several ways. For example, the Rich Application may register a 1219 custom protocol handler with the application platform so that the 1220 application will be invoked when the browser is redirected to the 1221 callback URL. Alternatively, the callback URL may point to a web 1222 site with which the Rich Application has a trust relationship. The 1223 web site can then pass the Callback URL down to the Rich Application 1224 for processing. Finally, the Callback URL may point to a web site 1225 that will display the Callback URL to the screen along with 1226 instructions for the user to enter the Verification Code into the 1227 application. 1229 For Rich Applications with a Callback URL, the Authorization Server 1230 MUST redirect the User back to the Callback URL, with the following 1231 parameters added: 1233 wrap_verification_code 1234 REQUIRED. The Verification Code 1236 wrap_client_state 1237 REQUIRED if the Client sent the value in the authorization request 1238 in Section 6.3.2 1240 Additional parameters 1241 Any additional parameters, as defined by the Authorization Server. 1243 If the User denied access, the Server MAY redirect the User's browser 1244 to the Callback URL with the Verification Code set to the reserved 1245 value: 1247 user_denied 1249 6.3.3.2. Applications without Callback URLs 1251 Rich Applications without Callback URLs need to receive the 1252 verification code in other ways. For Rich Applications without a 1253 Callback URL, the Authorization Server MUST present the Verification 1254 Code on the web page and instruct the user to enter it into the 1255 Client. 1257 The Server MAY also append the Verification Code to the title of the 1258 HTML page so that Clients that have access to the title of the 1259 browser's current page can obtain the Verification Code without 1260 requiring the User enter the Verification Code into the Client. The 1261 Client can parse the title looking for "code=" and then the rest of 1262 the title is the Verification Code. If adding the Verification Code 1263 to the title of the HTML page, the Server MUST also include the 1264 wrap_client_state parameter if sent from the Client as the "state=" 1265 parameter. 1267 Eg. For example.com where the Verification Code = WF34F7HG and 1268 Client State = NMMGFJJ, the Server would set the title of the page to 1269 something like: 1270