idnits 2.17.00 (12 Aug 2021) /tmp/idnits64985/draft-hardt-oauth-00.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 651 has weird spacing: '...itional par...' == Line 670 has weird spacing: '...itional par...' == Line 757 has weird spacing: '...itional par...' == Line 862 has weird spacing: '...itional par...' == Line 958 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 4509 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 1436, but no explicit reference was found in the text == Outdated reference: draft-narten-iana-considerations-rfc2434bis has been published as RFC 5226 Summary: 1 error (**), 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-00 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 . . . . . . . . . . . . . . . . . 6 68 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 9 69 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 3.1. URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 4. Accessing a Protected Resource . . . . . . . . . . . . . . . . 10 72 4.1. Access Token . . . . . . . . . . . . . . . . . . . . . . . 11 73 4.2. Client Calls Protected Resource Using HTTP Header . . . . 11 74 4.3. Client Calls Protected Resource Using URL Parameter . . . 11 75 4.4. Client Calls Protected Resource Using Post Parameter . . . 12 76 5. Acquiring an Access Token . . . . . . . . . . . . . . . . . . 12 77 5.1. Client Account and Password Profile . . . . . . . . . . . 13 78 5.1.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 13 79 5.1.2. Client Requests Access Token . . . . . . . . . . . . . 13 80 5.1.3. Successful Access Token Response from 81 Authorization Server . . . . . . . . . . . . . . . . 13 82 5.1.4. Unsuccessful Access Token Response from 83 Authorization Server . . . . . . . . . . . . . . . . . 14 84 5.1.5. Client Refreshes Access Token . . . . . . . . . . . . 14 85 5.2. Assertion Profile . . . . . . . . . . . . . . . . . . . . 14 86 5.2.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 14 87 5.2.2. Client Obtains Assertion . . . . . . . . . . . . . . . 15 88 5.2.3. Client Requests Access Token . . . . . . . . . . . . . 15 89 5.2.4. Successful Access Token Response from 90 Authorization Server . . . . . . . . . . . . . . . . . 15 91 5.2.5. Unsuccessful Access Token Response from 92 Authorization Server . . . . . . . . . . . . . . . . . 16 93 5.2.6. Client Refreshes Access Token . . . . . . . . . . . . 16 94 5.3. Username and Password Profile . . . . . . . . . . . . . . 16 95 5.3.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 16 96 5.3.2. Client Obtains Username and Password . . . . . . 16 97 5.3.3. Client Requests Access Token . . . . . . . . . . . . . 16 98 5.3.4. Successful Access Token Response from 99 Authorization Server . . . . . . . . . . . . . . . . . 17 100 5.3.5. Unsuccessful Access Token Response from 101 Authorization Server . . . . . . . . . . . . . . . . . 17 102 5.3.6. Verification URL Response from Authorization Server . 18 103 5.3.7. CAPTCHA Response from Authorization Server . . . . . . 18 104 5.3.8. Client Refreshes Access Token . . . . . . . . . . . . 19 105 5.3.9. Successful Access Token Refresh . . . . . . . . . . . 19 106 5.3.10. Unsuccessful Access Token Refresh . . . . . . . . . . 19 107 5.4. Web App Profile . . . . . . . . . . . . . . . . . . . . . 20 108 5.4.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 20 109 5.4.2. Client Directs the User to the Authorization 110 Server . . . . . . . . . . . . . . . . . . . . . . . . 20 111 5.4.3. Authorization Server Confirms Authorization 112 Request with User . . . . . . . . . . . . . . . . . . 21 113 5.4.4. Authorization Server Directs User back to the 114 Client . . . . . . . . . . . . . . . . . . . . . . . . 21 115 5.4.5. Client Requests Access Token . . . . . . . . . . . . . 21 116 5.4.6. Successful Access Token Response from 117 Authorization Server . . . . . . . . . . . . . . . . . 22 118 5.4.7. Unsuccessful Access Token Response from 119 Authorization Server . . . . . . . . . . . . . . . . . 23 120 5.4.8. Client Refreshes Access Token . . . . . . . . . . . . 24 121 5.4.9. Successful Access Token Refresh . . . . . . . . . . . 24 122 5.4.10. Unsuccessful Access Token Refresh . . . . . . . . . . 25 123 5.5. Rich App Profile . . . . . . . . . . . . . . . . . . . . . 25 124 5.5.1. Provisioning . . . . . . . . . . . . . . . . . . . . . 25 125 5.5.2. Client Directs the User to the Authorization 126 Server . . . . . . . . . . . . . . . . . . . . . . . . 25 127 5.5.3. Authorization Server Confirms Authorization 128 Request with User . . . . . . . . . . . . . . . . . . 26 129 5.5.4. Client Requests Access Token . . . . . . . . . . . . . 28 130 5.5.5. Successful Access Token Response from 131 Authorization Server . . . . . . . . . . . . . . . . . 28 132 5.5.6. Unsuccessful Access Token Response from 133 Authorization Server . . . . . . . . . . . . . . . . . 29 134 5.5.7. Client Refreshes Access Token . . . . . . . . . . . . 29 135 5.5.8. Successful Access Token Refresh . . . . . . . . . . . 29 136 5.5.9. Unsuccessful Access Token Refresh . . . . . . . . . . 30 137 6. Parameter Considerations . . . . . . . . . . . . . . . . . . . 30 138 6.1. Authorization Server Request / Response Parameter 139 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 30 140 6.2. Parameter Size . . . . . . . . . . . . . . . . . . . . . . 30 141 6.3. Access Token Format . . . . . . . . . . . . . . . . . . . 31 142 6.4. Refresh Token Format . . . . . . . . . . . . . . . . . . . 31 143 6.5. Additional Authorization Server Parameters . . . . . . . . 31 145 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 146 8. Security Considerations . . . . . . . . . . . . . . . . . . . 31 147 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 148 9.1. Normative References . . . . . . . . . . . . . . . . . . . 31 149 9.2. Informative References . . . . . . . . . . . . . . . . . . 32 150 Appendix A. Client Account and Password Profile Example . . . . . 32 151 A.1. Provisioning . . . . . . . . . . . . . . . . . . . . . . . 32 152 A.2. Client Requests Access Token . . . . . . . . . . . . . . . 33 153 A.3. Successful Access Token Response from Authorization 154 Server . . . . . . . . . . . . . . . . . . . . . . . . . . 33 155 A.4. Client Calls Protected Resource . . . . . . . . . . . . . 34 156 Appendix B. Web App Profile Example . . . . . . . . . . . . . . . 34 157 B.1. Provisioning . . . . . . . . . . . . . . . . . . . . . . . 34 158 B.2. Client Directs the User to the Server . . . . . . . . . . 35 159 B.3. Authorization Server Confirms Delegation Request with 160 User . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 161 B.4. Server Directs User back to the Client . . . . . . . . . . 35 162 B.5. Client Requests Access Token . . . . . . . . . . . . . . . 36 163 B.6. Successful Access Token Response from Authorization 164 Server . . . . . . . . . . . . . . . . . . . . . . . . . . 36 165 B.7. Client Calls Protected Resource . . . . . . . . . . . . . 37 166 B.8. Client Calls Refreshes Access Token . . . . . . . . . . . 37 167 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 169 1. Overview 171 As the internet has evolved, there is a growing trend for a variety 172 of applications (Clients) to access resources through an API over 173 HTTP or other protocols. Often these resources require authorization 174 for access and are Protected Resources. The systems that are trusted 175 to make authorization decisions may be independent from the Protected 176 Resources for scale and security reasons. The OAuth Web Resource 177 Authorization Profiles (OAuth WRAP) enable a Protected Resource to 178 delegate the authorization to access a Protected Resource to one or 179 more trusted authorities. 181 Clients that wish to access a Protected Resource first obtain 182 authorization from a trusted authority (Authorization Server). 183 Different credentials and profiles can be used to obtain this 184 authorization, but once authorized, the Client is provided an Access 185 Token, and possible a Refresh Token to obtain new Access Tokens. The 186 Authorization Server typically includes authorization information in 187 the Access Token and digitally signs the Access Token. Protected 188 Resource can verify that an Access Token received from a Client was 189 issued by a trusted Authorization Server and is valid. The Protected 190 Resource can then examine the contents of the Access Token to 191 determine the authorization that has been granted to the Client. 193 1.1. Accessing a Protected Resource 195 The Access Token is opaque to the Client, and can be any format 196 agreed to between the Authorization Server and the Protected Resource 197 enabling existing systems to reuse suitable tokens, or use a standard 198 token format such as a Simple Web Token or JSON Web Token. Since the 199 Access Token provides the Client authorization to the Protected 200 Resource for the life of the Access Token, the Authorization Server 201 should issue Access Tokens that expire within an appropriate time. 202 When an Access Token expires, the Client requests a new Access Token 203 from the Authorization Server, which once again computes the Client's 204 authorization, and issues a new Access Token. Figure 1 below shows 205 the flow between the Client and Authorization Server (A,B); and then 206 between the Client and Protected Resource (C,D): 208 +---+ +---------------+ 209 | C |--(A)------ credentials --------->| Authorization | 210 | l |<-(B)------ Access Token ---------| Server | 211 | i | +---------------+ 212 | e | 213 | n | Access Token +-----------+ 214 | t |--(C)----- in HTTP header ------->| Protected | 215 | |<-(D)------ API response ---------| Resource | 216 +---+ +-----------+ 218 Figure 1 220 In step A, the Client presents credentials to the Authorization 221 Server in exchange for an Access Token. A Profile specifies the 222 credentials and how the Client obtains them. This specification 223 defines a number of Profiles; additional Profiles may be defined to 224 support additional scenarios. 226 1.2. Autonomous Client Profiles 228 The following two Profiles (5.1 and 5.2) are recommended for 229 scenarios involving a Client acting autonomously. 231 Client Account and Password Profile (5.1): This is the simplest 232 Profile. The Client is provisioned with an account name and 233 corresponding password by the Authorization Server. The Client 234 presents the account name and password to the Access Token URL at the 235 Authorization Server in exchange for an Access Token. 237 Assertion Profile (5.2): This profile enables a Client with a SAML or 238 other assertion recognized by the Authorization Server. The Client 239 presents the assertion to the Access Token URL at the Authorization 240 Server in exchange for an Access Token. How the Client obtains the 241 assertion is out of scope of OAuth WRAP. 243 Access Tokens are short lived bearer tokens. When the Protected 244 Resource is presented with an expired Access Token by the Client, the 245 Protected Resource returns an error. The Client presents the 246 credentials once again to the Authorization Server to obtain a new 247 Access Token. 249 1.3. User Delegation Profiles 251 Common scenarios involve the User delegating to a Client to act on 252 the User's behalf, adding another party (the User) to the protocol. 253 In these Profiles, the Client receives a Refresh Token when it 254 acquires the first Access Token. When an Access Token expires, the 255 Client presents the Refresh Token to acquire a new Access Token. 257 Refresh Tokens are sensitive as they represent long-lived permissions 258 to access a Protected Resource and are always transmitted using 259 HTTPS. 261 Username and Password Profile (5.3): While the User may use a 262 username and password to authenticate to the Authorization Server, it 263 is undesirable for the Client to store the User's username and 264 password. In this profile the User provides their username and 265 password to an application (Client) they have installed on their 266 device. The Client presents a Client Identifier, the username and 267 password (credentials) to the Access Token URL at the Authorization 268 Server in exchange for an Access Token and a Refresh Token as 269 depicted in Figure 2 below. 271 +---+ +---------------+ 272 | C |--(A)------ credentials --------->| Authorization | 273 | l |<-(B)------ Access Token ---------| Server | 274 | i | Refresh Token +---------------+ 275 | e | 276 | n | Access Token +-----------+ 277 | t |--(C)----- in HTTP header ------->| Protected | 278 | |<-(D)------ API response ---------| Resource | 279 +---+ +-----------+ 281 Figure 2 283 When the Access Token expires, the Client presents the Refresh Token 284 to the Refresh Token URL at the Authorization Server in exchange for 285 a new Access Token (Figure 3, steps A and B). The Client then uses 286 the new Access Token to access the Protected Resource (Figure 3, 287 steps C and D). 289 +---+ +---------------+ 290 | C |--(A)----- Refresh Token -------->| Authorization | 291 | l |<-(B)------ Access Token ---------| Server | 292 | i | +---------------+ 293 | e | 294 | n | Access Token +-----------+ 295 | t |--(C)----- in HTTP header ------->| Protected | 296 | |<-(D)------ API response ---------| Resource | 297 +---+ +-----------+ 299 Figure 3 301 Web App Profile (5.4): It is undesirable for a User to provide their 302 Authorization Server username and password to web applications. 304 Additionally, the User may authenticate to the Authorization Server 305 using other mechanisms then a username and password. In this 306 profile, a web application (Client) has been provisioned with a 307 Client Identifier and Client Secret and may have registered a 308 Callback URL. Figure 4 below illustrates the protocol. (A) The 309 Client initiates the protocol by redirecting the User to the User 310 Authorization URL at the Authorization Server passing the Client 311 Identifier and the Callback URL. (B) The Authorization Server 312 authenticates the User, confirms the User would like to authorize the 313 Client to access the Protected Resource, and generates a Verification 314 Code. (C) The Authorization Server then redirects the User to the 315 Callback URL at the Protected Resource passing along the Verification 316 Code. 318 +---------+ 319 | Web App | 320 | Client | 321 +---------+ 322 v ^ 323 | | 324 (A) (C) 325 | | 326 \ \ 327 +---------+ +---------------+ 328 | |\---(C)-- Verification Code ----<| | 329 | User | | Authorization | 330 | at |<---(B)-- User authenticates --->| Server | 331 | Browser | | | 332 | |\---(A)-- Client Identifier ---->| | 333 +---------+ +---------------+ 335 Figure 4 337 Similar to step A in Figure 2, the Client then presents the Client 338 Identifier, Client Secret, Callback URL and Verification code 339 (credentials) to the Access Token URL at the Authorization Server for 340 an Access Token and a Refresh Token. 342 Rich App Profile (5.5): This profile is suitable when the Client is 343 an application the User has installed on their device and a web 344 browser is available, but it is undesirable for the User to provide 345 their username and password to an application, or the user may not be 346 using a username and password to authenticate to the Authorization 347 Server. 349 The Client initiates the protocol by directing the User's browser to 350 the Authorization URL at the Authorization Server passing the Client 351 Identifier and potentially a Callback URL. The Authorization Server 352 authenticates the User, confirms the User would like to authorize the 353 Client to access the Protected Resource, and generates a Verification 354 Code. The Verification Code may be communicated back to the Client 355 in a number of ways: 357 a. the Authorization Server presents the Verification Code to the 358 User, who is instructed to enter the Verification Code directly 359 in the Client; the Client reads the Verification Code from the 360 title of the web page presented by the Authorization Server; 362 b. the Authorization Server redirects the User to the Callback URL 363 that presents Client specific language for the User to enter the 364 Verification Code into the Client; or 366 c. the Client has registered a custom scheme and the Authorization 367 Server redirects the browser to the custom scheme that causes the 368 User's browser to load the Client application with the 369 Verification Code as a parameter. 371 Similar to step A in Figure 2, the Client then presents the Client 372 Identifier, Callback URL (if provided) and Verification code 373 (credentials) to the Access Token URL at the Authorization Server for 374 an Access Token and a Refresh Token. 376 2. Requirements Language 378 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 379 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 380 document are to be interpreted as described in [RFC2119]. Domain 381 name examples use [RFC2606]. 383 3. Definitions 385 Access Token: a short lived bearer token issued by the Authorization 386 Server to the Client. The Access Token is presented by the 387 Client to the Protected Resource to access protected resources. 389 Authorization Server: an authorization resource that issues Access 390 Tokens to Clients after successful authorization. May be the 391 same entity as the Protected Resource. 393 Client: an application that would like access to a Protected 394 Resource. Client Identifier:"> a value used by a Client to 395 identify itself to the Authorization Server. This may be a 396 human readable string or an opaque identifier. 398 Client Secret: a secret used by a web application Client to 399 establish ownership of the Client Identifier. 401 Profile: a mechanism for a Client to obtain an Access Token from an 402 Authorization Server. 404 Protected Resource: a protected API that allows access via OAuth 405 WRAP. May be the same entity as the Authorization Server. 406 Refresh Token:"> a long lived bearer token used by a Client to 407 acquire an Access Token from an Authorization Server. 409 User: an individual who has an account with the Authorization Server. 411 Verification Code: a code used by a Client to verify the User has 412 authorized the Client to have specific access to a Protected 413 Resource. 415 3.1. URLs 417 Access Token URL: the Authorization Server URL at which an Access 418 Token is requested by the Client. The URL may accept a variety 419 of parameters depending on the Profile. A Refresh Token may 420 also be returned to the Client. This URL MUST be an HTTPS URL 421 and MUST always be called with POST. 423 Callback URL: the Client URL where the User will be redirected after 424 an authorization request to the Authorization Server. 426 Refresh Token URL: the Authorization Server URL at which a Refresh 427 Token is presented in exchange for a new Access Token is 428 requested. This URL MUST be an HTTPS URL and MUST always be 429 called with POST. 431 User Authorization URL: the Authorization Server URL where the 432 Client redirects the User to make an authorization request. 434 4. Accessing a Protected Resource 436 Clients always present an Access Token to access a Protected 437 Resource. See section 5 for how the Client acquires an Access Token. 438 Use of the Authorization header is RECOMMENDED, since HTTP 439 implementations are aware that Authorization headers have special 440 security properties and may require special treatment in caches and 441 logs. Protected Resources SHOULD take precautions to insure that 442 Access Tokens are not inadvertently logged or captured. In addition 443 to the methods presented here, the Protected Resource MAY allow the 444 Client to present the Access Token using any scheme agreed on by the 445 Client and Protected Resource. 447 4.1. Access Token 449 The exact format of the Access Token is opaque to Clients and is out 450 of scope of this specification. However, Protected Resources MUST be 451 able to verify that the Access Token was issued by a trusted 452 Authorization Server and is still valid. Access Tokens SHOULD 453 periodically expire. The expiry time of Access Tokens is determined 454 as an appropriate balance between excessive resource utilization if 455 too short and unauthorized access if too long. 457 4.2. Client Calls Protected Resource Using HTTP Header 459 The Protected Resource SHOULD enable Clients to access the Protected 460 Resource by including the Access Token in the HTTP Authorization 461 header using the OAuth WRAP scheme with the following parameter: 463 access_token 464 REQUIRED. The value of the Access Token 466 For example, if the Access Token is the string 123456789, the HTTP 467 header would be: 469 Authorization: WRAP access_token="123456789" 471 If the Access Token has expired or is invalid, the Protected Resource 472 MUST return: 474 HTTP 401 Unauthorized 476 and the HTTP header: 478 WWW-Authenticate: WRAP 480 4.3. Client Calls Protected Resource Using URL Parameter 482 The Protected Resource MAY allow the Client to access protected 483 resources at the Protected Resource by including the following 484 parameter in the URL: 486 access_token 487 REQUIRED. The value of the Access Token 489 If the Access Token has expired or is invalid, the Protected Resource 490 MUST return: 492 HTTP 401 Unauthorized 494 and the HTTP header: 496 WWW-Authenticate: WRAP 498 4.4. Client Calls Protected Resource Using Post Parameter 500 The Protected Resource MAY allow the Client to access protected 501 resources at the Protected Resource by including the following 502 parameter in the body of a HTTP post message formatted as 503 application/x-www-form-urlencoded per 17.13.4 of HTML 4.01 504 [W3C.REC-html40-19980424]: 506 access_token 507 REQUIRED. The value of the Access Token 509 If the Access Token has expired or is invalid, the Protected Resource 510 MUST return: 512 HTTP 401 Unauthorized 514 and the HTTP header: 516 WWW-Authenticate: WRAP 518 5. Acquiring an Access Token 520 An Authorization Server may support one or more protocol profiles 521 that enable a Client to obtain an Access Token that can be used to 522 access a Protected Resource. 524 Client developers only need to implement the profile(s) that align 525 with how their application will be deployed and are supported by the 526 Authorization Server. 528 Authorization Server developers only need to implement the profile(s) 529 that are appropriate for them. 531 Protected Resource developers do not implement a profile as the 532 Client always interacts with the Protected Resource by presenting an 533 Access Token. 535 Section 6 has general information about parameters passed to and from 536 the Authorization Server. 538 5.1. Client Account and Password Profile 540 This profile is suitable when the Client is an application calling 541 the Protected Resource on behalf of an organization and the 542 Authorization Server accepts account passwords for authentication. 543 This enables the Authorization Server to use an existing 544 authentication mechanism. This profile SHOULD NOT be used when the 545 Client is acting on behalf of a user. Profiles 5.3, 5.4 or 5.5 are 546 RECOMMENDED when a Client is acting on behalf of a User. 548 5.1.1. Provisioning 550 Prior to initiating this protocol profile, the Client MUST have 551 obtained an account name and account password from the Authorization 552 Server. 554 5.1.2. Client Requests Access Token 556 The Client makes an HTTPS request to the Authorization Server's 557 Access Token URL using POST. The request contains the following 558 parameters: 560 wrap_name 561 REQUIRED. The account name. 563 wrap_password 564 REQUIRED. The account password. 566 wrap_scope 567 OPTIONAL. The Authorization Server MAY define authorization scope 568 values for the Client to include. 570 Additional parameters 571 Any additional parameters, as defined by the Authorization Server. 573 5.1.3. Successful Access Token Response from Authorization Server 575 If successful, the Authorization Server returns: 577 HTTP 200 OK 579 with the Refresh Token and an Access Token in the response body. The 580 response body contains the following parameters: 582 wrap_refresh_token 583 REQUIRED. The Refresh Token. 585 wrap_access_token 586 REQUIRED. The Access Token. 588 wrap_access_token_expires_in 589 OPTIONAL. The lifetime of the Access Token in seconds. For 590 example, 3600 represents one hour. 592 Additional parameters 593 Any additional parameters, as defined by the Authorization Server. 595 The Client may now use the Access Token to access the Protected 596 Resource per Section 4 598 5.1.4. Unsuccessful Access Token Response from Authorization Server 600 If the Client account name and password are invalid, the 601 Authorization Server MUST respond with: 603 HTTP 401 Unauthorized 605 and the HTTP header: 607 WWW-Authenticate: WRAP 609 The Client MUST obtain a valid account name and password before 610 retrying the request. 612 5.1.5. Client Refreshes Access Token 614 Authorization Servers SHOULD issue Access Tokens that expire and 615 require Clients to refresh them. Upon receiving the HTTP 401 616 response when accessing protected resources per Section 4, the Client 617 should request a new Access Token by repeating Section 5.1.2 619 5.2. Assertion Profile 621 5.2.1. Provisioning 623 Prior to initiating this protocol profile, the Client MUST have a 624 mechanism for obtained an assertion from an assertion issuer that can 625 be presented to the Authorization Server for access to the Protected 626 Resource. 628 5.2.2. Client Obtains Assertion 630 The Client obtains an assertion. The process for obtaining the 631 assertion is defined by the assertion issuer and the Authorization 632 Server, and is out of scope of this specification. 634 5.2.3. Client Requests Access Token 636 The Client makes an HTTPS request to the Authorization Server's 637 Access Token URL using POST. The request contains the following 638 parameters: 640 wrap_assertion_format 641 REQUIRED. The format of the assertion as defined by the 642 Authorization Server. 644 wrap_assertion 645 REQUIRED. The assertion. 647 wrap_scope 648 OPTIONAL. The Authorization Server MAY define authorization scope 649 values for the Client to include 651 Additional parameters 652 Any additional parameters, as defined by the Authorization Server. 654 5.2.4. Successful Access Token Response from Authorization Server 656 If successful, the Authorization Server returns: 658 HTTP 200 OK 660 with the Access Token in the response body. The response body 661 contains the following parameters: 663 wrap_access_token 664 REQUIRED. The Access Token. 666 wrap_access_token_expires_in 667 OPTIONAL. The lifetime of the Access Token in seconds. For 668 example, 3600 represents one hour. 670 Additional parameters 671 Any additional parameters, as defined by the Authorization Server. 673 The Client may now use the Access Token to access the Protected 674 Resource per Section 4. 676 5.2.5. Unsuccessful Access Token Response from Authorization Server 678 If the assertion is not valid, the Authorization Server MUST respond 679 with: 681 HTTP 401 Unauthorized 683 and the HTTP header: 685 WWW-Authenticate: WRAP 687 The Client MUST obtain a valid assertion by repeating Section 5.2.2 688 before retrying the request. 690 5.2.6. Client Refreshes Access Token 692 Authorization Servers SHOULD issue Access Tokens that expire and 693 require Clients to refresh them. Upon receiving the HTTP 401 694 response when accessing protected resources per Section 4, the Client 695 should request a new Access Token by repeating Section 5.2.3 if the 696 assertion is still valid, otherwise the Client MUST obtain a new, 697 valid assertion by repeating Section 5.2.2. 699 5.3. Username and Password Profile 701 This profile is suitable where the Client is an application the User 702 has installed on their computer and the User uses a username and 703 password to authenticate to the Authorization Server. This profile 704 enables a Client to act on behalf of the User without having to 705 permanently store the User's username and password. 707 5.3.1. Provisioning 709 Prior to initiating this protocol profile, the Authorization Server 710 MAY have required the Client to have obtained a Client Identifier 711 from the Authorization Server. 713 5.3.2. Client Obtains Username and Password 715 The Client obtains the User's username and password from the user. 716 The Client MUST discard the username and password once an Access 717 Token has been obtained. 719 5.3.3. Client Requests Access Token 721 The Client makes an HTTPS request to the Authorization Server's 722 Access Token URL using POST. The request contains the following 723 parameters: 725 wrap_client_id 726 REQUIRED. The Client Identifier. 728 wrap_username 729 REQUIRED. The User's username. 731 wrap_password 732 REQUIRED. The User's password. 734 wrap_scope 735 OPTIONAL. The Authorization Server MAY define authorization scope 736 values for the Client to include. 738 Additional parameters 739 Any additional parameters, as defined by the Authorization Server. 741 5.3.4. Successful Access Token Response from Authorization Server 743 If successful, the Authorization Server returns: 745 HTTP 200 OK 747 with the Access Token in the response body. The response body 748 contains the following parameters: 750 wrap_access_token 751 REQUIRED. The Access Token. 753 wrap_access_token_expires_in 754 OPTIONAL. The lifetime of the Access Token in seconds. For 755 example, 3600 represents one hour. 757 Additional parameters 758 Any additional parameters, as defined by the Authorization Server. 760 The Client MUST discard the User's username and password. The Client 761 securely stores the Refresh Token for later use. The Client may now 762 use the Access Token to access the Protected Resource per Section 4. 764 5.3.5. Unsuccessful Access Token Response from Authorization Server 766 The Authorization Server MUST verify User's username and password. 767 If the verification fails, the Authorization Server MUST respond 768 with: 770 HTTP 401 Unauthorized 772 and the HTTP header: 774 WWW-Authenticate: WRAP 776 The Client needs to obtain a valid username and password from the 777 User per Section 5.3.2 before retrying the request. 779 5.3.6. Verification URL Response from Authorization Server 781 If the Authorization Server determines that the Client may be 782 malicious, the Authorization Server MAY require the Client to 783 instruct the User to visit a Verification URL. The Authorization 784 Server communicates its requirement by responding to the Client's 785 Access Token request with the following: 787 HTTP 400 Bad Request 789 and the body of the Authorization Server response contains the 790 following parameter: 792 wrap_verification_url 793 REQUIRED. The verification URL that the Client MUST either load 794 in the User's browser, or display for the User to enter into a 795 browser. 797 The Client MUST then wait for the User to indicate they have 798 successfully completed the verification process at the Authorization 799 Server and attempt to obtain an Access Token Refresh Token per 800 Section 5.3.3 again. 802 5.3.7. CAPTCHA Response from Authorization Server 804 If the Authorization Server determines that the Client may be 805 malicious, the Authorization Server MAY require the Client to have 806 the User solve a CAPTCHA Puzzle. The Authorization Server 807 communicates its requirement by responding to the Client's Access 808 Token request with the following: 810 HTTP 400 Bad Request 812 and the body of the Authorization Server response contains the 813 following parameter: 815 wrap_captcha_url 816 REQUIRED. The URL to the CAPTCHA puzzle. 818 The Client MUST present the User with the CAPTCHA puzzle and prompt 819 for a solution. The Client then MAY attempt to obtain an Access 820 Token per Section 5.3.3 again, including the following additional 821 parameter: 823 wrap_captcha_url 824 REQUIRED. The URL to the CAPTCHA puzzle received from the 825 Authorization Server. 827 wrap_captcha_solution 828 REQUIRED. The solution string to the CAPTCHA puzzle. 830 5.3.8. Client Refreshes Access Token 832 Refreshing an Access Token is the same in Section 5.3, Section 5.4, 833 and Section 5.5. Authorization Servers SHOULD issue Access Tokens 834 that expire and require Clients to refresh them. Upon receiving the 835 HTTP 401 response when accessing protected resources per Section 4, 836 the Client makes an HTTPS request to the Authorization Server's 837 Refresh Token URL using POST. The request contains the following 838 parameters: 840 wrap_refresh_token 841 REQUIRED. The Refresh Token that was received in Section 5.3.3 843 Additional parameters: 844 Any additional parameters, as defined by the Authorization Server. 846 5.3.9. Successful Access Token Refresh 848 If successful, the Authorization Server returns: 850 HTTP 200 OK 852 with the Access Token in the response body. The response body 853 contains the following parameters: 855 wrap_access_token 856 REQUIRED. The Access Token. 858 wrap_access_token_expires_in 859 OPTIONAL. The lifetime of the Access Token in seconds. For 860 example, 3600 represents one hour. 862 Additional parameters 863 Any additional parameters, as defined by the Authorization Server. 865 5.3.10. Unsuccessful Access Token Refresh 867 The Authorization Server MUST verify the Refresh Token. If the 868 verification fails, the Authorization Server MUST respond with 870 HTTP 401 Unauthorized 872 and the HTTP header: 874 WWW-Authenticate: WRAP 876 The Client MUST again request authorization from the User by 877 prompting for the User's username and password per Section 5.3.2 878 before retrying the request. 880 5.4. Web App Profile 882 This profile is suitable when the Client is a web application calling 883 the Protected Resource on behalf of a User. This profile enables a 884 Client to act on behalf of the User without acquiring a User's 885 credentials. 887 5.4.1. Provisioning 889 Prior to initiating this protocol profile, the Client MUST have 890 obtained a Client Identifier and Client Secret from the Authorization 891 Server. The Authorization Server MAY have also required the Client 892 to register the Callback URL. 894 5.4.2. Client Directs the User to the Authorization Server 896 The Client initiates an authorization request by redirecting the 897 User's browser to the Authorization Server's User Authorization URL, 898 with the following parameters: 900 wrap_client_id 901 REQUIRED. The Client Identifier. 903 wrap_callback 904 REQUIRED. The Callback URL. An absolute URL to which the 905 Authorization Server will redirect the User back after the User 906 has approved the authorization request. Authorization Servers MAY 907 require that the wrap_callback URL match the previously registered 908 value for the Client Identifier. 910 wrap_client_state 911 OPTIONAL. An opaque value that Clients can use to maintain state 912 associated with this request. If this value is present, the 913 Authorization Server MUST return it to the Client's Callback URL. 915 wrap_scope 916 OPTIONAL. The Authorization Server MAY define authorization scope 917 values for the Client to include. 919 Additional parameters 920 Any additional parameters, as defined by the Authorization Server. 922 5.4.3. Authorization Server Confirms Authorization Request with User 924 Upon receiving an authorization request from the Client by a 925 redirection of the User's browser, the Authorization Server 926 authenticates the user, presents the User with the Protected Resource 927 access that will be granted to the Client, and prompts the User to 928 confirm the request. 930 If the User denies the request, the Authorization Server MAY allow 931 the User to return to the Client Callback URL with the following 932 parameters added: 934 wrap_error_reason 935 REQUIRED. Value is user_denied 937 wrap_client_state 938 REQUIRED if the Client sent the value in the authorization request 939 in Section 5.4.2 941 If the User approves the request, the Authorization Server generates 942 a Verification Code and associates it with the Client Identifier and 943 Callback URL. 945 5.4.4. Authorization Server Directs User back to the Client 947 If the User approved the request, the Authorization Server MUST 948 redirect the User back to the Callback URL, with the following 949 parameters added: 951 wrap_verification_code 952 REQUIRED. The Verification Code. 954 wrap_client_state 955 REQUIRED if the Client sent the value in the authorization request 956 in Section 5.4.2 958 Additional parameters: 959 Any additional parameters, as defined by the Authorization Server. 961 5.4.5. Client Requests Access Token 963 If the User approved the request, the Authorization Server MUST 964 redirect the User back to the Callback URL, with the following 965 parameters added: 967 wrap_client_id 968 REQUIRED. The Client Identifier 970 wrap_client_secret 971 REQUIRED. The Client Secret 973 wrap_verification_code 974 REQUIRED. The Verification Code. 976 wrap_callback 977 REQUIRED. The Callback URL used to obtain the Verification Code. 979 Additional parameters: 980 Any additional parameters, as defined by the Authorization Server. 982 5.4.6. Successful Access Token Response from Authorization Server 984 After receiving the Access Token request, the Authorization Server 985 verifies the request as follows: 987 the Client Secret MUST match the Client Identifer 989 the Client Identifier MUST match the Client Identifier from the 990 authorization redirect 992 the Verification Code MUST match the Client Identifier from the 993 authorization redirect 995 the Callback URL MUST match the Callback URL from the 996 authorization redirect 998 the Verification Code MUST not have expired 1000 The Authorization Server MAY also require that a Verification Code is 1001 not reused. 1003 If verification is successful, the Authorization Server returns: 1005 HTTP 200 OK 1007 with the Refresh Token and the Access Token in the response body. 1008 The response body contains the following parameters: 1010 wrap_refresh_token 1011 REQUIRED. The Refresh Token. 1013 wrap_access_token 1014 REQUIRED. The Access Token. 1016 wrap_access_token_expires_in 1017 OPTIONAL. The lifetime of the Access Token in seconds. For 1018 example, 3600 represents one hour. 1020 Additional parameters 1021 Any additional parameters, as defined by the Authorization Server. 1023 The Client securely stores the Refresh Token for later use. The 1024 Client may now use the Access Token to access the Protected Resource 1025 per Section 4. 1027 5.4.7. Unsuccessful Access Token Response from Authorization Server 1029 The Authorization Server MUST first verify the Client Identifier and 1030 Client Secret. If they are invalid, the Authorization Server MUST 1031 respond with: 1033 HTTP 401 Unauthorized 1035 and the HTTP header: 1037 WWW-Authenticate: WRAP 1039 The Client MUST obtain a valid Client Identifier and Client Secret 1040 before retrying the request. 1042 The Authorization Server MUST then verify that the Callback URL and 1043 Verification Code are associated with the Client Identifier. If the 1044 verification fails, the Authorization Server MUST respond with: 1046 HTTP 400 Bad Request 1048 and the body of the Authorization Server response contains the 1049 following parameters: 1051 wrap_error_reason 1052 OPTIONAL. If all the parameters are valid except that the 1053 Verification Code has expired or been revoked, then it is 1054 RECOMMENDED that this parameter be included and if so, then the 1055 value MUST be: 1057 expired_verification_code 1058 This enables the Client to detect it needs a new Verification Code 1059 and to direct the User to the Authorization Server per 1060 Section 5.4.2 1062 If the Callback URL is invalid, the value MUST be: 1064 invalid_callback 1066 Additional parameters 1067 Any additional parameters, as defined by the Authorization Server. 1069 5.4.8. Client Refreshes Access Token 1071 Refreshing an Access Token is the same in Section 5.3, Section 5.4, 1072 and Section 5.5. Authorization Servers SHOULD issue Access Tokens 1073 that expire and require Clients to refresh them. Upon receiving the 1074 HTTP 401 response when accessing protected resources per Section 4, 1075 the Client makes an HTTPS request to the Authorization Server's 1076 Refresh Token URL using POST. The request contains the following 1077 parameters: 1079 wrap_refresh_token 1080 REQUIRED. The Refresh Token that was received in Section 5.4.5 1082 Additional parameters: 1083 Any additional parameters, as defined by the Authorization Server. 1085 5.4.9. Successful Access Token Refresh 1087 If successful, the Authorization Server returns: 1089 HTTP 200 OK 1091 with the Access Token in the response body. The response body 1092 contains the following parameters: 1094 wrap_access_token 1095 REQUIRED. The Access Token. 1097 wrap_access_token_expires_in 1098 OPTIONAL. The lifetime of the Access Token in seconds. For 1099 example, 3600 represents one hour. 1101 Additional parameters 1102 Any additional parameters, as defined by the Authorization Server. 1104 5.4.10. Unsuccessful Access Token Refresh 1106 The Authorization Server MUST verify the Refresh Token. If the 1107 verification fails, the Authorization Server MUST respond with 1109 HTTP 401 Unauthorized 1111 and the HTTP header: 1113 WWW-Authenticate: WRAP 1115 The Client MUST again request authorization from the User per 1116 Section 5.4.2. 1118 5.5. Rich App Profile 1120 This profile is suitable where the Client is an application the User 1121 has installed on their computer and there is a browser available for 1122 the Client to launch. This profile enables a Client to act on behalf 1123 of the User regardless of how the User authenticates to the Server 1124 and without access to the User's credentials. 1126 5.5.1. Provisioning 1128 Prior to initiating this protocol profile, the Client MAY be required 1129 to register the Client Identifier and/or the Callback URL with the 1130 Server. 1132 5.5.2. Client Directs the User to the Authorization Server 1134 The Client initiates an authorization request by opening the User's 1135 browser with the Server's User Authorization URL, and including the 1136 following parameters: 1138 wrap_client_id 1139 REQUIRED. The Client Identifier. 1141 wrap_callback 1142 OPTIONAL. A Callback URL where the Authorization Server MAY 1143 redirect the User's browser after the User responds to the 1144 authorization request. 1146 wrap_client_state 1147 OPTIONAL. An opaque value that Clients can use to maintain state 1148 associated with this request. If this value is present, the 1149 Authorization Server MUST return it to the Client's Callback URL. 1151 wrap_scope 1152 OPTIONAL. The Authorization Server MAY define authorization scope 1153 values for the Client to include. 1155 Additional parameters 1156 Any additional parameters, as defined by the Authorization Server. 1158 5.5.3. Authorization Server Confirms Authorization Request with User 1160 Upon receiving an authorization request from the Client by way of the 1161 User's browser, the Authorization Server authenticates the user, 1162 presents the User with the Protected Resource access that will be 1163 granted to the Client, and prompts the User to confirm the request. 1164 If the User approves the request, the Authorization Server generates 1165 a Verification Code. If the User denied access, the Authorization 1166 Server MAY set the Verification Code to the reserved value: 1168 user_denied 1170 It is RECOMMENDED the Verification Code be single use, and expire 1171 within minutes of issue. There are a number of mechanisms for the 1172 Authorization Server to transmit the Verification Code to the Client, 1173 specified below. 1175 Rich Application interaction with the User and the Authorization 1176 Server is an area of active research and development. If the Rich 1177 Application is able to retrieve the verifier directly from the 1178 callback URL returned by the Authorization Server, an improved user 1179 experience is possible. However, not all applications are able to 1180 interact with the Authorization Server in this manner. 1182 5.5.3.1. Applications with Callback URLs 1184 Rich Applications may be able to receive callback URLs in any of 1185 several ways. For example, the Rich Application may register a 1186 custom protocol handler with the application platform so that the 1187 application will be invoked when the browser is redirected to the 1188 callback URL. Alternatively, the callback URL may point to a web 1189 site with which the Rich Application has a trust relationship. The 1190 web site can then pass the Callback URL down to the Rich Application 1191 for processing. Finally, the Callback URL may point to a web site 1192 that will display the Callback URL to the screen along with 1193 instructions for the user to enter the Verification Code into the 1194 application. 1196 For Rich Applications with a Callback URL, the Authorization Server 1197 MUST redirect the User back to the Callback URL, with the following 1198 parameters added: 1200 wrap_verification_code 1201 REQUIRED. The Verification Code 1203 wrap_client_state 1204 REQUIRED if the Client sent the value in the authorization request 1205 in Section 5.5.2 1207 Additional parameters 1208 Any additional parameters, as defined by the Authorization Server. 1210 If the User denied access, the Server MAY redirect the User's browser 1211 to the Callback URL with the Verification Code set to the reserved 1212 value: 1214 user_denied 1216 5.5.3.2. Applications without Callback URLs 1218 Rich Applications without Callback URLs need to receive the 1219 verification code in other ways. For Rich Applications without a 1220 Callback URL, the Authorization Server MUST present the Verification 1221 Code on the web page and instruct the user to enter it into the 1222 Client. 1224 The Server MAY also append the Verification Code to the title of the 1225 HTML page so that Clients that have access to the title of the 1226 browser's current page can obtain the Verification Code without 1227 requiring the User enter the Verification Code into the Client. The 1228 Client can parse the title looking for "code=" and then the rest of 1229 the title is the Verification Code. If adding the Verification Code 1230 to the title of the HTML page, the Server MUST also include the 1231 wrap_client_state parameter if sent from the Client as the "state=" 1232 parameter. 1234 Eg. For example.com where the Verification Code = WF34F7HG and 1235 Client State = NMMGFJJ, the Server would set the title of the page to 1236 something like: 1237 Successful delegation, code=WF34F7HG 1238 state=NMMGFJJ 1240 If the User denied access, the Server MAY append code=user_denied to 1241 the title of the HTML page so that the Client can detect that the 1242 User has denied access. 1244 5.5.4. Client Requests Access Token 1246 The Client makes an HTTPS request to the Server's Access Token URL 1247 using POST. The request contains the following parameters: 1249 wrap_client_id 1250 REQUIRED. The Client Identifier 1252 wrap_verification_code 1253 REQUIRED. The Verification Code. 1255 Additional parameters: 1256 Any additional parameters, as defined by the Authorization Server. 1258 5.5.5. Successful Access Token Response from Authorization Server 1260 The Server checks the Verification Code was previously issued to the 1261 same Client Display Name, has not expired and has not been used. If 1262 these conditions are met, the Server marks the Verification Code as 1263 being used and returns: 1265 HTTP 200 OK 1267 with the Refresh Token and an Access Token in the response body. The 1268 response body contains the following parameters: 1270 wrap_refresh_token 1271 REQUIRED. The Refresh Token. 1273 wrap_access_token 1274 REQUIRED. The Access Token. 1276 wrap_access_token_expires_in 1277 OPTIONAL. The lifetime of the Access Token in seconds. For 1278 example, 3600 represents one hour. 1280 Additional parameters 1281 Any additional parameters, as defined by the Authorization Server. 1283 The Client securely stores the Refresh Token for later use. The 1284 Client may now use the Access Token to access the Protected Resource 1285 per Section 4. 1287 5.5.6. Unsuccessful Access Token Response from Authorization Server 1289 The Authorization Server MUST first verify the Client Identifier and 1290 Client Secret. If they are invalid, the Authorization Server MUST 1291 respond with: 1293 HTTP 401 Unauthorized 1295 and the HTTP header: 1297 WWW-Authenticate: WRAP 1299 The Client needs to obtain a new Verification Code per Section 5.5.2. 1301 5.5.7. Client Refreshes Access Token 1303 Refreshing an Access Token is the same in Section 5.3, Section 5.4, 1304 and Section 5.5. Authorization Servers SHOULD issue Access Tokens 1305 that expire and require Clients to refresh them. Upon receiving the 1306 HTTP 401 response when accessing protected resources per Section 4, 1307 the Client makes an HTTPS request to the Authorization Server's 1308 Refresh Token URL using POST. The request contains the following 1309 parameters: 1311 wrap_refresh_token 1312 REQUIRED. The Refresh Token that was received in Section 5.5.4 1314 Additional parameters: 1315 Any additional parameters, as defined by the Authorization Server. 1317 5.5.8. Successful Access Token Refresh 1319 If successful, the Authorization Server returns: 1321 HTTP 200 OK 1323 with the Access Token in the response body. The response body 1324 contains the following parameters: 1326 wrap_access_token 1327 REQUIRED. The Access Token. 1329 wrap_access_token_expires_in 1330 OPTIONAL. The lifetime of the Access Token in seconds. For 1331 example, 3600 represents one hour. 1333 Additional parameters 1334 Any additional parameters, as defined by the Authorization Server. 1336 5.5.9. Unsuccessful Access Token Refresh 1338 The Authorization Server MUST verify the Refresh Token. If the 1339 verification fails, the Authorization Server MUST respond with 1341 HTTP 401 Unauthorized 1343 and the HTTP header: 1345 WWW-Authenticate: WRAP 1347 The Client MUST again request authorization from the User per 1348 Section 5.5.2. 1350 6. Parameter Considerations 1352 6.1. Authorization Server Request / Response Parameter Encoding 1354 All requests made directly to the Authorization Server use the HTTP 1355 POST method and the parameters MUST be in the body of the message and 1356 formatted as application/x-www-form-urlencoded per 17.13.4 of HTML 1357 4.01 [W3C.REC-html40-19980424]. 1359 Any parameters in the response from the Authorization Server MUST be 1360 in the body of the message and formatted as application/ 1361 x-www-form-urlencoded per 17.13.4 of HTML 4.01 1362 [W3C.REC-html40-19980424]. 1364 6.2. Parameter Size 1366 HTTP Headers 1367 Web servers often impose a maximum on the combined size of all 1368 HTTP headers ranging from 8KB to 16KB. The size of the Access 1369 Token should be small enough to ensure the total size of the HTTP 1370 headers does not exceed the limits of web servers. 1372 URLs 1373 Web servers and browsers often impose a maximum on the total 1374 length of the URL of as low as 2083 bytes. The length of URLs 1375 exposed by the Authorization Server and the length of parameters 1376 passed on a URL should be minimized so that the total length does 1377 not exceed this limit. 1379 6.3. Access Token Format 1381 OAuth WRAP does not specify the format of the Access Token. The 1382 format is mutually agreed to by the Authorization Server and the 1383 Protected Resource and is opaque to the Client. The Access Token 1384 format MUST consist of legal characters in an HTTP header per 1385 [Reference needed] 1387 The Simple Web Token (SWT) and JSON Web Token (JWT) are possible 1388 Access Token formats. 1390 [TBD: entropy recommendations for Access Token so that it remains 1391 secure during its lifetime] 1393 6.4. Refresh Token Format 1395 OAuth WRAP does not specify the format of the Refresh Token. The 1396 Refresh Token is both generated and consumed by the Authorization 1397 Server and is opaque to the Client and never exposed to the Protected 1398 Resource. The Refresh Token is a long lived credential, and should 1399 contain enough entropy that it cannot be guessed. The size 1400 limitations of the Access Token are not applicable to the Refresh 1401 Token as the Refresh Token is always in the body of an HTTP message. 1403 6.5. Additional Authorization Server Parameters 1405 The Authorization Server may define additional parameters to be 1406 included in are returned from calls to the Access Token URL or User 1407 Authorization URL. Parameters that start with wrap_ are reserved and 1408 may not be used. 1410 7. IANA Considerations 1412 This memo includes no request to IANA. 1414 8. Security Considerations 1416 TBD: need to put in all the security considerations for implementors. 1418 9. References 1420 9.1. Normative References 1422 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1423 Requirement Levels", BCP 14, RFC 2119, March 1997. 1425 [RFC2606] Eastlake, D. and A. Panitz, "Reserved Top Level DNS 1426 Names", BCP 32, RFC 2606, June 1999. 1428 [W3C.REC-html40-19980424] 1429 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.0 1430 Specification", World Wide Web Consortium 1431 Recommendation REC-html40-19980424, April 1998, 1432 . 1434 9.2. Informative References 1436 [I-D.narten-iana-considerations-rfc2434bis] 1437 Narten, T. and H. Alvestrand, "Guidelines for Writing an 1438 IANA Considerations Section in RFCs", 1439 draft-narten-iana-considerations-rfc2434bis-09 (work in 1440 progress), March 2008. 1442 [OAuth Core 1.0 Revision A] 1443 OAuth, OAuth Community., "OAuth Core 1.0 Revision A". 1445 Appendix A. Client Account and Password Profile Example 1447 In this example, crm.example.com is an application server that has a 1448 Protected Resource at https://crm.example.com/data. DataDumper is an 1449 application acting as a Client that periodically calls 1450 https://crm.exanmple.com/data. The Protected Resource trusts the 1451 Authorization Server auth.example.net to determine if a Client has 1452 access. 1454 A.1. Provisioning 1456 The Authorization Server documentation defines the Access Token URL 1457 as: 1459 https://auth.example.net/access_token 1461 The Authorization Server has defined that the parameter Audience be 1462 included in calls to the Access Token URL. 1464 The Client has been provisioned with the following: 1466 Client Account: datadumper Client Password: j2hw7GPsl0 1468 The Protected Resource and the Authorization Server have agreed to 1469 use a Simple Web Token (SWT) for the Access Token with the reserved 1470 attributes Issuer, Audience, ExpiresOn and the public attribute 1471 net.example.auth.account and have exchanged the following HMAC key 1472 value (expressed in base 64): 1474 3iK5ZYAoBQuOqSgF/YqlDw70HKRmbyXkrl5f4SJ4Toc= 1476 A.2. Client Requests Access Token 1478 The Client makes an HTTPS POST to: 1480 https://auth.example.net/access_token 1482 With the following message body: 1484 wrap_name=datadumper&wrap_password=j2hw7GPsl0&Audience=crm.example.com 1486 A.3. Successful Access Token Response from Authorization Server 1488 The Authorization Server checks that the Client Password j2hw7GPsl0 1489 is associated with the Client Name datadumper and that the Client is 1490 authorized to access crm.example.com. The Authorization Server notes 1491 the time is 2010-02-03T04:05:06Z, which is 1265198706 seconds since 1492 1970-01-01T0:0:0Z. The Authorization Server would like the Access 1493 Token to expire in an hour, so 3600 is added to the current time. 1494 The Authorization Server then uses the values: 1496 net.example.auth.account: 1497 datadumper ExpiresOn: 1265202306 (1265198706 + 3600) 1498 Audience: crm.example.com 1499 Issuer: auth.example.net 1501 and the agreed HMAC key to generate the following SWT: 1503 net.example.auth.account=datadumper&ExpiresOn=1265202306&Audience=crm. 1504 example.com&Issuer=auth.example.net&HMACSHA256=N9%2F%2F0tSos78Me36%2Bi 1505 oBH0sFKfd7eCsURlEIheoUbCJk%3D 1507 The Authorization Server then responds to the Clients HTTPS request 1508 with: 1510 HTTP 200 OK 1512 and the Access Token and lifetime of the Access Token as application/ 1513 x-www-form-urlencoded data in the body of the message as such: 1515 wrap_access_token=net.example.auth.account%3Ddatadumper%26ExpiresOn%3D 1516 1265202306%26Audience%3Dcrm.example.com%26Issuer%3Dauth.example.net%26 1517 HMACSHA256%3DN9%252F%252F0tSos78Me36%252BioBH0sFKfd7eCsURlEIheoUbCJk%2 1518 53D&wrap_access_token_expires_in=3600 1520 A.4. Client Calls Protected Resource 1522 The Client now has an Access Token valid for an hour. The Client 1523 makes an API call to: 1525 https://crm.example.com/data 1527 including the following HTTP header: 1529 Authorization: WRAP access_token="net.example.auth.account=datadumper& 1530 ExpiresOn=1265202306&Audience=crm.example.com&Issuer=auth.example.net& 1531 HMACSHA256=N9%2F%2F0tSos78Me36%2BioBH0sFKfd7eCsURlEIheoUbCJk%3D" 1533 The Protected Resources verifies the SWT and performs the Client's 1534 request per the authorization attributes in the SWT. 1536 Appendix B. Web App Profile Example 1538 In this example, Jane, the User, listens to music from 1539 music.example.com and updates her status at status.example.com. When 1540 listening to music, Jane would like her status to be updated at the 1541 start of each song. From an OAuth WRAP perspective, the Client is 1542 music.example.com, the Protected Resource is 1543 https://status.example.com/update, and auth.example.com is the 1544 Authorization Server trusted by status.example.com. 1546 B.1. Provisioning 1548 The Authorization Server documentation defines the following URLs: 1550 User Authorization URL: https://auth.example.com/user_authorization 1551 Access Token URL: https://auth.example.com/access_token 1552 Refresh Token URL: https://auth.example.com/refresh_token 1554 The Authorization Server has defined that if the Client wants 1555 authorization to update a User's status, that the Client include the 1556 wrap_scope parameter with the value status_update when requesting 1557 authorization. 1559 The Client has been provisioned with: 1561 Client Identifier: music.example.com 1562 Client Secret: 7F2986DF2342914A 1564 The Client has registered the Callback URL: 1566 https://music.example.com/auth_callback 1567 The Protected Resource and the Authorization Server have agreed to 1568 use a Simple Web Token (SWT) for the Access Token with the reserved 1569 attributes Issuer, Audience, ExpiresOn and the public attributes 1570 com.example.auth.account, com.example.auth.client and 1571 com.example.auth.scope. They have exchanged the following HMAC key 1572 value (expressed in base 64): 1574 Zt9JlL1QvPYRSCK9PgSjrxRUBWe7lbEYsZCdM+sJCF4= 1576 B.2. Client Directs the User to the Server 1578 Jane informs music.example.com that she would like her status at 1579 status.example.com to be updated when a new song starts playing. The 1580 music.example.com website maintains user sessions with a URL 1581 parameter named session which has the value Vn3IG2FRALSEQX2Nxr at 1582 this time for Jane. The Client will use wrap_client_state to 1583 maintain the session value. The Client redirects Jane's browser to 1584 the Authorization Server's User Authorization URL appending 1585 parameters for the Client Identifier, Callback URL, Client state and 1586 authorization scope. 1588 https://auth.example.com/user_authorization?wrap_client_id=music.examp 1589 le.com&wrap_callback=http%3A%2F%2Fmusic.example.com%2Fauth_callback&wr 1590 ap_client_state=Vn3IG2FRALSEQX2Nxr&wrap_scope=status_update 1592 B.3. Authorization Server Confirms Delegation Request with User 1594 The Authorization Server verifies the supplied Client Identifier 1595 music.example.com has been registered and has the Callback URL 1596 https://music.example.com/auth_callback. The Authorization Server 1597 authenticates that the User it is dealing with is Jane, and then asks 1598 Jane to authorize music.example.com to update Jane's status at 1599 status.example.com. Jane approves the request and the Authorization 1600 Server generates a Verification Code with the value 46YEXQjVit6T3nQ8, 1601 stores it with the Client Identifier, Callback URl and the current 1602 time. 1604 B.4. Server Directs User back to the Client 1606 The Server redirects Jane back to the Client's Callback URL with the 1607 Verification Code and Client State appended: 1609 https://music.example.com/auth_callback?wrap_verification_code=46YEXQj 1610 Vit6T3nQ8&wrap_client_state=Vn3IG2FRALSEQX2Nxr 1612 B.5. Client Requests Access Token 1614 The Client makes an HTTPS POST request to: 1616 https://auth.example.com/access_token 1618 With the following message body: 1620 wrap_client_id=music.example.com&wrap_client_secret=7F2986DF2342914A&w 1621 rap_verification_code=46YEXQjVit6T3nQ8&wrap_callback=http%3A%2F%2Fmusi 1622 c.example.com%2Fauth_callback 1624 B.6. Successful Access Token Response from Authorization Server 1626 The Authorization Server verifies that the Verification Code is still 1627 valid, has not been used, and is associated with the Client ID, 1628 Client Secret and Callback URL Password. The Authorization Server 1629 then generates a Refresh Token with the value: 1631 MfdWTc+v9MXhpc+d/csrKFMPfj1RySm6CzIjmTBGN6w= 1633 The Authorization Server notes the time is 2010-01-02T03:04:05Z, 1634 which is 1262430245 seconds since 1970-01-01T0:0:0Z. The 1635 Authorization Server then uses the values: 1637 com.example.auth.scope: status_updatea 1638 com.example.auth.account: Jane 1639 com.example.auth.client: music.example.com 1640 ExpiresOn: 1262433845 (1262430245 + 3600 seconds later) 1641 Audience: status.example.com 1642 Issuer: auth.example.com 1644 and the agreed HMAC key to generate the following SWT: 1646 com.example.auth.scope=status_update&com.example.auth.account=Jane&com 1647 .example.auth.client=music.example.com&ExpiresOn=1262433845&Audience=s 1648 tatus.example.com&Issuer=auth.example.com&HMACSHA256=3xZAYzJRtYCQgkAF3 1649 iqElp1DhyKkPhq947j04NcDocQ%3D 1651 The Authorization Server then responds to the Clients HTTPS request 1652 with: 1654 HTTP 200 OK 1656 and the Refresh Token, Access Token and lifetime of the Access Token 1657 as application/x-www-form-urlencoded data in the body of the message 1658 as such: 1660 wrap_refresh_token=MfdWTc%2Bv9MXhpc%2Bd%2FcsrKFMPfj1RySm6CzIjmTBGN6w%3 1661 D&wrap_access_token=com.example.auth.scope%3Dstatus_update%26com.examp 1662 le.auth.account%3DJane%26com.example.auth.client%3Dmusic.example.com%2 1663 6ExpiresOn%3D1262433845%26Audience%3Dstatus.example.com%26Issuer%3Daut 1664 h.example.com%26HMACSHA256%3D3xZAYzJRtYCQgkAF3iqElp1DhyKkPhq947j04NcDo 1665 cQ%253D&wrap_access_token_expires_in=3600 1667 The Client now has a Refresh Token and Access Token valid for an 1668 hour. The Client stores the Refresh Token for later use. 1670 B.7. Client Calls Protected Resource 1672 A few minutes later, music.example.com starts playing a new song for 1673 Jane. The Client updates Jane's status at status.example.com by 1674 making an API call to: 1676 https://status.example.com/update 1678 including the following HTTP header: 1680 Authorization: WRAP access_token="com.example.auth.scope=status_update 1681 &com.example.auth.account=Jane&com.example.auth.client=music.example.c 1682 om&ExpiresOn=1262433845&Audience=status.example.com&Issuer=auth.exampl 1683 e.com&HMACSHA256=3xZAYzJRtYCQgkAF3iqElp1DhyKkPhq947j04NcDocQ%3D" 1685 The Protected Resources verifies the SWT, confirms the authorization 1686 contained in the SWT, and updates Jane's status. 1688 B.8. Client Calls Refreshes Access Token 1690 An hour passes by and music.example.com starts playing another new 1691 song for Jane. The Client again makes an API call to 1692 status.example.com including the same HTTP Authorization header. 1693 Unlike previous calls where the status update was performed, the 1694 Protected Resource returns the following error response: 1696 HTTP 401 Unauthorized 1698 and the HTTP header: 1700 WWW-Authenticate: WRAP 1702 The Client determines it probably needs a new Access Token, retrieves 1703 the Refresh Token and makes an HTTPS POST to: 1705 https://auth.example.com/refresh_token 1707 including the Client Identifier, Client Secret and Refresh Token in 1708 the message body as: 1710 wrap_client_id=music.example.com&wrap_client_secret=7F2986DF2342914A&w 1711 rap_refresh_token=MfdWTc%2Bv9MXhpc%2Bd%2FcsrKFMPfj1RySm6CzIjmTBGN6w%3D 1713 The Authorization Server looks up the data associated with the 1714 Refresh Token, determines music.example.com is still authorized to 1715 update Jane's status, and determines it will generate a new Access 1716 Token for the Client that expires in an hour. The time is now 2010- 1717 01-02T04:15:23Z, which results in an Access Token expiry time of 1718 1262438123 seconds since 1970-01-01T0:0:0Z. The Authorization Server 1719 generates a new Access Token and returns it in the body of the 1720 message as: 1722 wrap_access_token=com.example.auth.scope=status_update&com.example.aut 1723 h.account=Jane&com.example.auth.client=music.example.com&ExpiresOn=126 1724 2438123&Audience=status.example.com&Issuer=auth.example.com&HMACSHA256 1725 =AT4TFChHgyylItEWAjK7MFRJuvUS3WLVzO%2F68gvIRQI%3D&wrap_access_token_ex 1726 pires_in=3600 1728 The Client takes the new Access Token and uses it to successfully 1729 update Jane's status at status.example.com. 1731 Authors' Addresses 1733 Dick Hardt (editor) 1734 Microsoft 1736 Email: dick.hardt@microsoft.com 1738 Allen Tom 1739 Yahoo! 1741 Email: atom@yahoo-inc.com 1743 Brian Eaton 1744 Google 1746 Email: beaton@google.com 1747 Yaron Goland 1748 Microsoft 1750 Email: yarong@microsoft.com