idnits 2.17.1 draft-zollner-scim-domain-extension-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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (22 October 2021) is 916 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SCIM D. Zollner 3 Internet-Draft Microsoft 4 Intended status: Informational 22 October 2021 5 Expires: 25 April 2022 7 SCIM Verified Domains Extension 8 draft-zollner-scim-domain-extension-00 10 Abstract 12 The System for Cross-domain Identity Management (SCIM) protocol 13 supports creation and management of identity resources such as users 14 between a client and a service provider. In some instances, a SCIM 15 service provider may maintain a list of DNS domains that an 16 organization using that service has registered for their exclusive 17 use with the service. This registration of domains is frequently 18 tied to some form of ownership verification for each domain. This 19 document defines an extension to the SCIM protocol introducing a new 20 'VerifiedDomains' resource type in order to allow a SCIM client to 21 confirm what domains have had ownership verified by the SCIM service 22 provider, as well as some information about whether the User 23 resource's userName and emails attributes require domain verification 24 in order for a value to possess that domain suffix. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 25 April 2022. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 3 62 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 5. Verified Domains . . . . . . . . . . . . . . . . . . . . . . 3 64 5.1. ServiceProviderConfig Extension . . . . . . . . . . . . . 3 65 5.2. VerifiedDomains Schema Extension . . . . . . . . . . . . 4 66 5.3. Sample Requests . . . . . . . . . . . . . . . . . . . . . 4 67 5.3.1. Retrieving all verified domains . . . . . . . . . . . 4 68 5.3.2. Querying verified domains by domainName value . . . . 5 69 6. Schema BNF . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 71 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 74 1. Introduction 76 The System for Cross-domain identity Management (SCIM) protocol 77 RFC7644 (https://datatracker.ietf.org/doc/html/rfc7644) supports 78 creation, modification, and deletion of core identity resources. To 79 allow for efficient interactions between SCIM clients and multi- 80 customer SCIM service providers such as SaaS applications, the client 81 may wish to avoid sending creation or update requests that are 82 already known to contain attribute values that will be rejected by 83 the SCIM service provider. 85 A common source of creation and update failures when interacting with 86 SCIM service providers for SaaS applications is when the SCIM client 87 attempts to create or update the userName(adhering to RFC5321 88 (https://datatracker.ietf.org/doc/html/rfc5321) format) or emails 89 attribute on a user and the SCIM client provides a value with a 90 domain suffix that is not verified in the customer's tenant in the 91 service represented by the SCIM service provider. 93 This document defines a simple extension to the SCIM protocol and 94 core schema that adds support for a "VerifiedDomains" resource type 95 that can be queried to retrieve a list of verified domains in the 96 SCIM service provider's environment so that a SCIM client can utilize 97 this information to apply additional logic and avoid sending requests 98 that will fail. 100 2. Conventions and Definitions 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in 105 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 3. IANA Considerations 110 This document has no IANA actions. 112 4. Definitions 114 Domain: At least a Second Level Domain (SLD) and a Top Level 115 Domain(TLD) registered with public DNS registrars and ICANN. Further 116 expansion to Third Level Domains (aka subdomains) are also permitted. 118 5. Verified Domains 120 A SCIM endpoint supporting the Domains extension MUST implement a 121 /VerifiedDomains resource as outlined in this document. This 122 extension is written with only the HTTP/REST GET method required, as 123 the data provided by the SCIM service provider is intended to be 124 read-only. POST, PUT, PATCH and DELETE requests to the 125 /VerifiedDomains resource MUST result in a HTTP Bad Request (400). 127 5.1. ServiceProviderConfig Extension 129 SCIM endpoints that support the Verified Domains extension MUST 130 advertise this support in the ServiceProviderConfig endpoint as 131 defined: 133 verifiedDomains 134 A complex type that specifies Verified Domains configuration 135 options. REQUIRED. 137 supported 138 A boolean type that specifies if the Verified 139 Domains extension is supported. 141 userNameProperties 142 A complex type that specifies if the expected value for 143 userName follows the RFC5321 format, and if accepted 144 values following RFC5321 require a verified domain suffix. 146 emailsVerifiedDomainRequired 147 A boolean type that specifies if accepted values for 148 emails require a verified domain suffix. 150 5.2. VerifiedDomains Schema Extension 152 Any SCIM service provider that supports the Verified Domains 153 extension MUST implement the VerifiedDomains resource type with the 154 urn:ietf:params:scim:schemas:2.0:VerifiedDomain schema defined in 155 this section: 157 The following singular attributes are defined: 159 domainName 160 A string attribute containing at least the Second Level Domain 161 (SLD) and Top Level Domain (TLD) of a domain verified in the 162 SCIM service provider's system. Subdomains (Third Level 163 Domains and below) are supported as well. REQUIRED. 165 allowSubdomains 166 A boolean attribute set to true for any verified domain 167 resource that should be interpreted by the client to 168 include all subdomains. REQUIRED. 170 verifiedDate 171 A dateTime attribute indicating the date and time at which the 172 domain resource was verified in the SCIM service provider's 173 system. OPTIONAL. 175 5.3. Sample Requests 177 5.3.1. Retrieving all verified domains 179 5.3.1.1. Request 180 GET /VerifiedDomains 181 Host: example.com 182 Accept: application/scim+json 183 Authorization: Bearer 123456abcd 185 5.3.1.2. Response 187 HTTP/1.1 200 OK 188 Content-Type: application/scim+json 190 { 191 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 192 "totalResults":2", 193 "itemsPerPage":100, 194 "startIndex":1, 195 "Resources":[ 196 { 197 "id":"1", 198 "domainName":"contoso.com", 199 "allowSubdomains":true, 200 }, 201 { 202 "id":"2", 203 "domainName":"fabrikam.com", 204 "allowSubdomains":true 205 } 206 ] 207 } 209 5.3.2. Querying verified domains by domainName value 211 5.3.2.1. Request 213 GET /VerifiedDomains?filter=domainName contains "contoso.com" 214 Host: example.com 215 Accept: application/scim+json 216 Authorization: Bearer 123456abcd 218 5.3.2.2. Response 219 HTTP/1.1 200 OK 220 Content-Type: application/scim+json 222 { 223 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 224 "totalResults":1", 225 "itemsPerPage":100, 226 "startIndex":1, 227 "Resources":[ 228 { 229 "id":"1", 230 "domainName":"contoso.com", 231 "allowSubdomains":true 232 } 233 ] 234 } 236 6. Schema BNF 238 [ 239 { 240 "id" : "urn:ietf:params:scim:schemas:2.0:VerifiedDomain", 241 "name" : "Domain", 242 "description" : "DNS Domains", 243 "attributes" : [ 244 { 245 "name" : "domainName" 246 "type" : "string" 247 "multiValued" : false 248 "description" : "Value for a domain name registered and 249 optionally verified in the SCIM service provider. The 250 value should represent a DNS domain name such as 251 'contoso.com' and optionally may contain 252 one or more subdomain levels such as 'scim.contoso.com'. 253 REQUIRED.", 254 "required" : true, 255 "caseExact" : false, 256 "mutability" : "readOnly", 257 "returned" : "default", 258 "uniqueness" : "server" 259 }, 260 { 261 "name" : "allowSubdomains", 262 "type" : "boolean", 263 "multiValued" : false, 264 "description" : "A Boolean value indicating if subdomains 265 below the domain specified in domainName should be 266 treated identically to the value provided in domainName. 268 OPTIONAL", 269 "required" : true, 270 "mutability" : "readOnly", 271 "returned" : "default" 272 }, 273 { 274 "name" : "verifiedDate", 275 "type" : "dateTime", 276 "multiValued" : false, 277 "description" : "An optional dateTime value indicating 278 the time at which the domain specified in domainName 279 was verified. OPTIONAL", 280 "required" : false 281 "mutability" : "readOnly", 282 "returned" : "default" 283 } 284 ] 285 "meta" : { 286 "resourceType" : "Schema", 287 "location" : 288 "/v2/Schemas/urn:ietf:params:scim:schemas:2.0:VerifiedDomain" 289 } 290 } 291 ] 293 7. Normative References 295 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 296 Requirement Levels", BCP 14, RFC 2119, 297 DOI 10.17487/RFC2119, March 1997, 298 . 300 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 301 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 302 May 2017, . 304 Acknowledgments 306 TODO acknowledge. 308 Author's Address 310 Danny Zollner 311 Microsoft 313 Email: danny@zollnerd.com