SCIM Extension for Tenant-Aware Identity Provisioning

1.1. Relationship to Other SCIM Work

This extension is intended to compose with, not duplicate, other SCIM resource and extension work:¶

Roles and entitlements:

The discovery of which roles and entitlements a service provider accepts, including values that vary per customer or tenant, is addressed by [I-D.ietf-scim-roles-entitlements]. Portable, scoped role bindings of the form "subject has role R in scope S" (where S MAY be a tenant) are addressed by the RoleAssignment work [I-D.poreddy-scim-role-assignment], whose scope type "tenant" references a Tenant defined by this document. Accordingly, this document does NOT carry tenant-local roles or entitlements on the membership object; see Section 5. Implementations that require scoped role bindings SHOULD use RoleAssignment with a scope that references a Tenant "id" defined here.¶

Use cases:

Multi-tenant deployment topologies and reconciliation flows are described in [I-D.ietf-scim-use-cases-reloaded]. This document provides the schema and protocol surface those topologies require.¶

Core resources:

This document extends the "User" and "Group" resources of [RFC7643] and adds the "Tenant" resource type. It does not modify the core schema or protocol and is additive in the sense of [RFC7643], Section 4.¶

4.1. Endpoints

A service provider implementing this extension SHALL support the following endpoints with the semantics defined in [RFC7644]:¶

GET    /Tenants            (list/search)
GET    /Tenants/{id}       (read)
POST   /Tenants            (create)
PUT    /Tenants/{id}       (replace)
PATCH  /Tenants/{id}       (modify)
DELETE /Tenants/{id}       (delete; see lifecycle rules)

DELETE is subject to the cascade rules of Section 9.¶

4.2. Attributes

The Tenant resource has the following attributes. Each entry below follows [RFC7643], Section 2.2. Unless otherwise noted, the type is "string", "multiValued" is false, "required" is false, "caseExact" is false, "mutability" is "readWrite", "returned" is "default", and "uniqueness" is "none".¶

id:

Type string. Required true. Mutability readOnly. Returned always. Uniqueness server. A unique, stable, non-reassignable identifier assigned by the service provider. Compared octet-by-octet; see Section 8.3.¶

externalId:

Type string. Uniqueness server. A client-supplied identifier; see [RFC7643], Section 3.1.¶

displayName:

Type string. Required true. A human-readable name for the Tenant.¶

status:

Type string. Required true. Canonical values "active", "suspended", "archived", "pending". Transitions are governed by Section 9.¶

type:

Type string. Canonical values "customer", "partner", "internal", "workspace", "organization".¶

domains:

Complex multi-valued. Each entry has sub-attributes "value" (string, required, the FQDN), "primary" (boolean; at most one entry MAY be true), and "verified" (boolean, readOnly; true if and only if the service provider has independently verified domain ownership). FQDN comparison follows Section 8.3.¶

homeRegion:

Type string. Optional. Identifier of the Tenant's home region. Present only when the region profile (see Section 13) is supported.¶

regions:

Complex multi-valued. Optional. Present only when the region profile is supported. Sub-attributes are defined in Section 13.¶

meta:

Complex. Required. ReadOnly. As defined in [RFC7643], Section 3.1. "meta.resourceType" SHALL be the string "Tenant". "meta.version" SHALL be supported to enable the concurrency control of Section 10.¶

4.3. Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Tenant"
  ],
  "id": "tenant-acme",
  "externalId": "customer-1001",
  "displayName": "Acme Corporation",
  "status": "active",
  "type": "customer",
  "domains": [
    {"value": "acme.example.com", "primary": true, "verified": true}
  ],
  "meta": {
    "resourceType": "Tenant",
    "version": "W/\"a330bc54f0671c9\"",
    "location": "https://sp.example.com/scim/v2/Tenants/tenant-acme"
  }
}

5.1. Attributes

memberships:

Complex multi-valued. ReadWrite. Each entry represents the user's relationship to one Tenant. Sub-attributes:¶

