idnits 2.17.1 draft-catalano-oauth-umaclaim-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** There are 8 instances of too long lines in the document, the longest one being 7 characters in excess of 72. == There are 7 instances of lines with non-RFC2606-compliant FQDNs in the document. 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 (July 20, 2014) is 3540 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) -- Looks like a reference, but probably isn't: '1' on line 643 -- Looks like a reference, but probably isn't: '2' on line 652 -- No information found for draft-uma-core - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'UMA' Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Catalano, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track M. Machulak 5 Expires: January 21, 2015 Cloud Identity 6 July 20, 2014 8 User-Managed Access (UMA) Claim Profiles Framework 9 draft-catalano-oauth-umaclaim-00 11 Abstract 13 User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how 14 resource owners can control protected-resource access by clients 15 operated by arbitrary requesting parties, where the resources reside 16 on any number of resource servers, and where a centralized 17 authorization server governs access based on resource owner policy. 18 This specification defines a generic framework for building UMA claim 19 profiles that can be used by client applications to obtain the 20 necessary authorization to access protected resources. This revision 21 of the specification is part of V0.9. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on January 21, 2015. 40 Copyright Notice 42 Copyright (c) 2014 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 59 2. Generic Framework for Claim Profiles . . . . . . . . . . . . 4 60 2.1. Client Provides Custom User Attributes . . . . . . . . . 6 61 2.2. Client Acts as SAML Assertion Conveyor . . . . . . . . . 8 62 2.3. Client Acts as OpenID Connect Claims Conveyor . . . . . . 9 63 2.4. Hybrid Approach: Client Acts as Custom Claims Conveyor 64 and OpenID Connect Claims Conveyor . . . . . . . . . . . 9 65 2.5. Client Redirects Requesting Party to AS . . . . . . . . . 10 66 2.5.1. Requesting Party Claims Endpoint . . . . . . . . . . 11 67 2.5.2. Message Flow . . . . . . . . . . . . . . . . . . . . 11 68 2.5.3. Examples . . . . . . . . . . . . . . . . . . . . . . 13 69 2.5.3.1. Authorization Server Acts as OpenID Connect 70 Relying Party . . . . . . . . . . . . . . . . . . 13 71 2.5.3.2. Authorization Server Acts as SAML Relying Party . 13 72 2.5.3.3. Authorization Server pulls Claim from local user 73 store . . . . . . . . . . . . . . . . . . . . . . 14 74 2.6. IANA Considerations . . . . . . . . . . . . . . . . . . . 14 75 2.7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 14 76 2.8. Issues . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 3. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 78 3.1. Normative References . . . . . . . . . . . . . . . . . . 14 79 3.2. Informative References . . . . . . . . . . . . . . . . . 14 80 3.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 15 81 Appendix A. Document History . . . . . . . . . . . . . . . . . . 15 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 84 1. Introduction 86 User-Managed Access [UMA] is a profile of OAuth 2.0. UMA defines how 87 resource owners can control protected-resource access by clients 88 operated by arbitrary requesting parties, where the resources reside 89 on any number of resource servers, and where a centralized 90 authorization server governs access based on resource owner policy. 91 This specification defines a generic framework for building UMA claim 92 profiles that can be used by client applications to obtain the 93 necessary authorization to access protected resources. 95 Using the framework defined in this specification, UMA deployers can 96 add new claim profiles to meet requirements of particular deployments 97 of UMA. Profiles built on this framework will give both 98 authorization servers and clients certain interoperability and ease 99 of development properties. This specification also provides some 100 sample profiles that build on the framework. Deployers can build on 101 the framework directly or on these sample profiles, as they wish, in 102 order to promote interoperability in their specific environments. 104 The framework introduces different interaction patterns that the 105 client and authorization server can use, and different roles they can 106 play, in order to gather claims about the requesting party: 108 o The ?delivery? interaction pattern leverages a ?claims-aware 109 client? that is able to deliver claims about the requesting party 110 (or information about how to get claims) directly to the 111 authorization server. The information delivered can be an 112 identity or claims token, data that aids in discovery of a claims 113 endpoint, etc., depending on the client's role outside of UMA as a 114 federated identity provider, a federated relying party, an 115 application integrated with a native identity repository, etc. 116 The authorization server then plays the role of a ?claims 117 receiver? (and/or activates a ?claims connector? based on the 118 information, for gathering claims itself without requesting party 119 involvement). 121 o The ?redirect? pattern assumes a ?claims-unaware client? whose 122 only option (other than failing entirely) is to redirect an end- 123 user requesting party to the authorization server. On receiving 124 the end user, the authorization server activates a ?claims 125 connector? for gathering the necessary claims with the user's 126 involvement, using any method or combination of methods. In this 127 role, the authorization server may be a relying party in a 128 federated identity interaction, or it may connect to a directory 129 or other user repository. After the claims-gathering process, the 130 authorization server redirects the user back to the client. 132 The profiles defined based on both interaction patterns are as 133 follows: 135 o Delivery: 137 * Client delivers a SAML assertion to the authorization server 139 * Client delivers OpenID Connect user claims to the authorization 140 server 142 * Client delivers custom user claims to the authorization server 143 * Client delivers custom and OpenID Connect user claims to the 144 authorization server 146 o Redirect: 148 * Client redirects end-user requesting party to the authorization 149 server 151 In all cases, it is assumed that the authorization server evaluates 152 the resource owner's policy for a particular resource set based, at 153 least in part, on the supplied claims. An authorization server MAY 154 support any claim profiles defined in this specification, and SHOULD 155 advertise its conformance to tbe profiles it supports in its 156 configuration data. 158 1.1. Notational Conventions 160 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 161 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 162 document are to be interpreted as described in [RFC2119]. 164 Unless otherwise noted, all the protocol properties and values are 165 case sensitive. 167 2. Generic Framework for Claim Profiles 169 When a client asks an authorization server to associate authorization 170 data with a requesting party token (RPT) so that the client can 171 successfully access a resource on behalf of the requesting party 172 operating it, the authorization can respond in three main ways: 173 either it can deny the client's request outright, or it can accede to 174 the request outright, or it can respond that it needs claims in order 175 to assess whether suitability of adding the needed authorization 176 data. The authorization server has an opportunity, when it returns a 177 "need_claims" response, to provide further instructions and hints to 178 the client in this response. This section defines extensions to 179 [UMA] that support these instructions and hints. 181 The authorization request endpoint in the authorization API presented 182 by the authorization server is extended to accept JSON-encoded 183 claims-related data in the body of the request. Along with the "rpt" 184 and "ticket" properties that already need to be provided, a "claims" 185 property appears in addition. 187 Common message flow: 189 1. The client sends the claims type and its claims directly to the 190 AS 192 POST /rpt_authorization HTTP/1.1 193 Host: www.nuveam.com 194 Authorization: Bearer jwfLG53^sad$#f 195 ... 197 { 198 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 199 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 200 "claims": [ 201 { 202 "type": "CLAIM_TYPE_AS_STRING", 203 "value": {SPECIFIC_SET_OF_CLAIMS_AS_JSON_OBJECT} 204 } 205 ] 206 } 208 Importantly, the claims MUST be an array of JSON objects. The type 209 field MUST have a String value indicating the type of claims-related 210 data, while the value field MUST be a JSON object specific to that 211 type of claims-related data. 213 2. The authorization server informs the client that authorization 214 data has been added 216 HTTP/1.1 201 Created 217 Content-Type: application/json;charset=UTF-8 219 { 220 "rpt":"e6b09a4f434a6a47a65a198652df381a" 221 } 223 3. The authorization server informs the client that further claims 224 should be provided to the authorization request endpoint: 226 HTTP/1.1 403 Forbidden 227 Content-Type: application/json 229 { 230 "need_claims":[ 231 { 232 "type":"CLAIM_TYPE_AS_STRING", 233 "name":"", 234 "value":"" 235 }] 236 } 237 4. The authorization server informs the client that further claims 238 should be provided (the example below is for SAML assertion) 240 HTTP/1.1 403 Forbidden 241 Content-Type: application/json 243 { 244 "need_claims":[ 245 { 246 "type":"claim-client-assertion-saml-1.0", 247 "name":"", 248 "value":"" 249 } 250 ] 251 } 253 5. The authorization server informs the client that the 254 authorization data cannot be added. 256 HTTP/1.1 403 Forbidden 257 Content-Type: application/json;charset=UTF-8 259 { 260 "error":"not_authorized_permission", 261 "error_description":"Authorization data cannot be added." 262 } 264 2.1. Client Provides Custom User Attributes 266 TYPE = "custom" 268 VALUE = {custom defined} 270 In the most trivial setting where the AS and the Client are 271 collocated and have an established trust relationship (in particular, 272 the AS trusts information that it receives from the client), then the 273 client can be preconfigured to provide the required information to 274 the AS based on a custom schema. We provide the most trivial example 275 below, where the client application provides a user's identifier (in 276 this case email) to the AS and such identifier is used for policy 277 evaluation. 279 Example: 281 POST /rpt_authorization HTTP/1.1 282 Host: www.nuveam.com 283 Authorization: Bearer jwfLG53^sad$#f 284 ... 286 { 287 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 288 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 289 "claims": [ 290 { 291 "type": "ci-nuveam-claims", 292 "value": { "email": "bob@company.example.com" } 293 } 294 ] 295 } 297 Another example is where the client provides a richer set of 298 attributes directly to the AS and these attributes are used for 299 policy evaluation. Importantly, it is the AS that decides which 300 attributes are used for policy evaluation and which are not. 302 Example: 304 POST /rpt_authorization HTTP/1.1 305 Host: www.nuveam.com 306 Authorization: Bearer jwfLG53^sad$#f 307 ... 309 { 310 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 311 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 312 "claims": [ 313 { 314 "type": "ci-nuveam-claims", 315 "value": { "email": "bob@gmail.com", "roles": [ "manager", "admin" ] } 316 } 317 ] 319 } 321 We provide an example of a reply below (standard UMA reply): 323 Example: 325 HTTP/1.1 201 Created 326 Content-Type: application/json 328 { 329 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv2" 330 } 332 In case of custom attributes, the client does not necessarily use any 333 specific protocol for obtaining user attributes. It can use a pre- 334 established relationship with the AS to provide the required set of 335 attributes. 337 2.2. Client Acts as SAML Assertion Conveyor 339 TYPE = "claim-client-assertion-saml-1.0" 341 VALUE = {base64-encoded SAML assertion} 343 In this setting the AS and the Client have a pre-established trust 344 relationship. The client may provide the AS with a SAML assertion 345 that can be used for policy evaluation. We provide an example of the 346 request below. 348 Example: 350 POST /rpt_authorization HTTP/1.1 351 Host: www.nuveam.com 352 Authorization: Bearer jwfLG53^sad$#f 353 ... 355 { 356 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 357 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 358 "claims": [ 359 { 360 "type": "claim-client-assertion-saml-1.0", 361 "value": { 362 "saml_assertion": "PHNhbWxwOl...[omitted for brevity]...ZT" 363 } 364 } 365 ] 367 } 369 2.3. Client Acts as OpenID Connect Claims Conveyor 371 TYPE = "claim-client-claims-oidc-1.0" 373 VALUE = {set of oidc reserved claims} 375 In this setting the AS and the Client have a pre-established trust 376 relationship. The client may provide the AS with a OpenID Connect 377 user claims that can be used for policy evaluation. We provide an 378 example of the request made by the client to the Authorization Server 379 below. 381 Example: 383 POST /rpt_authorization HTTP/1.1 384 Host: www.nuveam.com 385 Authorization: Bearer jwfLG53^sad$#f 386 ... 388 { 389 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 390 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 391 "claims": [ 392 { 393 "type": "claim-client-claims-oidc-1.0", 394 "value": { 395 "sub": "248289761001" 396 "name": "Jane Doe", 397 "given_name": "Jane", 398 "family_name": "Doe", 399 "email": "joedoe@example.com" 400 "email_verified": true, 401 } 402 } 403 ] 404 } 406 2.4. Hybrid Approach: Client Acts as Custom Claims Conveyor and OpenID 407 Connect Claims Conveyor 409 TYPE = "custom" 411 VALUE = {custom defined} 413 TYPE = "claim-client-claims-oidc-1.0" 415 VALUE = {set of oidc reserved claims} 416 In this setting the AS and the Client have a pre-established trust 417 relationship. The client may provide the AS with custom claims as 418 well as with OpenID Connect user claims that can be used for policy 419 evaluation. We provide an example of the request below. 421 Example: 423 POST /rpt_authorization HTTP/1.1 424 Host: www.nuveam.com 425 Authorization: Bearer jwfLG53^sad$#f 426 ... 427 { 428 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 429 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de", 430 "claims": [ 431 { 432 "type": "ci-nuveam-claims", 433 "value": { "roles": ["manager", "admin" } 434 }, 435 { 436 "type": "claim-client-claims-oidc-1.0", 437 "value": { "email": "bob@gmail.com" } 438 } 439 ] 440 } 442 2.5. Client Redirects Requesting Party to AS 444 TYPE = "claim-client-redirect-1.0" 446 VALUE = {value of the scope at AS} 448 The redirect UMA profile defines a Requesting Party Claims Endpoint 449 that the Authorization Server has to support. This endpoint is 450 advertised in the Authorisation Server Configuration Data as defined 451 by the UMA specification [UMA]. The requesting party claims endpoint 452 is used by the Authorization Server to interact with the requesting 453 party and not with the client application. The authorization server 454 can first verify the identity of the requesting party or it may 455 engage the requesting party in claims gathering flow. For example, 456 the AS may decide based on the authentication process that it has 457 enough information to evaluate a policy or it may require the 458 requesting party to provide further claims, e.g. using an existing 459 identity federation protocol. For example, after landing at this 460 endpoint the requesting party may be further redirected to the source 461 of claims (e.g. SAML IDP or the OpenID Connect Identity Provider). 463 2.5.1. Requesting Party Claims Endpoint 465 In redirect UMA profile, the configuration data has to be extended 466 with the following property. 468 requesting_party_claims_endpoint 469 REQUIRED. The endpoint URI at which the authorization server 470 interacts with the end-user requesting party to obtain the 471 necessary user-claims that will be used during policy 472 evaluation process. 474 Example of authorization server configuration extended with 475 requesting party claims endpoint: 477 { 478 "version":"1.0", 479 "issuer":"https://example.com", 480 "pat_profiles_supported":["bearer"], 481 "aat_profiles_supported":["bearer"], 482 "rpt_profiles_supported":["bearer"], 483 "pat_grant_types_supported":["authorization_code"], 484 "aat_grant_types_supported":["authorization_code"], 485 "claim_profiles_supported":["openid"], 486 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri", 487 "token_endpoint":"https://as.example.com/token_uri", 488 "user_endpoint":"https://as.example.com/user_uri", 489 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri", 490 "introspection_endpoint":"https://as.example.com/rs/status_uri", 491 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri", 492 "rpt_endpoint":"https://as.example.com/client/rpt_uri", 493 "authorization_request_endpoint":"https://as.example.com/client/authz_uri", 494 "requesting_party_claims_endpoint":"https://as.example.com/rp/claims_uri" 495 } 497 2.5.2. Message Flow 499 Message flow: 501 1. Client asks for new authorization data to be added to an existing 502 RPT 504 POST /rpt_authorization HTTP/1.1 505 Host: www.nuveam.com 506 Authorization: Bearer jwfLG53^sad$#f 507 ... 509 { 510 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv", 511 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de" 512 } 514 2. AS tells the client to redirect the user to the Requesting Party 515 Claims Endpoint and includes the scope parameter in the value of the 516 response 518 HTTP/1.1 403 Forbidden 519 Content-Type: application/json 521 { 522 "need_claims":[ 523 { 524 "type":"redirect_required", 525 "name":"Redirect Required", 526 "value":"699faf5bf2869838e992d57756bc6f" 527 } 528 ] 529 } 531 3. Client redirects the user to the Requesting Party Claims Endpoint 532 and includes the scope parameter in the request 534 HTTP/1.1 302 Found 535 Location: https://www.nuveam.com/uma/rp_claims?scope=699faf5bf2869838e992 536 d57756bc6f&redirect_uri=http%3A%2F%2Fwww.umaapp.com%%2Fredirect&client_id= 537 ca4453936fa5fda2110b9e589d61ab37&state=32455ddsafas 539 After the user is redirected to the AS, the claims for the user are 540 gathered according to one of the defined protocols, such as SAML, 541 OpenID Connect or any other protocol implemented by an UMA-compliant 542 Authorisation Server. Furthermore, the AS is free to obtain the 543 information from a local or remote LDAP, Active Directory or any 544 other user datastore (e.g. SQL or NoSQL-based datastore). 546 4. AS informs the client that new authorization can be added and the 547 client is free to request a new RPT 549 HTTP/1.1 302 Found 550 Location: https://www.umaapp.com/redirect?access=granted&state=32455ddsafas 552 5. AS informs the client that authorization data cannot be added 554 HTTP/1.1 302 Found 555 Location: https://www.umaapp.com/redirect?access=denied&state=32455ddsafas 557 2.5.3. Examples 559 In this section, we discuss three examples: 561 1. User is redirected to an OIDC Provider; 563 2. User is redirected to a SAML IDP; 565 3. User's authentication is sufficient for policy evalutation. 567 2.5.3.1. Authorization Server Acts as OpenID Connect Relying Party 569 In this claim profile example, the Authorisation Server acts as an 570 OIDC compliant RP. This flow is used in case the policies for a 571 particular resource set use any of the existing reserved OIDC claims. 572 Importantly, it is the AS that determines if OIDC claims should be 573 used for policy evaluation. This information is not shared with the 574 client application. 576 During this flow the AS acts according to the OpenID Connect protocol 577 and this is outside of the UMA specification. 579 2.5.3.2. Authorization Server Acts as SAML Relying Party 581 In this claim profile example, the Authorisation Server acts as an 582 SAML compliant Service Provider. This flow is used in case the 583 policies for a particular resource set require the use of the SAML 584 protocol. Importantly, it is the AS that determines if the SAML 585 protocol should be used for policy evaluation. This information is 586 not shared with the client application. 588 During this flow the AS acts according to the SAML protocol and this 589 is outside of the UMA specification. 591 2.5.3.3. Authorization Server pulls Claim from local user store 593 In this claim profile example and after successful authentication of 594 the RP, the AS can pull the required user attributes from a local 595 user datastore (e.g. LDAP, Active Directory, and other SQL and 596 NoSQL-datastores). This information can be used for policy 597 evaluation. 599 2.6. IANA Considerations 601 This document makes no request of IANA. 603 2.7. Acknowledgments 605 The current editor of this specification is Domenico Catalano of 606 Oracle. The following people are co-authors: 608 o Maciej Machulak, Cloud Identity Ltd 610 o Thomas Hardjono, MIT 612 o Eve Maler, ForgeRock 614 Additional contributors to this specification include the Kantara UMA 615 Work Group participants, a list of whom can be found at 616 [UMAnitarians]. 618 2.8. Issues 620 Issues are captured at the project's GitHub site ([1]). 622 3. References 624 3.1. Normative References 626 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 627 Requirement Levels", BCP 14, RFC 2119, March 1997. 629 [UMA] Hardjono, T., Ed., "User-Managed Access (UMA) Profile of 630 OAuth 2.0", December 2013, 631 . 634 3.2. Informative References 636 [UMAnitarians] 637 Maler, E., "UMA Participant Roster", July 2014, 638 . 641 3.3. URIs 643 [1] https://github.com/xmlgrrl/UMA-Specifications/issues 645 [2] http://kantarainitiative.org/confluence/display/uma/ 646 UMA+1.0+Core+Protocol 648 Appendix A. Document History 650 NOTE: To be removed by RFC editor before publication as an RFC. 652 See [2] for a list of code-breaking and other major changes made to 653 this specification at various revision points. 655 Authors' Addresses 657 Domenico Catalano (editor) 658 Oracle 660 Email: domenico.catalano@oracle.com 662 Maciej Machulak 663 Cloud Identity 665 Email: maciej.machulak@cloudidentity.co.uk