idnits 2.17.1 draft-wahl-scim-profile-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 date (June 21, 2019) is 1771 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Wahl, Ed. 3 Internet-Draft Microsoft Corporation 4 Intended status: Standards Track June 21, 2019 5 Expires: December 23, 2019 7 SCIM Profile for Provisioning Users Into Relying Party Applications 8 draft-wahl-scim-profile-00 10 Abstract 12 This document specifies a profile of the System for Cross-Domain 13 Identity Management Protocol (SCIM). This profile defines how an 14 identity provider, acting as a SCIM client, can notify a relying 15 party application of changes to user accounts. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on December 23, 2019. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 53 2. General Considerations . . . . . . . . . . . . . . . . . . . 4 54 2.1. Endpoints and Payload . . . . . . . . . . . . . . . . . . 4 55 2.2. Authentication and Authorization . . . . . . . . . . . . 5 56 2.3. SCIM Servers With Multiple Identity Providers and 57 Multiple tenants . . . . . . . . . . . . . . . . . . . . 5 58 2.4. Case Sensitivity in Payloads . . . . . . . . . . . . . . 6 59 2.5. Overlapping and Throttling Requests . . . . . . . . . . . 6 60 2.6. Bulk Operations and Service Provider Configuration . . . 7 61 2.7. Error Results . . . . . . . . . . . . . . . . . . . . . . 7 62 2.8. Non-Requirements . . . . . . . . . . . . . . . . . . . . 7 63 3. Minimum Schema and Schema Discovery . . . . . . . . . . . . . 7 64 3.1. Additional Considerations for the ID Attribute . . . . . 9 65 3.2. Additional Considerations ExternalId Attribute . . . . . 9 66 3.3. Resources for Schema Discovery . . . . . . . . . . . . . 10 67 4. Operations on Users . . . . . . . . . . . . . . . . . . . . . 12 68 4.1. When a User Account is added in the Identity Provider . . 12 69 4.1.1. Optionally locating a User by ExternalId . . . . . . 12 70 4.1.2. Creating a User with POST . . . . . . . . . . . . . . 13 71 4.2. When a User Account's Attributes Change . . . . . . . . . 14 72 4.2.1. Retrieving a User by ID . . . . . . . . . . . . . . . 15 73 4.2.2. Modifying a User with PATCH . . . . . . . . . . . . . 16 74 4.2.3. Indicating User Sign In Blocked . . . . . . . . . . . 18 75 4.3. When the User's Account is to be Removed . . . . . . . . 19 76 4.3.1. Removing a User with DELETE . . . . . . . . . . . . . 19 77 4.4. User Account Retrieval from the Relying Party . . . . . . 20 78 4.4.1. Retrieving Multiple Users in a Single Request . . . . 20 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 80 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 21 83 7.2. Informative References . . . . . . . . . . . . . . . . . 22 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 86 1. Introduction 88 Relying party applications implement single-sign on protocols, such 89 as SAML or OpenID Connect, for user authentication from an identity 90 provider, and often store one or more attributes about each of user 91 identities from those identity providers. The term relying party is 92 defined in OpenID Connect [OPENID.OIDC]. The single sign in flows 93 between an identity provider and a relying party often allow the 94 identity provider to include one or more attributes about a user 95 signing in, such as their name, at the time of the sign in event. 96 However, those attributes might also change, and those changes be 97 relevant, to a relying party application, even when no user is 98 signing in. For example, if an identity provider deletes a user, 99 then the relying party application would never see a subsequent sign 100 in event from that user. 102 The SCIM protocol RFC 7644 [RFC7644] is an application-level, REST 103 protocol for provisioning and managing identity data on the web. 104 SCIM can be leveraged for many use cases, including transfer of 105 attributes about users to a relying party application (see RFC 7643 106 [RFC7643] section 3). This profile describes how SCIM can be used 107 between an identity provider and a relying party application, so the 108 identity provider can notify a relying party application acting as a 109 SCIM server of changes to user accounts, out of band from the normal 110 sign-in flow of those users. . This profile defines the 111 interactions between an identity provider as the initiator, a SCIM 112 client, and a replying party application, as the SCIM server, in the 113 following scenario: 115 o A replying party application has a database of user resources with 116 attributes of those users relevant to that application. It also 117 trusts one or more identity providers to authenticate users on its 118 behalf and provide claims about that user. It also copies the 119 values from some of those claims from those identity providers 120 into its database. 122 o An identity provider has its own distinct database of user 123 resources. That database is the source of its claims which it 124 provides to a relying party application. Normally this is done 125 through a sign-in flow using a protocol such as SAML or Open ID 126 Connect. 128 o The identity provider also wishes to keep the relying party 129 application up to date, even when no user is signing in to that 130 replying party, and so uses SCIM to send changes to the 131 application. 133 Based on this profile, the identity provider acts as a SCIM client 134 and sends the changes via the SCIM protocol to the application acting 135 as a SCIM server. The relying party application represents each user 136 account in its database which is visible to the identity provider, as 137 a SCIM User resource. This enables the relying party application to 138 have a more up-to-date copy of users with its identity provider, than 139 if it was only being updated when a user signs in. 141 For example, if the identity provider deletes a user, this deletion 142 event can be transferred to the relying party application via SCIM, 143 so that the application also cleans up any data associated with that 144 user -- who won't be accessing that application in future. Or, for 145 another example, if the user changes their name in the identity 146 provider, then this change can be sent to the application, so that 147 the user's name is displayed correctly within the application to 148 other users. 150 This profile is not intended to be a comprehensive or bidirectional 151 replication protocol; instead, it provides basic consistency for user 152 resources sent from an identity provider to a relying party, 153 necessary for a user to be able to sign into the relying party. 154 Management of other resource types besides users is outside the scope 155 of this profile. 157 1.1. Requirements Language 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 161 document are to be interpreted as described in RFC 2119 [RFC2119]. 163 2. General Considerations 165 A SCIM client in an identity provider will, either upon specific 166 changes in its database (e.g., when there is a new user), or at 167 intervals, send queries and changes to the relying party 168 application's SCIM server. This section covers the basic 169 requirements for a SCIM client and server implementation. The 170 sections following this one cover the schema requirements, the 171 pattern of operations in this profile, and security considerations. 173 2.1. Endpoints and Payload 175 A SCIM client and server MUST support HTTPS. A SCIM client and SCIM 176 server MUST have previously agreed on the HTTPS URI for the SCIM 177 server's "Users" endpoint, below the Base URI (Base URI is defined in 178 section 1.3 of RFC 7644 [RFC7644]). Additionally, the client and 179 server MAY have also previously agreed on the HTTPS URIs for the SCIM 180 server's "ResourceTypes" and "Schemas" endpoints. These URI MAY 181 contain the string "v2", for example 182 "https://api.example.com/scim/tenant/example.org/v2/Users" might be a 183 base endpoint for Users in a particular application. 185 A SCIM client implementing this profile MUST use JSON-structured 186 request bodies and expect JSON-structured responses using the UTF-8 187 RFC 3629 [RFC3629] encoding, in the Content-Type "application/ 188 scim+json". 190 These are to be sent via HTTPS using TLS, RFC 8446 [RFC8446]. 192 2.2. Authentication and Authorization 194 This profile is intended for service-to-service communication: a SCIM 195 client is not acting under the context of an individual person, it is 196 operating on behalf of the identity provider. 198 A SCIM client and a SCIM server SHOULD support one or more 199 authentication mechanisms to authenticate a SCIM client to a SCIM 200 server. One mechanism SHOULD be bearer tokens. 202 If a SCIM client supports bearer tokens, then the client SHOULD 203 include the token in the Authorization header of each request, as 204 described in section 2.1 of RFC 6750 [RFC6750]. This profile does 205 not cover establishing common authentication keys, which is assumed 206 to occur out of band. 208 A SCIM server does not need to support operations by un-authenticated 209 clients. A SCIM server MUST only permit a client to query, create, 210 update and delete one or more User resources, after the token is 211 validated. 213 2.3. SCIM Servers With Multiple Identity Providers and Multiple tenants 215 If a SCIM server supports multiple tenants, then the operations 216 defined in this profile are relative to a single tenant. If a SCIM 217 server is part of an application which is affiliated with multiple 218 independent identity providers, and the operator of that SCIM server 219 permits each tenant to choose its identity providers, then that SCIM 220 server MUST ensure that the operations performed by one SCIM client 221 on behalf of one tenant do not affect another tenant. 223 A SCIM server SHOULD give each SCIM client a distinct identity and 224 authorization information. 226 A SCIM server SHOULD ensure that within a single tenant, or within 227 the application if the application is not multi-tenanted, each SCIM 228 client's updates do not affect those of other SCIM clients. 230 There are several ways for a SCIM server to achieve that. For 231 example, a SCIM server might have each tenant or each SCIM client use 232 a unique User endpoint. 234 For example, if the application had tenants example.com and 235 example.org, and identity providers A and B, and tenant example.com 236 used identity providers A and B but tenant example.org only allowed 237 identity provider B, then identity provider A would be instructed to 238 use endpoints /example.com/Users and /example.org/Users, and identity 239 provider B would be instructed to use endpoint /example.org/Users. 241 Or, in another approach, a SCIM server MAY record which SCIM client 242 identity created each user resource, and only permit user resources 243 to be queried, updated or deleted by the same client. 245 2.4. Case Sensitivity in Payloads 247 As defined in RFC 7644 [RFC7644], attribute names and attribute 248 operators used in filters are case insensitive. 250 An implementation of this protocol SHOULD treat all other ABNF US- 251 ASCII strings as case insensitive. For example, in the following 252 PATCH body 254 { 255 "schemas": 256 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 257 "Operations":[{ 258 "op":"remove", 259 "path":"emails[type eq \"work\"]" 260 }] 261 } 263 The case of these strings "schemas", "Operations", "op", "remove" and 264 "path" are not significant. 266 Most attribute values are case insensitive when matching, however the 267 values of the "id" attribute and the "externalID" attribute are case 268 sensitive. 270 2.5. Overlapping and Throttling Requests 272 A SCIM client MAY send multiple requests to a SCIM server, and need 273 not wait for one a response prior to sending another requests, with 274 one exception. A SCIM client SHOULD NOT send another PATCH request 275 for a particular User resource, if there was a PATCH request sent for 276 that same resource in the last 60 seconds for which the client did 277 not receive a response. A SCIM server need not process multiple 278 operations in the order they were sent by the client. 280 A SCIM server MAY throttle clients who send too many simultaneous 281 requests or too many requests in a short time interval, by returning 282 status code 429, as defined in RFC 6585 [RFC6585], to subsequent 283 requests. A SCIM client which receives status code 429 SHOULD wait 284 before retrying that request. 286 2.6. Bulk Operations and Service Provider Configuration 288 A SCIM server MAY support bulk operations, and if it does SHOULD 289 support querying the service provider configuration. A SCIM server 290 is not required to support bulk operations or the service provider 291 configuration, and a server which does not support them SHOULD return 292 either an error or an empty result for a query for the 293 ServiceProviderConfig. 295 A SCIM client MAY query a SCIM server to determine if it supports 296 bulk operations, by sending a GET for ServiceProviderConfig, as 297 described in section 4 RFC 7644 [RFC7644]. If a SCIM server returns 298 an error to this query, then a SCIM client SHOULD assume that SCIM 299 server does not support bulk operations, and send subsequent requests 300 not using bulk operations. 302 2.7. Error Results 304 If a SCIM server implementing this profile encounters an error when 305 processing a request from a client, it SHOULD transmit the error in 306 the HTTP status code of the response, as described in section 3.2 of 307 RFC 7644 [RFC7644] and RFC 6585 [RFC6585]. 309 2.8. Non-Requirements 311 A SCIM server implementing this profile MAY implement these or other 312 features, but a SCIM client SHOULD NOT assume they are supported 313 unless it has determined otherwise. 315 o HTTP cookies for authentication, or authentication not related to 316 OAuth (from RFC 7644 [RFC7644] section 2) 318 o sorting, paging or queries via POST (from RFC 7644 [RFC7644] 319 sections 3.4.2 and 3.4.3) 321 o updates via PUT (from RFC 7644 [RFC7644] sections 3.5.1) 323 o the Me URI fragment (from RFC 7644 [RFC7644] sections 3.11) 325 o eTags (from RFC 7644 [RFC7644] sections 3.14) 327 o anonymous requests (from RFC 7644 [RFC7644] sections 7.6) 329 3. Minimum Schema and Schema Discovery 331 SCIM defines a user schema in RFC 7643 [RFC7643]. A SCIM server 332 implementing this profile need not implement the full set of 333 attributes of that schema, since those attributes are not necessarily 334 relevant to the application. 336 A SCIM server that supports a client creating users MUST recognize 337 the User resource schema, as described in section 4.1 of RFC 7643 338 [RFC7643], but does not need to support all of the attributes. 340 A SCIM server SHOULD recognize the Enterprise User schema extension 341 as described in section 4.3 of RFC 7643 [RFC7643]. 343 From these schemas, 345 o A SCIM server MUST provide the attribute "ID" for all users. 347 o A SCIM server that supports a client creating users SHOULD support 348 the attribute "userName" being supplied by a SCIM client when 349 creating a user, or when the client is modifying a user. 351 o A SCIM server SHOULD support the attribute "active", as it allows 352 a SCIM client to temporarily de-activate a user. 354 o A SCIM server SHOULD support the attribute "displayName", with 355 values of at least 128 characters in length, being included when a 356 user resource is created and subsequently changed. 358 A SCIM server SHOULD NOT require any additional attributes besides 359 userName to be supplied by a SCIM client when creating a user. 361 If email addresses are relevant to a SCIM server application, 363 o That SCIM server SHOULD support the multi-valued attribute 364 "emails", for a client providing one value. 366 o That SCIM server MAY support a client providing more than one 367 value. As there is no way to indicate this at present, a SCIM 368 client SHOULD NOT require a SCIM server to support multiple 369 values. 371 o That SCIM server SHOULD support each value of "emails" having sub- 372 attributes "primary", "type" and "value", and SHOULD support sub- 373 attribute "type" having a value of "work". 375 For other attributes, if they are relevant to the application, and 376 can be supplied by the identity provider, then that application's 377 SCIM server MAY support storing them. In particular, 379 o A SCIM server MAY support the attribute "externalId", with values 380 of at least 64 characters in length. 382 o A SCIM server MAY support the complex multi-valued attributes 383 "addresses" and "phoneNumbers", for a client providing one value 384 of each, and MAY support a client providing more than one value of 385 each attribute. 387 o A SCIM server MAY support the complex attribute "manager". 389 o A SCIM server MAY support the complex attribute "name", and if it 390 does, SHOULD support the sub-attributes "formatted", "familyName", 391 "givenName", "middleName", "honorificPrefix" and 392 "honorificSuffix". 394 o A SCIM server MAY support the attributes "title" and 395 "preferredLanguage". 397 o A SCIM server MAY support the attribute "department" in the 398 enterprise 2.0 user schema. 400 3.1. Additional Considerations for the ID Attribute 402 A SCIM server SHOULD construct a value for the "ID" attribute which 403 is unique across all users which that SCIM server has in its 404 database, and is likely to have in the future. In addition, the 405 value SHOULD NOT include any characters which would require escaping 406 if they were included in a HTTPS URI, and be limited to 64 US-ASCII 407 characters in length. For example, a universally unique identifier 408 as described in RFC 4122 [RFC4122] would be a better choice for an id 409 value than an email address or person's display name. 411 A SCIM server SHOULD NOT change the value of the "ID" attribute once 412 it has been assigned to a User. Each subsequent GET of that user 413 SHOULD return the same value. 415 A SCIM client MUST NOT assign any semantics to the value of the "ID" 416 attribute which is receives from a SCIM server, other than it is 417 unique in that server. 419 3.2. Additional Considerations ExternalId Attribute 421 A SCIM client MAY construct a value for the "externalId" attribute 422 for its users. If it does, the values of that attribute SHOULD be 423 unique across all users which the identity provider has in its 424 database, and is likely to have in the future. In addition, the 425 value SHOULD NOT include any characters which would require escaping 426 if they were to be included in a HTTPS URI, and be limited to 64 US- 427 ASCII characters in length. For example, a universally unique 428 identifier as described in RFC 4122 [RFC4122] would be a better 429 choice for an externalId value than an email address or person's 430 display name. 432 A SCIM server need not support the "externalId" attribute. If it 433 does, it SHOULD NOT assign any semantics to the value of the 434 "externalId" attributes. 436 3.3. Resources for Schema Discovery 438 A SCIM server SHOULD support schema discovery through the "Schemas" 439 and "ResourceTypes" endpoint URIs, as described in section 4 RFC 7644 440 [RFC7644], that specifies the attributes of the "User" resource type 441 which it supports. 443 A SCIM server that supports more than the minimum attributes of this 444 profile SHOULD publish through schema discovery any additional 445 attributes which it permits an identity provider to send. 447 A SCIM client MAY query a SCIM server to determine its schema, by 448 querying either of those collections with GET requests. If that SCIM 449 server returns an error to either query, then the SCIM client SHOULD 450 assume that SCIM server only supports the attributes "userName", 451 "ID", "active", "displayName" and "emails". 453 A SCIM server MUST ignore any additional resource types or attributes 454 in the returned schema which it does not understand. 456 For example, if "https://example.com/Schemas" was the endpoint for 457 "Schemas", and an authorized SCIM client sent 459 GET /Schemas HTTP/1.1 460 Authorization: Bearer h480djs93hd8 462 then a SCIM server might return 464 HTTP/1.1 200 OK 465 Content-Type: application/scim+json 466 Content-Length: ... 468 { 469 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 470 "totalResults": 1, 471 "Resources":[ 472 { 473 "id":"urn:ietf:params:scim:schemas:core:2.0:User", 474 "name":"User", 475 "description":"User Account", 476 "attributes":[ 477 { 478 "name":"userName", 479 "type":"string", 480 "multiValued":false, 481 "required":true, 482 "caseExact":false, 483 "mutability":"readWrite", 484 "returned":"default", 485 "uniqueness":"server" 486 }, 488 { 489 "name":"displayName", 490 "type":"string", 491 "multiValued":false, 492 "required":false, 493 "caseExact":false, 494 "mutability":"readWrite", 495 "returned":"default", 496 "uniqueness":"none" 497 }, 499 { 500 "name":"active", 501 "type":"boolean", 502 "multiValued":false, 503 "required":false, 504 "mutability":"readWrite", 505 "returned":"default" 506 }, 508 ... 510 ] 511 }, 512 "meta":{ 513 "resourceType":"Schema" 514 } 515 } 516 ] 517 } 519 4. Operations on Users 521 4.1. When a User Account is added in the Identity Provider 523 When a user account is added in the identity provider, then 525 o The identity provider's SCIM client MAY query a SCIM server to 526 locate the user by externalId. This step is OPTIONAL and a SCIM 527 client MAY omit it. A SCIM server is not required to support 528 querying by externalId, and if it does not, SHOULD return an error 529 for a filter on the "Users" endpoint with the externalId 530 attribute. 532 o If the user does already not exist in that SCIM server, or the 533 client did not query for it, then the identity provider's SCIM 534 client MAY send a POST to create the user in that SCIM server. 536 4.1.1. Optionally locating a User by ExternalId 538 If a SCIM server supports the "externalId" attribute, a SCIM client 539 MAY query a user by filtering for a value of the "externalId" 540 attribute. A SCIM server that implements this profile and supports 541 the "externalId" attribute SHOULD support filtering, as described in 542 section 3.4.2.22 of RFC 7644 [RFC7644]. That SCIM server MAY support 543 filtering by an equality match of the "externalId" attribute. 545 GET /Users?filter=externalId%20eq%201-2 HTTP/1.1 546 Authorization: Bearer h480djs93hd8 548 A SCIM client MAY query a SCIM server for a value of "externalId". 549 If the SCIM server supports this query and the attribute value is not 550 present on any current User in that SCIM server, the query response 551 is a successful response with 0 result resources. 553 HTTP/1.1 200 OK 554 Content-Type: application/scim+json 555 Content-Length: ... 557 { 558 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 559 "totalResults": 0, 560 "Resources":[] 561 } 563 Otherwise, if there is a matching entry, then the query response is a 564 successful response with one result resource. 566 4.1.2. Creating a User with POST 568 To create a user, a SCIM client sends a POST request to the SCIM 569 server's "Users" endpoint. The order of fields in the request for 570 the attributes and metadata is not significant. 572 For example, if a SCIM client has determined a SCIM server supports 573 the attributes "email", "name" and "department", the SCIM client 574 would send 576 POST /Users HTTP/1.1 577 Host: example.com 578 Accept: application/scim+json 579 Content-Type: application/scim+json 580 Authorization: Bearer h480djs93hd8 581 Content-Length: ... 583 { 584 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User", 585 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"], 586 "active":true, 587 "displayName":"Babs Jensen", 588 "emails":[{"primary":true","type":"work", 589 "value":"babs@example.com"}], 590 "meta":{"resourceType":"User"}, 591 "userName":"bjensen@example.com", 592 "name":{ 593 "formatted":"Ms. Barbara J Jensen III", 594 "familyName":"Jensen", 595 "givenName":"Barbara" 596 }, 597 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":{ 598 "department":"Retail" 599 } 600 } 602 In addition to the attributes, a SCIM server MAY supply, and a SCIM 603 server SHOULD permit, the POST payload to contain the "schemas" and 604 "meta" fields. A SCIM client MUST NOT send the "id" attribute in the 605 POST request. 607 If the creation was successful, then that server SHOULD return HTTP 608 status code 201 with a representation of the User resource. The 609 returned resource SHOULD have an "id" attribute. The returned 610 resource MAY contain some of the attributes supplied by that SCIM 611 client, but some attributes might not be returned if they were not 612 stored by that server, or if that server chooses not to return them. 613 The returned resource MAY have additional attributes generated by 614 that server. 616 HTTP/1.1 201 Created 617 Content-Type: application/scim+json 618 Content-Length: ... 620 { 621 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 622 "id":"48af03ac28ad4fb88478" 623 } 625 If a user resource earlier existed but had been deleted, then a POST 626 request for a new User resource with the same userName, externalId or 627 other attributes as the previously deleted resource SHOULD NOT fail 628 due to attribute conflict. If it does fail due to an attribute 629 conflict, that server SHOULD return status code 409. 631 4.2. When a User Account's Attributes Change 633 When inside of an identity provider, one or more of a user's 634 attributes, such as display name, changes to a new value, then 636 The identity provider's SCIM client MAY query a SCIM server with a 637 GET to retrieve the user's current attributes, as known to that 638 server. This step is OPTIONAL and a SCIM client MAY omit it. 640 The identity provider's SCIM client MAY send a PATCH to update the 641 user in a SCIM server. 643 If a SCIM client chooses to perform the query prior to the PATCH, 644 then the sequence of operations would resemble 646 +--------+ +--------+ 647 | | | | 648 | |--(1) GET Request with id of user->| | 649 | | | | 650 | |<-(2) GET Response of that user----| | 651 | | | | 652 | IDP | | RP | 653 | | | | 654 | |--(3) PATCH Request for that user->| | 655 | | | | 656 | |<-(4) PATCH Response---------------| | 657 | | | | 658 +--------+ +--------+ 660 4.2.1. Retrieving a User by ID 662 A SCIM client MAY query a SCIM server for a user created earlier, by 663 constructing an URI from the "Users" endpoint and the value of the 664 "id" attribute returned by that server in an earlier POST response. 665 For example, 667 GET /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 668 Authorization: Bearer h480djs93hd8 670 If that user still exists in that SCIM server, that SCIM server would 671 return it. 673 HTTP/1.1 200 OK 674 Content-Type: application/scim+json 676 { 677 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 678 "id":"5d48a0a8e9f04aa38008", 679 "externalId":"58342554-38d6-4ec8-948c-50044d0a33fd", 680 "meta": { 681 "resourceType":"User" 682 }, 683 "userName":"bjensen@example.com", 684 "name": { 685 "formatted":"givenName familyName", 686 "familyName":"familyName", 687 "givenName":"givenName", 688 }, 689 "active": true, 690 "emails":[{ 691 "value":"bjensen@example.com", 692 "type":"work", 693 "primary": true 694 }] 695 } 697 A SCIM client MAY use the returned user resource to determine if a 698 change it intends to send has already been made to a user. 700 If the user no longer exists, a SCIM server SHOULD return a 404 701 error. 703 If a SCIM client expected that the user was present, but received a 704 404 error, then that SCIM client MAY attempt to re-create a 705 replacement user with a POST operation, it cannot PATCH a deleted 706 user. Note that the new user SHOULD have a different "ID" attribute 707 value. 709 4.2.2. Modifying a User with PATCH 711 A SCIM client sends a PATCH operation to change one or more 712 attributes of the user. A SCIM server implementing this profile 713 SHOULD support PATCH, as described in section 3.5 of RFC 7644 714 [RFC7644]. 716 o A SCIM server SHOULD support the "replace" operation for the 717 "userName" attribute. 719 o A SCIM server SHOULD support the "add", "remove" and "replace" 720 operations for the attributes "active" and "displayName". A SCIM 721 client MUST only send the "add" operation for one of these 722 attributes if it has not previously set or retrieved that value 723 for that attribute, and MUST only send the "remove" operation for 724 one of these attributes if it has previously set or retrieved a 725 value for that attribute. 727 o If a SCIM server supports storing email addresses, then that SCIM 728 server SHOULD support the "add", "remove" and "replace" operations 729 for attribute "emails", and SHOULD support "replace" changing just 730 the value sub-attribute. 732 o A SCIM server MAY support operations on other attributes within 733 the PATCH. 735 o A SCIM client MUST NOT assume the response contains any or all of 736 the user attributes, as that SCIM server MAY choose to not return 737 the entire user resource and all its attributes in the response. 739 PATCH /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 740 Host: example.com 741 Accept: application/scim+json 742 Content-Type: application/scim+json 743 Authorization: Bearer h480djs93hd8 745 { 746 "schemas": 747 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 748 "Operations":[{ 749 "op":"replace", 750 "value":{ 751 "emails":[ 752 { 753 "value":"bjensen@example.com", 754 "type":"work", 755 "primary":true 756 } 757 ] 758 }] 759 } 761 A SCIM client MAY include multiple operations for different 762 attributes in a single PATCH. 764 PATCH /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 765 Host: example.com 766 Accept: application/scim+json 767 Content-Type: application/scim+json 768 Authorization: Bearer h480djs93hd8 770 { 771 "schemas": 772 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 773 "Operations":[ 774 { 775 "op":"Replace", 776 "path":"emails[type eq \"work\"].value", 777 "value":"bjensen@example.com" 778 }, 779 { 780 "op":"Replace", 781 "path":"name.familyName", 782 "value":"Jensen" 783 } 784 ] 785 } 787 4.2.3. Indicating User Sign In Blocked 789 An identity provider MAY wish to indicate that a user is unable to 790 sign in, and so is temporarily unable to access the application. A 791 SCIM client would send a change of the "active" attribute to the 792 value false to indicate the user will be unable to sign in. Later, 793 if the user is made able to sign in, that SCIM client would send a 794 new request to change the value of the "active" attribute of true. 796 PATCH /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 797 Host: example.com 798 Accept: application/scim+json 799 Content-Type: application/scim+json 800 Authorization: Bearer h480djs93hd8 802 { 803 "schemas": 804 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 805 "Operations":[{ 806 "op":"replace", 807 "value":{ 808 "active":false 809 }] 810 } 812 4.3. When the User's Account is to be Removed 814 The identity provider MAY wish to indicate to the application that a 815 user will never be signing in again. As there is no undo, this 816 SHOULD only be done when the user account has been purged, e.g., if 817 the user account has been soft-deleted in the identity provider but 818 might be restored, the "active" attribute SHOULD be used instead of a 819 delete to indicate the user's undoable change of status. 821 4.3.1. Removing a User with DELETE 823 A SCIM client MAY delete a user it had created earlier, using the 824 DELETE operation. 826 DELETE /Users/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1 827 Host: example.com 828 Authorization: Bearer h480djs93hd8 830 If the delete was successful, a SCIM server SHOULD return status code 831 200. 833 A SCIM server MAY return an error 404 if the user was already 834 deleted, and SHOULD return a different error if the delete could not 835 be performed. 837 4.4. User Account Retrieval from the Relying Party 839 At intervals, a SCIM client MAY wish to query a SCIM server to ensure 840 that SCIM server's copy of the user resources matches those expected 841 by that SCIM client. For example, the identity provider might wish 842 to reconcile with the application so that it can determine if one or 843 more changes are needed. This can be done by either querying for 844 each individual user with a GET operation, or retrieving multiple 845 users in a single request. 847 Querying for an individual user was shown in the earlier section, 848 Retrieving a User by ID. 850 4.4.1. Retrieving Multiple Users in a Single Request 852 A SCIM client MAY request to retrieve all users visible to it, by 853 sending a GET request for the "Users" endpoint. 855 GET /Users HTTP/1.1 856 Authorization: Bearer h480djs93hd8 858 That SCIM server SHOULD either return the result, return the result 859 in multiple pages, or reject the request if the response would be too 860 large to return. 862 HTTP/1.1 200 OK 863 Content-Type: application/scim+json 864 Content-Length: ... 866 { 867 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 868 "totalResults": 1, 869 "Resources":[{ 870 ... 871 }] 872 } 874 5. Security Considerations 876 The security requirements of sections 7.1, 7.2, 7.3, 7.4, 7.5, 7.7 877 and 7.8 of RFC 7644 [RFC7644] apply to implementations of this 878 profile. A SCIM server following this protocol SHOULD NOT support 879 anonymous requests, so section 7.6 of that RFC would not be 880 applicable. 882 If a SCIM server in an application is affiliated with multiple 883 independent identity providers, then multiple SCIM clients could be 884 making changes and querying the same SCIM server. The application 885 security model will take into consideration whether user resources 886 created from one identity provider are intended be visible to a 887 client acting on behalf of a different identity provider. 889 6. IANA Considerations 891 There are no IANA considerations in this document. 893 7. References 895 7.1. Normative References 897 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 898 Requirement Levels", BCP 14, RFC 2119, 899 DOI 10.17487/RFC2119, March 1997, 900 . 902 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 903 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 904 2003, . 906 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 907 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 908 . 910 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 911 Framework: Bearer Token Usage", RFC 6750, 912 DOI 10.17487/RFC6750, October 2012, 913 . 915 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 916 Mortimore, "System for Cross-domain Identity Management: 917 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 918 2015, . 920 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 921 and C. Mortimore, "System for Cross-domain Identity 922 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 923 September 2015, . 925 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 926 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 927 . 929 7.2. Informative References 931 [OPENID.OIDC] 932 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 933 C. Mortimore, "OpenID Connect Core 1.0 incorporating 934 errata set 1", November 2014, 935 . 937 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 938 Unique IDentifier (UUID) URN Namespace", RFC 4122, 939 DOI 10.17487/RFC4122, July 2005, 940 . 942 Author's Address 944 Mark Wahl (editor) 945 Microsoft Corporation 946 1 Microsoft Way 947 Redmond, WA 98052 948 US 950 Email: mwahl@microsoft.com