• "value" (string, required, readWrite): the referenced Tenant's "id".¶
• "$ref" (reference, required, readOnly, referenceTypes=["Tenant"]): the URI "/Tenants/{id}".¶
• "status" (string, required, readWrite): canonical values "active", "suspended", "invited", "pending", "deactivated". Transitions are governed by Section 9.¶
• "primary" (boolean, readWrite): at most one entry MAY be true.¶

This object intentionally does NOT carry tenant-local "roles" or "entitlements". Scoped role and entitlement bindings are expressed using RoleAssignment [I-D.poreddy-scim-role-assignment] with a scope that references the Tenant "id", and the set of available roles and entitlements is discovered using [I-D.ietf-scim-roles-entitlements]. This avoids re-encoding scope into role strings and keeps a single interoperable mechanism for scoped authorization data. See Section 1.1.¶

5.2. Effective State

A user's effective state in Tenant "t" is determined by composing the core user state, the tenant state, and the membership state, in this order:¶

1. If core "User.active" is false, the effective state is "inactive" in every Tenant.¶
2. Otherwise, if "Tenant(t).status" is "suspended" or "archived", the effective state is "inactive" in "t" regardless of membership status.¶
3. Otherwise, the effective state is derived from "membership.status" for the matching membership: "active" is active; "suspended" and "deactivated" are inactive; "invited" and "pending" are inactive until activation.¶
4. If no membership exists for "t", the user has no presence in "t", and SCIM operations targeting "t" for that user SHALL be rejected with HTTP 404.¶

5.3. Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:tenantMembership:2.0:User"
  ],
  "id": "user-123",
  "userName": "alex@example.com",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:tenantMembership:2.0:User": {
    "memberships": [
      {
        "value": "tenant-acme",
        "$ref": "/Tenants/tenant-acme",
        "status": "active",
        "primary": true
      },
      {
        "value": "tenant-contoso",
        "$ref": "/Tenants/tenant-contoso",
        "status": "suspended",
        "primary": false
      }
    ]
  }
}

6.1. Attributes

value:

Type string. Required when "scope = tenant". Mutability readWrite. The owning Tenant's "id".¶

$ref:

Type reference. ReferenceTypes ["Tenant"]. Required when "scope = tenant". Mutability readOnly. The URI "/Tenants/{id}".¶

scope:

Type string. Required. Mutability readWrite. Canonical values "tenant", "global".¶

6.2. Constraints

Tenant-scoped groups SHALL belong to exactly one Tenant. A client SHALL NOT create a Group with "scope = tenant" and no "value". Cross-tenant Group membership is not modeled; cross-tenant collaboration is expressed at the User level via multiple memberships.¶

7.1. Attributes

multiTenancy:

Complex. Required. Mutability readOnly. Sub-attributes:¶

• "supported" (boolean): true if and only if the service provider supports any portion of this extension.¶
• "tenantResourceSupported" (boolean): true if and only if "/Tenants" is available.¶
• "tenantMembershipSupported" (boolean): true if and only if the user and group membership extensions are supported.¶
• "tenantAwareFilteringSupported" (boolean): true if and only if filters referencing membership attributes are supported.¶
• "tenantScopedUniquenessSupported" (boolean): true if and only if tenant-scoped uniqueness is configurable for natural-key attributes.¶
• "regionAwareTenancySupported" (boolean): true if and only if the region profile is implemented.¶
• "tenantSelectionMethods" (string, multi-valued): the indicator methods the service provider accepts. Values are drawn from "tokenClaim", "path", "header", "subdomain", "body".¶
• "tenantSelectionPrecedence" (string, multi-valued): an ordered list of methods denoting their precedence. The default order is ["tokenClaim", "path", "header", "subdomain", "body"].¶
• "authenticatedSelectionMethods" (string, multi-valued): the subset of "tenantSelectionMethods" the service provider treats as authenticated (see Section 2). The default value is ["tokenClaim"].¶
• "tenantClaim" (string): the JWT claim name carrying tenant context. Default "tenant_id".¶
• "tenantHeader" (string): the HTTP header field name carrying tenant context. Default "SCIM-Tenant-Id".¶
• "tenantScopedUniqueness" (complex): a record of which natural keys are scoped to Tenant rather than server. Sub-attributes are attribute names ("userName", "externalId", "groupDisplayName") mapped to the string "tenant" or "server".¶

