idnits 2.17.1 draft-hunt-oauth-software-statement-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (September 27, 2013) is 3862 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2246' is defined on line 723, but no explicit reference was found in the text == Unused Reference: 'RFC4627' is defined on line 726, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 733, but no explicit reference was found in the text == Unused Reference: 'RFC6125' is defined on line 739, but no explicit reference was found in the text == Unused Reference: 'RFC6750' is defined on line 748, but no explicit reference was found in the text == Outdated reference: A later version (-41) exists of draft-ietf-jose-json-web-key-16 == Outdated reference: A later version (-18) exists of draft-ietf-oauth-assertions-12 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-jwt-bearer-06 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-17 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth P. Hunt, Ed. 3 Internet-Draft Oracle Corporation 4 Intended status: Standards Track T. Nadalin 5 Expires: March 31, 2014 Microsoft 6 September 27, 2013 8 OAuth 2.0 Software Statement 9 draft-hunt-oauth-software-statement-00 11 Abstract 13 This specification defines a JWT authorization assertion known as a 14 'software statment' for use in an OAuth protected environment. A 15 software statement is a JWT assertion used by an OAuth client to 16 provide both informational and OAuth protocol related assertions that 17 aid service providers to recognize OAuth client software and its 18 expected behaviour within an OAuth Framework protected resource 19 environment. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 31, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 57 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Software Statement . . . . . . . . . . . . . . . . . . . . . 4 59 2.1. Software Statement Lifecycle . . . . . . . . . . . . . . 4 60 2.2. Statement Attributes . . . . . . . . . . . . . . . . . . 6 61 2.2.1. Singular Attributes . . . . . . . . . . . . . . . . . 7 62 2.2.2. Multi-valued Attributes . . . . . . . . . . . . . . . 9 63 2.2.3. Relationship Between Grant Types and Response Types . 10 64 2.2.4. Human Readable Client Metadata . . . . . . . . . . . 11 65 2.3. Software Statement Requirements . . . . . . . . . . . . . 12 66 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 67 3.1. OAuth Token Endpoint Authentication Methods Registry . . 13 68 3.1.1. Registration Template . . . . . . . . . . . . . . . . 14 69 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 14 70 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 71 5. Normative References . . . . . . . . . . . . . . . . . . . . 15 72 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 16 73 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 76 1. Introduction 78 The OAuth 2.0 Authorization Framework [RFC6749] is a framework by 79 which client applications use access tokens issued by authorization 80 servers to access to a service provider's software API endpoints. As 81 a framework, OAuth 2.0 enables many different flows by which a client 82 application may obtain an access token including delegated 83 authorization from a user. 85 This specification defines a JWT authorization assertion 86 [I-D.ietf-oauth-jwt-bearer] known as a 'software statment'. An 87 software statement is used by an OAuth client to provide both 88 informational and OAuth protocol [RFC6749] related assertions that 89 aid OAuth infrastructure to both recognize client software and 90 determine a client's expected requirements when accessing an OAuth 91 protected resource. 93 Applications using software statements, may typically go through 3 94 phases where: 96 o A software statement is generated and associated with a client 97 application. 98 o A service provider approves client software for use within its 99 domain on the basic of software_id, developer, or software 100 statment signing organization. 101 o And finally, where a particular instance of a client possessing a 102 software statement associates with a particular serivce provider. 104 1.1. Notational Conventions 106 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 107 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 108 document are to be interpreted as described in [RFC2119]. 110 Unless otherwise noted, all the protocol parameter names and values 111 are case sensitive. 113 1.2. Terminology 115 This specification uses the terms "Access Token", "Refresh Token", 116 "Authorization Code", "Authorization Grant", "Authorization Server", 117 "Authorization Endpoint", "Client", "Client Identifier", "Client 118 Secret", "Protected Resource", "Resource Owner", "Resource Server", 119 and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. 121 This specification uses the following additional terms: 123 Deployment Organization An administrative security domain under 124 which, a software API is deployed and protected by an OAuth 2.0 125 framework. In simple cloud deployments, the software API 126 publisher and the deployment organization may be the same. In 127 other scenarios, a software publisher may be working with many 128 different deployment organizations. 130 Software API Deployment A deployment instance of a software API that 131 is protected by OAuth 2.0 in a particular deployment organization 132 domain. For any particular software API, there may be one or 133 more deployments. A software API deployment typically has an 134 associated OAuth 2.0 authorization server endpoint as well as a 135 client registration endpoint. The means by which endpoints are 136 obtained (discovery) are out of scope for this specification. 138 Software API Publisher The organization that defines a particular 139 web accessible API that may deployed in one or more deployment 140 environments. A publisher may be any commercial, public, 141 private, or open source organization that is responsible for 142 publishing and distributing software that may be protected via 143 OAuth 2.0. A software API publisher may issue software 144 assertions which client developers use to distribute with their 145 software to facilitate registration. In some cases a software 146 API publisher and a client developer may be the same 147 organization. 149 Client Developer The person or organization that builds a client 150 software package and prepares it for distribution. A client 151 developer obtains a software assertion from a software publisher, 152 or self-generates one for the purposes of facilitating client 153 association. 155 Software Statement A signed JWT authorization token 156 [I-D.ietf-oauth-jwt-bearer] that asserts information about the 157 client software that may be used by registration system to 158 qualify clients for eligibility to register. To obtain a 159 statement, a client developer may generate a client specific 160 assertion, or a client developer may registers with a software 161 API publisher to obtain a software assertion. The statement is 162 distributed with all copies of a client application and may be 163 used during the client-to-service provider association process. 165 2. Software Statement 167 As per the introduction, a software statement is an 'authorization' 168 bearer token (as defined in Section 2.1 of 169 [I-D.ietf-oauth-jwt-bearer]) that carries assertions about a software 170 that MAY be used in one or more deployment organizations and is 171 shared by all instances of a client application. 173 A software statement IS NOT an authentication assertion. A software 174 statement is a signed set of assertions fixing both OAuth related 175 protocol values as well as informational assertions as a signed 176 assertion from a trusted party. A deployment organization MAY use 177 the statement to set access policy and to recognize client software 178 during registration or association processes. 180 2.1. Software Statement Lifecycle 182 Software statements are used in 3 stages in the lifecycle of an OAuth 183 enabled client application. A typical lifecycle flow is illustrated 184 in Figure 1 describing when a developer obtains a software statement 185 and how it is used within a deployment organization. 187 Client App 188 Developer 189 O (A) Obtain Software Statement **************** 190 \|/ <-------------------------------------- * Software API * 191 | * Publisher * 192 / \ **************** 193 | 194 | | 195 | | 196 |D S | A 197 |i o | p 198 |s f | p 199 |t t | r (B) 200 A |r w | o 201 p |i a | v 202 p |b r | a 203 |u e | l 204 |t | 205 |i | 206 |o | 207 |n *************|******** 208 v * v * 209 +------------+ * +---------------+ * 210 | Client App | (C) Present Software Statement * | OAuth 2.0 | * 211 | Instance | --------------------------------->| Authorization | * 212 +------------+ * | Server | * 213 * +---------------+ * 214 * OAuth 2.0 aware * 215 * Service Provider * 216 ********************** 217 Legend: 218 O 219 \|/ - Developer 220 | 221 / \ 223 +----+ 224 | | - Piece of software 225 | | 226 +----+ 228 ****** 229 * * - Organization 230 * * 231 ****** 233 Figure 1: Client Statement Lifecycle 235 (A) A client developer registers a clent application with a software 236 API publisher. The software publisher, upon approval, generates 237 a signed software statement that is returned to the developer. 238 Alternatively, a developer may self-sign a software statement. A 239 self-signed statement, while weaker from a trust perspective, 240 allows the provider to recognize and approve software (step B). 241 A statement ensures that all registration parameters for a client 242 are the same for every instance of a client deployed. The 243 advantage of having the software API publisher is that deploying 244 organizations MAY choose to pre-approve (step B) all software 245 signed by a common trusted organization. 247 This protocol and procedure for issuing a software statement to 248 the client app developer is out-of-scope of this document. This 249 document assumes that the client app developer has obtained such 250 a software statement already. 252 (B) When an administrator at a service provider obtains a software 253 statement, the administrator configures policies to accept or 254 reject a particular client software statement for use within a 255 deploying organization. An administrator may also configure 256 broader pre-approval policy that accepts software by name, 257 author, or signing organization, or other category that can be 258 derived from a software statement. 260 (C) A client instance conveys the software statement to the service 261 provider, as described in 262 [I-D.draft-hunt-oauth-client-association]. 264 2.2. Statement Attributes 266 The following are attributes that may be included in a software 267 statement. For each attribute defined, a qualifier (OPTIONAL, 268 RECOMMENDED, REQUIRED) is included that indicates the usage 269 requirement for the client. Unless otherwise stated, all client 270 schema attributes are String based values. For example, URIs, email 271 addresses, identifiers, are all defined as Strings. 273 Authorization servers MUST reject statements if it does not 274 understand the values of any of the following singular or multi- 275 valued attributes. An authorization server MAY override any value 276 (including any omitted values) provided in a statement or separately 277 during the association process and replace the requested value with a 278 default at the server's discretion. 280 Extensions and profiles of this specification MAY expand this list, 281 and authorization servers MUST accept all fields in this list. The 282 authorization server MUST ignore any additional parameters sent by 283 the Client that it does not understand. 285 2.2.1. Singular Attributes 287 The following is a list of attributes that MUST have only a SINGLE 288 value in a software statement. 290 software_id 291 REQUIRED. A unique identifier that identifies the software such 292 as a UUID. The identifier SHOULD NOT change when software 293 version changes or when a new installation instance is detected. 294 "software_id" is intended to help a registration endpoint 295 recognize a client's assertion that it is a prticular piece of 296 software. Because of this, software identifier is usually 297 associated with a particular client name. While the 298 OAuth"client_id"is linked to a client software deployment 299 instance, the "software_id" is an identifier shared between all 300 copies of the client software. Registration servers MAY use the 301 supplied software identifier to determine whether a particular 302 client software is approved or supported for use in the 303 deployment domain. 305 software_version 306 RECOMMENDED. A version identifier such as a UUID or a number. 307 Servers MAY use equality match to determine if a particular 308 client is a particular version. "software_version" SHOULD change 309 on any update to the client software. Registration servers MAY 310 use the software version and identity to determine whether a 311 particular client version is authorized for use in the deployment 312 domain. 314 client_name 315 RECOMMENDED. A human-readable name of the client to be presented 316 to the user. If omitted, the authorization server MAY display 317 the raw "software_id" value to the user instead. It is 318 RECOMMENDED that clients always send this field. The value of 319 this field MAY be internationalized as described in Human 320 Readable Client Metadata (Section 2.2.4). 322 client_uri 323 RECOMMENDED. A URL of the homepage of the client software. If 324 present, the server SHOULD display this URL to the end user in a 325 clickable fashion. It is RECOMMENDED that clients always send 326 this field. The value of this field MUST point to a valid Web 327 page. The value of this field MAY be internationalized as 328 described in Human Readable Client Metadata (Section 2.2.4). 330 jwks_uri 331 OPTIONAL. A URL for the client's JSON Web Key Set 332 [I-D.ietf-jose-json-web-key] document representing the client's 333 public keys. The value of this field MUST point to a valid JWK 334 Set. These keys MAY also be used for higher level protocols that 335 require signing or encryption. 337 logo_uri 338 OPTIONAL. A URL that references a logo image for the client. If 339 present, the server SHOULD display this image to the end user 340 during approval. The value of this field MUST point to a valid 341 image file. The value of this field MAY be internationalized as 342 described in Human Readable Client Metadata (Section 2.2.4). 344 policy_uri 345 OPTIONAL. A URL that points to a human-readable policy document 346 for the client. The authorization server SHOULD display this URL 347 to the End-User if it is given. The Policy usually describes how 348 an End-User's data will be used by the client. The value of this 349 field MUST point to a valid Web page. The value of this field 350 MAY be internationalized as described in Human Readable Client 351 Metadata (Section 2.2.4). 353 scope 354 OPTIONAL. A space separated list of scope values (as described 355 in Section 3.3 [RFC6749]) that the client can use when requesting 356 access tokens. The semantics of values in this list is service 357 specific. If omitted, an authorization server MAY register a 358 client with a default set of scopes. 360 targetEndpoint 361 RECOMMENDED. A generic URI of the service API the client is 362 registering for (often set by the software API publisher). 363 Clients requesting access to more than one target endpoint SHOULD 364 use a separate statement for each target. 366 token_endpoint_auth_method 367 OPTIONAL. Value containing the requested authentication method 368 for the Token Endpoint. The server MAY override the requested 369 value. Clients MUST check for a change in value in the 370 registration response. Values defined by this specification are: 372 * "none": The client is a public client as defined in OAuth 2.0 373 and does not have a client secret. 374 * "bearer": The client is will use a bearer assertion as defined 375 in Section 4.2 of [I-D.ietf-oauth-assertions]. 377 Additional values can be defined via the IANA OAuth Token 378 Endpoint Authentication Methods registry Section 3.1. Absolute 379 URIs can also be used as values for this parameter. If 380 unspecified or omitted, the default is "bearer". 382 tos_uri 383 OPTIONAL. A URL that points to a human-readable "Terms of 384 Service" document for the client. The authorization server 385 SHOULD display this URL to the End-User if it is given. The 386 Terms of Service usually describe a contractual relationship 387 between the End-User and the client that the End-User accepts 388 when authorizing the client. The value of this field MUST point 389 to a valid Web page. The value of this field MAY be 390 internationalized as described in Human Readable Client Metadata 391 (Section 2.2.4). 393 2.2.2. Multi-valued Attributes 395 The following is a list of multi-valued attributes that may be used 396 in a software statement. 398 contacts 399 OPTIONAL. One or more email addresses for people responsible for 400 this client. The authorization server MAY make these addresses 401 available to end users for support requests for the client. An 402 authorization server MAY use these email addresses as identifiers 403 for an administrative page for this client. 405 redirect_uris 406 RECOMMENDED. One or more redirect URI values for use in 407 redirect-based flows such as the Authorization Code and Implicit 408 grant types. authorization servers SHOULD require registration 409 of valid redirect URIs for all clients that use these grant types 410 to protect against token and credential theft attacks. 412 grant_types 413 OPTIONAL. One or more OAuth 2.0 grant types that the client may 414 use. These grant types are defined as follows: 416 * "authorization_code": The Authorization Code Grant described 417 in OAuth 2.0 Section 4.1 418 * "implicit": The Implicit Grant described in OAuth 2.0 419 Section 4.2 420 * "password": The Resource Owner Password Credentials Grant 421 described in OAuth 2.0 Section 4.3 422 * "client_credentials": The "Client credentials Grant" described 423 in OAuth 2.0 Section 4.4 424 * "refresh_token": The Refresh Token Grant described in OAuth 425 2.0 Section 6. 426 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 427 grant type defined in OAuth JWT Bearer Token Profiles 428 [I-D.ietf-oauth-jwt-bearer]. 430 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 431 Bearer grant type defined in OAuth SAML 2 Bearer Token 432 Profiles [I-D.ietf-oauth-saml2-bearer]. 434 Authorization servers MAY allow for other values as defined in 435 grant type extensions to OAuth 2.0. The extension process is 436 described in OAuth 2.0 Section 2.5, and the value of this 437 parameter MUST be the same as the value of the "grant_type" 438 parameter passed to the Token Endpoint defined in the extension. 440 response_types 441 OPTIONAL. One or more OAuth 2.0 response types that the client 442 may use. These response types are defined as follows: 444 * "code": The Authorization Code response described in OAuth 2.0 445 Section 4.1. 446 * "token": The Implicit response described in OAuth 2.0 447 Section 4.2. 449 Authorization servers MAY allow for other values as defined in 450 response type extensions to OAuth 2.0. The extension process is 451 described in OAuth 2.0 Section 2.5, and the value of this 452 parameter MUST be the same as the value of the "response_type" 453 parameter passed to the Authorization Endpoint defined in the 454 extension. 456 2.2.3. Relationship Between Grant Types and Response Types 458 The "grant_types" and "response_types" values described above are 459 partially orthogonal, as they refer to arguments passed to different 460 endpoints in the OAuth protocol. However, they are related in that 461 the "grant_types" available to a client influence the 462 "response_types" that the client is allowed to use, and vice versa. 463 For instance, a "grant_types" value that includes 464 "authorization_code" implies a "response_types" value that includes 465 code, as both values are defined as part of the OAuth 2.0 466 Authorization Code Grant. As such, a server supporting these fields 467 SHOULD take steps to ensure that a client cannot register itself into 468 an inconsistent state. 470 The correlation between the two fields is listed in the table below. 472 +-------------------------------------------------+-----------------+ 473 | grant_types value includes: | response_types | 474 | | value includes: | 475 +-------------------------------------------------+-----------------+ 476 | authorization_code | code | 477 | | | 478 | implicit | token | 479 | | | 480 | password | (none) | 481 | | | 482 | client_credentials | (none) | 483 | | | 484 | refresh_token | (none) | 485 | | | 486 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 487 | | | 488 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 489 +-------------------------------------------------+-----------------+ 491 Extensions and profiles of this document that introduce new values to 492 either the "grant_types" or "response_types" parameter MUST document 493 all correspondences between these two parameter types. 495 2.2.4. Human Readable Client Metadata 497 [[This needs to be updated to be compatible with SCIM. There is a 498 also a problem with how to limit the amount of localization data 499 exchange for an instance registration. Note that mobile clients tend 500 to only need one preferred language while web clients represent many 501 clients and may have more than 20 languages to support.]] 503 Human-readable Client Metadata values and client Metadata values that 504 reference human-readable values MAY be represented in multiple 505 languages and scripts. For example, the values of fields such as 506 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 507 might have multiple locale-specific values in some client 508 registrations. 510 To specify the languages and scripts, BCP47 [RFC5646] language tags 511 are added to client Metadata member names, delimited by a # 512 character. Since JSON member names are case sensitive, it is 513 RECOMMENDED that language tag values used in Claim Names be spelled 514 using the character case with which they are registered in the IANA 515 Language Subtag Registry [IANA.Language]. In particular, normally 516 language names are spelled with lowercase characters, region names 517 are spelled with uppercase characters, and languages are spelled with 518 mixed case characters. However, since BCP47 language tag values are 519 case insensitive, implementations SHOULD interpret the language tag 520 values supplied in a case insensitive manner. Per the 521 recommendations in BCP47, language tag values used in Metadata member 522 names should only be as specific as necessary. For instance, using 523 "fr" might be sufficient in many contexts, rather than "fr-CA" or 524 "fr-FR". 526 For example, a client could represent its name in English as 527 ""client_name#en": "My Client"" and its name in Japanese as 528 ""client_name#ja-Jpan-JP": 529 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 530 registration request. The authorization server MAY display any or 531 all of these names to the Resource Owner during the authorization 532 step, choosing which name to display based on system configuration, 533 user preferences or other factors. 535 If any human-readable field is sent without a language tag, parties 536 using it MUST NOT make any assumptions about the language, character 537 set, or script of the string value, and the string value MUST be used 538 as-is wherever it is presented in a user interface. To facilitate 539 interoperability, it is RECOMMENDED that clients and servers use a 540 human-readable field without any language tags in addition to any 541 language-specific fields, and it is RECOMMENDED that any human- 542 readable fields sent without language tags contain values suitable 543 for display on a wide variety of systems. 545 Implementer's Note: Many JSON libraries make it possible to reference 546 members of a JSON object as members of an Object construct in the 547 native programming environment of the library. However, while the 548 "#" character is a valid character inside of a JSON object's member 549 names, it is not a valid character for use in an object member name 550 in many programming environments. Therefore, implementations will 551 need to use alternative access forms for these claims. For instance, 552 in JavaScript, if one parses the JSON as follows, "var j = 553 JSON.parse(json);", then the member "client_name#en-us" can be 554 accessed using the JavaScript syntax "j["client_name#en-us"]". 556 2.3. Software Statement Requirements 558 In order to create and validate a software assertion, the following 559 requirements apply in addition to those stated in Section 3 560 [I-D.ietf-oauth-jwt-bearer]. 562 1. The JWT MAY contain any claim specified in Section 2.2. 563 2. The JWT MUST contain an "iss" (issuer) claim that contains a 564 unique identifier for the entity that issued and signed the JWT. 565 The value MAY be the client developer, a software API publisher, 566 or a third-party organization (e.g. a consortium) that would be 567 trusted by deploying organizations. 568 3. The JWT MUST contain a "sub" (subject) claim that contains a 569 unique value corresponding to the "software_id". This number is 570 MAY be assigned by the software API publisher. 571 4. The JWT MUST contain an "aud" (audience) claim containing a value 572 that is ONE of the following: 574 * A value that identifies one or more software API deployments, 575 where the client software MAY be registered. 576 * A value "urn:oauth:scim:reg:generic" which indicates the 577 assertion MAY be used with any software API deployment 578 environment. 579 5. The JWT MUST contain an "exp" (expiration) claim that limits the 580 time window during which the JWT can be used to register clients. 581 When registering clients, the registration server MUST verify 582 that the expiration time has not passed, subject to allowable 583 clock skew between systems, and reject expired JWTs. The 584 authorization server SHOULD NOT use this value to revoke an 585 existing client registration. 587 3. IANA Considerations 589 3.1. OAuth Token Endpoint Authentication Methods Registry 591 This specification establishes the OAuth Token Endpoint 592 Authentication Methods registry. 594 Additional values for use as "token_endpoint_auth_method" metadata 595 values are registered with a Specification Required ([RFC5226]) after 596 a two-week review period on the oauth-ext-review@ietf.org mailing 597 list, on the advice of one or more Designated Experts. However, to 598 allow for the allocation of values prior to publication, the 599 Designated Expert(s) may approve registration once they are satisfied 600 that such a specification will be published. 602 Registration requests must be sent to the oauth-ext-review@ietf.org 603 mailing list for review and comment, with an appropriate subject 604 (e.g., "Request to register token_endpoint_auth_method value: 605 example"). 607 Within the review period, the Designated Expert(s) will either 608 approve or deny the registration request, communicating this decision 609 to the review list and IANA. Denials should include an explanation 610 and, if applicable, suggestions as to how to make the request 611 successful. 613 IANA must only accept registry updates from the Designated Expert(s) 614 and should direct all requests for registration to the review mailing 615 list. 617 3.1.1. Registration Template 619 Token Endpoint Authorization Method name: 620 The name requested (e.g., "example"). This name is case 621 sensitive. Names that match other registered names in a case 622 insensitive manner SHOULD NOT be accepted. 624 Change controller: 625 For Standards Track RFCs, state "IETF". For others, give the name 626 of the responsible party. Other details (e.g., postal address, 627 email address, home page URI) may also be included. 629 Specification document(s): 630 Reference to the document(s) that specify the token endpoint 631 authorization method, preferably including a URI that can be used 632 to retrieve a copy of the document(s). An indication of the 633 relevant sections may also be included but is not required. 635 3.1.2. Initial Registry Contents 637 The OAuth Token Endpoint Authentication Methods registry's initial 638 contents are: 640 o Token Endpoint Authorization Method name: "none" 641 o Change controller: IETF 642 o Specification document(s): [[ this document ]] 644 o Token Endpoint Authorization Method name: "bearer" 645 o Change controller: IETF 646 o Specification document(s): [[ this document ]] 648 o Token Endpoint Authorization Method name: "client_secret_post" 649 o Change controller: IETF 650 o Specification document(s): [[ this document ]] 652 o Token Endpoint Authorization Method name: "client_secret_basic" 653 o Change controller: IETF 654 o Specification document(s): [[ this document ]] 656 4. Security Considerations 658 The authorization server MUST treat the overall software statements, 659 as self-asserted since there is no way to prove a client is the 660 software it asserts to be. A rogue client might use the name and 661 logo for the legitimate client, which it is trying to impersonate. 662 An authorization server needs to take steps to mitigate this phishing 663 risk, since the logo could confuse users into thinking they're 664 logging in to the legitimate client. For instance, an authorization 665 server could warn if the domain/site of the logo doesn't match the 666 domain/site of redirect URIs. An authorization server can also 667 present warning messages to end users about untrusted clients in all 668 cases, especially if such clients have been dynamically registered 669 and have not been trusted by any users at the authorization server 670 before. 672 Authorization servers MAY assume that registered client software 673 sharing the same software assertion, software_id, and other metadata 674 SHOULD have similar operational behaviour metrics. Similarly, 675 Authorization server administrators MAY use software_id and 676 software_version to facilitate normal change control and approval 677 management of client software including: 679 o Approval of specific clients software for use with specific 680 protected resources. 681 o Lifecycle management and support of specific software versions as 682 indicated by software_version. 683 o Revocation of groups of client credentials and associated access 684 tokens when support issues or security risks identified with a 685 particular client software as identified by software_id and 686 software_version. 688 5. Normative References 690 [I-D.draft-hunt-oauth-client-association] 691 Hunt, P., Ed. and T. Nadalin, "OAuth Client Association", 692 . 694 [I-D.ietf-jose-json-web-key] 695 Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 696 key-16 (work in progress), September 2013. 698 [I-D.ietf-oauth-assertions] 699 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 700 "Assertion Framework for OAuth 2.0 Client Authentication 701 and Authorization Grants", draft-ietf-oauth-assertions-12 702 (work in progress), July 2013. 704 [I-D.ietf-oauth-jwt-bearer] 705 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 706 (JWT) Profile for OAuth 2.0 Client Authentication and 707 Authorization Grants", draft-ietf-oauth-jwt-bearer-06 708 (work in progress), July 2013. 710 [I-D.ietf-oauth-saml2-bearer] 711 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 712 Profile for OAuth 2.0 Client Authentication and 713 Authorization Grants", draft-ietf-oauth-saml2-bearer-17 714 (work in progress), July 2013. 716 [IANA.Language] 717 Internet Assigned Numbers Authority (IANA), "Language 718 Subtag Registry", 2005. 720 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 721 Requirement Levels", BCP 14, RFC 2119, March 1997. 723 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 724 RFC 2246, January 1999. 726 [RFC4627] Crockford, D., "The application/json Media Type for 727 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 729 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 730 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 731 May 2008. 733 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 734 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 736 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 737 Languages", BCP 47, RFC 5646, September 2009. 739 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 740 Verification of Domain-Based Application Service Identity 741 within Internet Public Key Infrastructure Using X.509 742 (PKIX) Certificates in the Context of Transport Layer 743 Security (TLS)", RFC 6125, March 2011. 745 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 746 6749, October 2012. 748 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 749 Framework: Bearer Token Usage", RFC 6750, October 2012. 751 Appendix A. Acknowledgments 753 This draft was based upon in large part upon the work in draft-ietf- 754 oauth-dyn-reg-14, draft-richer-oauth-dyn-reg-core-00 and draft- 755 richer-oauth-dyn-reg-12 and WG discussions. The authors would like 756 to thank Justin Richer and the members of the OAuth Working Group. 758 Appendix B. Document History 760 [[ to be removed by the RFC editor before publication as an RFC ]] 761 -00 763 o First draft. 765 Authors' Addresses 767 Phil Hunt (editor) 768 Oracle Corporation 770 Email: phil.hunt@yahoo.com 772 Tony Nadalin 773 Microsoft 775 Email: tonynad@microsoft.com