7.2. Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig",
    "urn:ietf:params:scim:schemas:extension:multiTenancy:2.0:ServiceProviderConfig"
  ],
  "urn:ietf:params:scim:schemas:extension:multiTenancy:2.0:ServiceProviderConfig": {
    "multiTenancy": {
      "supported": true,
      "tenantResourceSupported": true,
      "tenantMembershipSupported": true,
      "tenantAwareFilteringSupported": true,
      "tenantScopedUniquenessSupported": true,
      "regionAwareTenancySupported": true,
      "tenantSelectionMethods": [
        "tokenClaim","path","header","subdomain","body"
      ],
      "tenantSelectionPrecedence": [
        "tokenClaim","path","header","subdomain","body"
      ],
      "authenticatedSelectionMethods": ["tokenClaim"],
      "tenantClaim": "tenant_id",
      "tenantHeader": "SCIM-Tenant-Id",
      "tenantScopedUniqueness": {
        "userName": "tenant",
        "externalId": "tenant",
        "groupDisplayName": "tenant"
      }
    }
  }
}

8.1. Resolution Rule and Binding Invariant

Let TI(q) be the set of present, canonicalized (Section 8.3) tenant indicators in request q, and let A(q) be the subset of TI(q) that the service provider treats as authenticated (by default, the access-token claim only; see "authenticatedSelectionMethods"). The service provider SHALL resolve and admit a request as follows:¶

T* = value of the highest-precedence element of A(q), if A(q) is
     non-empty; otherwise the highest-precedence element of TI(q).

A request is ADMISSIBLE if and only if:
  (1) the client is authorized for T*, AND
  (2) for every indicator i in TI(q): canonicalize(i) = T*.

Tenant Binding Invariant:
  For any operation that commits a state change, the effective tenant
  equals T*, and the client holds an authorization grant for T*.

Step (1) is the authorization gate. Step (2) is the cross-check that prevents a lower-precedence (possibly spoofable) indicator from silently redirecting the request. Because T* is taken from the highest-precedence authenticated indicator whenever one is present, effective context is never derived from a spoofable source when an authenticated indicator exists. Each rule preserves the invariant: derivation sets the effective tenant to T*; step (1) ensures authorization for T*; step (2) ensures no other indicator disagrees; and canonicalization (Section 8.3) ensures the comparisons in (2) are sound. Implementations SHALL evaluate the gate and cross-check in a way that does not leak tenant existence or authorization; see Section 15.5.¶

8.2. Rejection and Error Uniformity

When a request is not admissible, the service provider SHALL respond as follows:¶

• If the client is not authorized for T* (step (1) fails), the service provider SHALL return HTTP 404 and SHALL return a response that is indistinguishable from the response for a nonexistent Tenant (see Section 15.4). The service provider SHALL NOT reveal that an indicator conflict occurred.¶
• If the client is authorized for T* but a lower-precedence indicator disagrees (step (2) fails), the service provider SHALL return HTTP 400 with a SCIM error response with "scimType = invalidValue". Such a response MAY identify T* (for which the client is authorized) but MUST NOT echo any conflicting tenant identifier for which the client is not authorized.¶

Because the 400 conflict response is reachable only after the authorization gate for T* has been passed, it does not act as an existence or authorization oracle for any other Tenant.¶

8.3. Identifier Canonicalization

Before comparison under Section 8.1, each indicator is mapped to a Tenant "id" and normalized:¶

• A "tokenClaim", "path", "header", or "body" indicator carries a Tenant "id" directly. Tenant "id" values are compared octet-by-octet (case-sensitive); the service provider SHALL NOT apply case folding or Unicode normalization to "id".¶
• A "subdomain" indicator carries an FQDN that is mapped to a Tenant "id" through the verified "domains" of a Tenant. FQDNs are compared after lowercasing, removal of any trailing dot, and conversion of any internationalized labels to their A-label (Punycode) form. An unverified domain SHALL NOT resolve a tenant context.¶

If an indicator cannot be mapped to a Tenant "id" (for example, an unrecognized subdomain), it is treated as not resolving to any Tenant; the request is then handled as in Section 8.2 with respect to T*.¶

8.4. Multi-Tenant Administrative Clients

A single client (for example, an identity-governance administrator) may be authorized for many Tenants under one access token. Such a token cannot name a single Tenant in "tenant_id". To support this case:¶

• If the access token asserts an authorized tenant set rather than a single Tenant, the token claim does not by itself fix T*. A(q) is then empty for the purpose of Section 8.1, and T* is taken from the highest-precedence present indicator in TI(q).¶
• The resolved T* SHALL be a member of the token's authorized tenant set; otherwise the authorization gate (step (1)) fails and Section 8.2 applies. This preserves the Tenant Binding Invariant: T* remains constrained by an authenticated grant even though it is not named by an authenticated indicator.¶

8.5. Token Claim

A service provider that consumes OAuth 2.0 [RFC6749] access tokens or JWT-profile access tokens [RFC9068] SHALL accept a JWT claim named "tenant_id" of type string. The claim value SHALL be the SCIM Tenant "id" the client asserts as the request's tenant context.¶

A service provider MAY additionally accept implementation-specific claims (for example, "tid" for compatibility with deployed ecosystems) and SHALL advertise the primary accepted claim in "ServiceProviderConfig.multiTenancy.tenantClaim". When multiple claims carrying tenant context are present in a single token, the claim named by "tenantClaim" SHALL take precedence.¶

8.6. HTTP Header Field

When an HTTP header-field indicator is used, the canonical field name is "SCIM-Tenant-Id" and its value is the Tenant "id". The field name follows the structured-naming guidance of [RFC9110], Section 16.3.2 and is registered as a provisional HTTP field name; see Section 17. The header field is a tenant-context indicator only and, unless it is listed in "authenticatedSelectionMethods", SHALL NOT be treated as authenticated.¶

8.7. Precedence Configuration

The default precedence is ["tokenClaim", "path", "header", "subdomain", "body"], reflecting that a signed access-token claim is cryptographically bound to the request through OAuth bearer presentation [RFC6750], while URL path, header, subdomain, and body are mutable by intermediaries or by the client. Implementations MAY alter the precedence per deployment. Any deviation from the default SHALL be reflected in "ServiceProviderConfig.multiTenancy.tenantSelectionPrecedence", and any deviation from the default authenticated set SHALL be reflected in "authenticatedSelectionMethods". A service provider SHALL NOT place an unauthenticated indicator ahead of an authenticated one in a way that would allow an unauthenticated indicator to determine T* while an authenticated indicator is present.¶

9.1. Tenant States

While a Tenant is "suspended" or "archived", the service provider SHALL reject state-changing operations on resources owned by that Tenant with HTTP 409 and "scimType = mutability", except operations that themselves transition the Tenant status.¶

9.2. Membership States

9.3. Tenant Deletion and Cascade

A service provider SHALL NOT silently cascade-delete Users or Groups when a Tenant is deleted. On "DELETE /Tenants/{id}":¶

1. If the Tenant owns any tenant-scoped Group or any User whose only membership is in this Tenant, the service provider SHALL reject the request with HTTP 409 and "scimType = uniqueness" unless the client supplies an explicit cascade indication that the service provider documents and advertises. This prevents accidental destruction of identities.¶
2. For a User with memberships in other Tenants, deletion of this Tenant SHALL remove only the membership entry that references this Tenant; the User resource is retained.¶
3. A Tenant SHOULD be in status "archived" before deletion.¶

10.1. Optimistic Concurrency

Service providers SHALL support resource versioning via "meta.version" and HTTP entity-tags as described in [RFC7644], Section 3.14 and [RFC9110], Section 8.8.3. A client that mutates a membership (adds, replaces, or removes a membership entry, or changes "membership.status") SHOULD supply an "If-Match" precondition. A service provider SHALL reject a membership-mutating request whose "If-Match" precondition does not match the current version with HTTP 412. A service provider MAY require the precondition and reject a membership-mutating request that omits "If-Match" with HTTP 428 [RFC6585]. These requirements prevent lost-update races that could otherwise reinstate or escalate a user's presence in a Tenant.¶

10.2. PATCH Targeting of Memberships

A single membership is targeted in a PATCH operation using a value-path filter per [RFC7644], Section 3.5.2, with the schema URI prefix. For example, to suspend a user's membership in one Tenant:¶

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:tenantMembership:2.0:User:memberships[value eq \"tenant-acme\"].status",
      "value": "suspended"
    }
  ]
}

An "op" of "remove" whose path selects an entire membership entry (for example, "...:memberships[value eq \"tenant-acme\"]") ends the user's presence in that Tenant; subsequent operations targeting that Tenant for that user are handled per Section 5.2, item 4. A service provider SHALL reject a PATCH that would leave two membership entries referencing the same Tenant with HTTP 409 and "scimType = uniqueness".¶

13.1. Tenant.regions Sub-Attributes

region:

Type string. Required. Region identifier (deployment-specific).¶

mode:

Type string. Required. Canonical values "readWrite", "readOnly", "authenticationOnly", "unavailable".¶

status:

Type string. Mutability readOnly. Canonical values "available", "degraded", "unavailable".¶

writeAuthority:

Type boolean. Required. Mutability readOnly. At most one region per Tenant SHALL have "writeAuthority = true".¶

13.2. Region Write Authority Rule

When "regions" is present, a service provider SHALL reject a state-changing operation if the receiving region has "writeAuthority = false" for the resolved Tenant. The rejection SHALL return HTTP 409 with "scimType = mutability" and a "Link" header field to the home region's SCIM root, per the discovery semantics of [RFC7644], Section 4.¶

13.3. Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Tenant"
  ],
  "id": "tenant-acme",
  "displayName": "Acme Corporation",
  "status": "active",
  "homeRegion": "region-a",
  "regions": [
    {"region":"region-a","mode":"readWrite",
     "status":"available","writeAuthority":true},
    {"region":"region-b","mode":"authenticationOnly",
     "status":"available","writeAuthority":false}
  ],
  "meta": {
    "resourceType": "Tenant",
    "location": "https://sp.example.com/scim/v2/Tenants/tenant-acme"
  }
}

15.1. Threat Model

The threat model assumes a network-positioned adversary that may craft arbitrary HTTP requests including any combination of tenant indicators, that holds valid credentials for some subset of Tenants, that cannot forge signatures of the trusted OAuth issuer, that cannot break TLS confidentiality or integrity, and that may observe response codes, bodies it is authorized to receive, and response timing.¶

The named attack classes are:¶

1. Indicator confusion: induce a state mutation for a Tenant whose authenticated context disagrees with another indicator.¶
2. Cross-tenant access: read or mutate a resource owned by a Tenant for which the adversary is not authorized.¶
3. Unauthorized membership: create a membership in a Tenant for which the adversary is not authorized.¶
4. Region bypass: cause a write to commit at a region with "writeAuthority = false".¶
5. Lost-update escalation: use a concurrent membership update to reinstate or escalate presence in a Tenant.¶

15.2. Why the Rules Hold

Resistance to attack classes 1-3 reduces to the Tenant Binding Invariant of Section 8.1: every committed state-changing operation acts on T*, and the client is authorized for T*. Indicator confusion (class 1) is prevented because T* is taken from the highest-precedence authenticated indicator when one is present, and step (2) rejects any disagreement; an adversary cannot move effective context to a Tenant other than the one named by an indicator it can authenticate. Cross-tenant access and unauthorized membership (classes 2-3) are prevented by the authorization gate, step (1), which is evaluated for T* before any state change. Region bypass (class 4) is prevented by the write-authority rule of Section 13.2. Lost-update escalation (class 5) is prevented by the concurrency requirements of Section 10.1. These are argued as invariant-preservation properties rather than proved formally; a formal symbolic model is identified as future work in Section 18.¶

15.3. Indicator Trust

The default precedence places the token claim first because it is cryptographically bound to the request. An implementation that downgrades this ordering MUST justify the change in a deployment-specific threat model and MUST reflect the change in "tenantSelectionPrecedence" and "authenticatedSelectionMethods". A service provider SHALL NOT accept an unsigned tenant claim from any indicator that is not authenticated as if it were authenticated.¶

15.4. Tenant Enumeration

A service provider SHALL respond identically to requests for an unauthorized Tenant and a nonexistent Tenant, returning HTTP 404 with no body content that distinguishes the two cases. Differential timing between the two paths SHOULD be minimized; constant-time existence checks are RECOMMENDED for tenant lookup.¶

15.5. Error Message Leakage

Error responses MUST NOT echo Tenant identifiers from indicators that resolved to Tenants the client is not authorized for. As specified in Section 8.2, conflict-rejection (400) responses are reachable only after the authorization gate for T* has passed, and SHALL describe the conflict without revealing any tenant identifier for which the client is unauthorized.¶

15.6. Side-Channel Timing

Tenant-scoped uniqueness checks MAY leak existence via response-time variance. Service providers SHOULD apply constant-time comparison or response-time padding for natural-key uniqueness probes that occur during create operations.¶

15.7. Audit Scoping

Audit events SHALL be scoped to the Tenant the event affects. Cross-tenant administrative audit views SHALL be restricted to clients explicitly authorized for cross-tenant administration.¶

15.8. Region Metadata Exposure

When the region profile is enabled, "Tenant.regions" reveals deployment topology and failover posture. This metadata SHOULD be exposed only to clients with administrative authorization for the Tenant.¶

16.1. Membership Disclosure

Tenant membership reveals customer, partner, employment, or administrative relationships. Service providers SHALL apply least-privilege response shaping. A client authorized only for Tenant "t" SHALL NOT receive memberships of the same User in Tenants other than "t".¶

16.2. Attribute Minimization

"ListResponses" from "/Tenants" SHOULD by default return only "id", "displayName", and "status". Per-Tenant user counts, membership counts, and similar aggregate properties MUST NOT be returned unless explicitly requested by a suitably authorized administrative client.¶

16.3. Data Residency and Cross-Border Transfer

When the region profile is implemented, "homeRegion" and "regions" metadata may correspond to the lawful basis under which the Tenant's personal data is processed. Service providers SHOULD ensure that the "homeRegion" of a Tenant is consistent with the data-residency commitment made to the Tenant's data controller; that cross-region replication is governed by an appropriate data-transfer mechanism, including but not limited to Standard Contractual Clauses under [GDPR], Articles 44 through 49, or equivalent mechanisms in other regimes; and that the exposure of "Tenant.regions" is consistent with data-subject rights under the applicable regime.¶

16.4. Cross-Tenant Analytics

Aggregate analytics across Tenants SHALL NOT be exposed through SCIM endpoints. Such analytics are out of scope of this document.¶

17.1. SCIM Schema URIs

This document requests registration of the following entries in the "SCIM Schema URIs" registry maintained by IANA. The reference for each entry is this document.¶

urn:ietf:params:scim:schemas:core:2.0:Tenant

Name: Tenant¶

urn:ietf:params:scim:schemas:extension:tenantMembership:2.0:User

Name: User Tenant Membership¶

urn:ietf:params:scim:schemas:extension:tenantMembership:2.0:Group

Name: Group Tenant Membership¶

urn:ietf:params:scim:schemas:extension:multiTenancy:2.0:ServiceProviderConfig

Name: Multi-Tenancy ServiceProviderConfig¶

17.2. SCIM Resource Types

This document requests registration of the following entry in the "SCIM Resource Types" registry. The reference is this document.¶

Name:

Tenant¶

Endpoint:

/Tenants¶

Schema:

urn:ietf:params:scim:schemas:core:2.0:Tenant¶

17.3. JSON Web Token Claims

This document requests registration of the following claim in the "JSON Web Token Claims" registry per [RFC7519], Section 10.1. Because tenant identifiers are deployment-specific and several equivalent claims are already deployed, the registration is requested as provisional, with the expectation that the SCIM and OAuth communities confirm or revise the name before any permanent registration.¶

17.4. HTTP Field Name

This document requests provisional registration of the HTTP field name "SCIM-Tenant-Id" in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" per [RFC9110], Section 16.3.1, with status "provisional", a reference to this document, and the field semantics of Section 8.6.¶