Network Working Group P. Poreddy Internet-Draft Individual Contributor Intended status: Standards Track November 2025 Expires: 8 May 2026 SCIM RoleAssignment Draft Specification v0.2 draft-poreddy-scim-role-assignment-01 Abstract SCIM 2.0 defines "roles" and "entitlements" attributes on the User resource, but it lacks a standardized way to bind roles to specific scopes such as projects, tenants, or groups. This gap forces organizations to rely on group sprawl or non-standard encodings, preventing true interoperability. This document introduces a new SCIM resource type, RoleAssignment, which models scoped role bindings as first-class records, enabling portable provisioning, lifecycle governance, and compliance visibility. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 5 May 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. Poreddy Expires 8 May 2026 [Page 1] Internet-Draft SCIM RoleAssignment November 2025 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 3 1.2. Proposed Solution . . . . . . . . . . . . . . . . . . . . 4 1.3. Design Rationale . . . . . . . . . . . . . . . . . . . . 4 1.3.1. Why not extend User.roles? . . . . . . . . . . . . . 4 1.3.2. Why not use Groups? . . . . . . . . . . . . . . . . . 4 1.3.3. Why a connection resource? . . . . . . . . . . . . . 5 1.3.4. Why immutable core attributes? . . . . . . . . . . . 5 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. Resource Type . . . . . . . . . . . . . . . . . . . . . . 5 4.2. Attributes (Top-Level) . . . . . . . . . . . . . . . . . 5 4.3. subject Sub-Attributes . . . . . . . . . . . . . . . . . 7 4.4. scope Sub-Attributes . . . . . . . . . . . . . . . . . . 7 4.5. role Sub-Attributes . . . . . . . . . . . . . . . . . . . 8 4.6. grant Sub-Attributes . . . . . . . . . . . . . . . . . . 9 4.6.1. approver Sub-Attributes . . . . . . . . . . . . . . . 9 4.7. validity Sub-Attributes . . . . . . . . . . . . . . . . . 10 4.8. Resource Mutability . . . . . . . . . . . . . . . . . . . 11 4.9. status Semantics . . . . . . . . . . . . . . . . . . . . 11 4.10. JSON Schema representation . . . . . . . . . . . . . . . 12 4.11. Soft Delete and Audit Trail . . . . . . . . . . . . . . . 18 4.12. Complete Example . . . . . . . . . . . . . . . . . . . . 18 5. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.1. Create (POST) . . . . . . . . . . . . . . . . . . . . . . 20 5.2. Read (GET) . . . . . . . . . . . . . . . . . . . . . . . 20 5.3. Replace (PUT) . . . . . . . . . . . . . . . . . . . . . . 20 5.4. Patch (PATCH) . . . . . . . . . . . . . . . . . . . . . . 20 5.5. Delete (DELETE) . . . . . . . . . . . . . . . . . . . . . 20 5.6. Filter (GET with filter parameter) . . . . . . . . . . . 20 5.7. Pagination and Sorting . . . . . . . . . . . . . . . . . 20 5.8. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 21 5.9. Common Query Patterns . . . . . . . . . . . . . . . . . . 21 5.9.1. User's assignments (excluding revoked): . . . . . . . 21 5.9.2. All assignments in a scope: . . . . . . . . . . . . . 21 5.9.3. Role discovery within a scope type: . . . . . . . . . 21 Poreddy Expires 8 May 2026 [Page 2] Internet-Draft SCIM RoleAssignment November 2025 5.9.4. Expiring assignments: . . . . . . . . . . . . . . . . 21 5.9.5. Audit trail - recently revoked assignments: . . . . . 21 5.9.6. All active assignments (operational query): . . . . . 21 5.10. Invalid Validity Window . . . . . . . . . . . . . . . . . 22 5.11. Invalid Resource Reference . . . . . . . . . . . . . . . 22 5.12. Duplicate Active Assignment . . . . . . . . . . . . . . . 22 5.13. Immutable Attribute Modification . . . . . . . . . . . . 22 6. Backward Compatibility . . . . . . . . . . . . . . . . . . . 23 7. Security Considerations . . . . . . . . . . . . . . . . . . . 23 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 24 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 10. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 24 10.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . 24 10.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . 25 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.1. draft-poreddy-scim-role-assignment-01 . . . . . . . . . 26 11.2. draft-poreddy-scim-role-assignment-00 . . . . . . . . . 26 12. Author's Address . . . . . . . . . . . . . . . . . . . . . . 26 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 13.1. Normative References . . . . . . . . . . . . . . . . . . 26 13.2. Informative References . . . . . . . . . . . . . . . . . 27 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 1. Introduction 1.1. Problem Statement The SCIM protocol [RFC7643] [RFC7644] defines the User and Group resources and allows global roles to be attached to Users via the "roles" attribute. However, the specification does not provide a standardized way to associate roles with specific scopes such as projects, tenants, or device groups. This limitation prevents SCIM from modeling the most common real- world requirement: assigning different roles to the same identity in different contexts. For example, consider a user named Alice: User: Alice +-- Global Role: Power User +-- Project A: Maintainer +-- Project B: Developer +-- Project C: ReadOnly Poreddy Expires 8 May 2026 [Page 3] Internet-Draft SCIM RoleAssignment November 2025 Today, there is no interoperable SCIM method to represent Alice's per-project role bindings. Current workarounds include creating Groups for every {scope x role} combination, which leads to group sprawl and poor interoperability, or embedding scope names into free- form role strings, which are not machine-readable or portable. These limitations are visible in real-world SCIM implementations: GitLab [GITLAB-SCIM], Tanium [TANIUM-RBAC], and scenarios in Microsoft Entra ID [AZURE-SCIM]. 1.2. Proposed Solution This document introduces a new SCIM 2.0 resource, _RoleAssignment_, which makes scoped role bindings a first-class concept. Each RoleAssignment explicitly links a subject (e.g., User), a scope (e.g., Project), and a role (e.g., Developer). Optional metadata such as validity periods, source system, and approver information enable lifecycle management and governance. By standardizing RoleAssignments: * Identity Providers can provision scoped roles in a portable way. * Service Providers can expose and consume these assignments consistently. * Auditors and governance systems can query "who has what role in which scope." 1.3. Design Rationale This specification introduces RoleAssignment as a standalone resource type rather than extending existing SCIM resources for the following reasons: 1.3.1. Why not extend User.roles? User.roles is a multi-valued attribute without scope information. Extending it would require complex nested structures that don't fit SCIM's flat attribute model and would make querying and lifecycle management difficult. 1.3.2. Why not use Groups? Using Groups for every {scope × role} combination leads to group sprawl and poor scalability. A system with 100 projects and 5 roles would require 500 groups. Group membership also lacks the metadata needed for governance (validity periods, approval chains). Poreddy Expires 8 May 2026 [Page 4] Internet-Draft SCIM RoleAssignment November 2025 1.3.3. Why a connection resource? Unlike SCIM's traditional approach of embedding relationships, RoleAssignments have their own lifecycle, metadata, and audit requirements. They need: - Independent querying ("show all Developer roles in Project X") - Temporal validity and expiration - Approval and provenance tracking - Status transitions independent of subject or scope 1.3.4. Why immutable core attributes? Making subject, scope, and role immutable ensures audit integrity. Each RoleAssignment represents a discrete authorization event. Changes to these core attributes represent new authorization decisions and should be tracked as separate resources. 2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Overview The RoleAssignment resource complements existing SCIM resources. Whereas the User.roles attribute provides only coarse global roles, RoleAssignment expresses who (subject) has what role in which scope. This allows interoperable provisioning of scoped role bindings. 4. Schema 4.1. Resource Type { "name": "RoleAssignment", "endpoint": "/RoleAssignments", "schema": "urn:ietf:params:scim:schemas:core:2.0:RoleAssignment", "schemaExtensions": [] } 4.2. Attributes (Top-Level) The RoleAssignment resource defines the following top-level attributes. Poreddy Expires 8 May 2026 [Page 5] Internet-Draft SCIM RoleAssignment November 2025 +===========+=========+=====+=======+============+==================+ | Attribute | Type | Req | Multi | Mutability | Description | +===========+=========+=====+=======+============+==================+ | subject | complex | yes | no | immutable | The subject | | | | | | | receiving the | | | | | | | role. | +-----------+---------+-----+-------+------------+------------------+ | scope | complex | yes | no | immutable | The scope | | | | | | | where the role | | | | | | | applies. | +-----------+---------+-----+-------+------------+------------------+ | role | complex | yes | no | immutable | The role | | | | | | | granted within | | | | | | | the scope. | +-----------+---------+-----+-------+------------+------------------+ | priority | integer | no | no | readWrite | Conflict | | | | | | | resolution | | | | | | | (higher wins). | | | | | | | Default 0. | +-----------+---------+-----+-------+------------+------------------+ | grant | complex | no | no | readWrite | Assignment | | | | | | | metadata | | | | | | | (source, | | | | | | | reason, | | | | | | | approver). | +-----------+---------+-----+-------+------------+------------------+ | validity | complex | no | no | readWrite | Validity | | | | | | | window in UTC. | +-----------+---------+-----+-------+------------+------------------+ | status | string | no | no | readOnly | Computed | | | | | | | lifecycle | | | | | | | status. | +-----------+---------+-----+-------+------------+------------------+ Table 1 "The common attributes (id, externalId, meta) defined in RFC 7643 Section 3.1 are inherited by RoleAssignment and are not redefined here." _Priority usage guidance:_ When multiple active assignments exist for the same subject and scope, the assignment with the highest priority takes precedence. If priorities are equal, implementation- defined resolution rules apply. Poreddy Expires 8 May 2026 [Page 6] Internet-Draft SCIM RoleAssignment November 2025 4.3. subject Sub-Attributes +===========+===========+===+=======+============+==================+ | Attribute | Type |Req| Multi | Mutability | Description | +===========+===========+===+=======+============+==================+ | value | string |yes| no | immutable | Identifier of | | | | | | | the subject. | | | | | | | If the subject | | | | | | | is a resource, | | | | | | | value MUST | | | | | | | equal the id | | | | | | | attribute of | | | | | | | that resource. | +-----------+-----------+---+-------+------------+------------------+ | $ref | reference |no | no | immutable | URI to the | | | | | | | subject | | | | | | | resource, if | | | | | | | the subject is | | | | | | | a resource. | +-----------+-----------+---+-------+------------+------------------+ | type | string |no | no | immutable | Subject type. | | | | | | | If the subject | | | | | | | is a resource, | | | | | | | type MUST | | | | | | | equal the | | | | | | | resource type | | | | | | | name of that | | | | | | | resource. | +-----------+-----------+---+-------+------------+------------------+ | display | string |no | no | immutable | A human- | | | | | | | readable name | | | | | | | for the | | | | | | | subject. | +-----------+-----------+---+-------+------------+------------------+ Table 2 4.4. scope Sub-Attributes +=========+===========+===+=====+============+======================+ |Attribute| Type |Req|Multi| Mutability | Description | +=========+===========+===+=====+============+======================+ |type | string |yes|no | immutable | Scope type. | | | | | | | Common: "project", | | | | | | | "tenant", | | | | | | | "organization", | | | | | | | "application", | | | | | | | "environment". | Poreddy Expires 8 May 2026 [Page 7] Internet-Draft SCIM RoleAssignment November 2025 +---------+-----------+---+-----+------------+----------------------+ |value | string |yes|no | immutable | Provider-meaningful | | | | | | | identifier of the | | | | | | | scope. | +---------+-----------+---+-----+------------+----------------------+ |$ref | reference |no |no | immutable | URI to the scope | | | | | | | resource, if | | | | | | | available. | | | | | | | Optional when scope | | | | | | | is opaque. | +---------+-----------+---+-----+------------+----------------------+ |display | string |no |no | immutable | A human-readable | | | | | | | name for the scope. | +---------+-----------+---+-----+------------+----------------------+ Table 3 4.5. role Sub-Attributes +===========+===========+===+=======+============+=================+ | Attribute | Type |Req| Multi | Mutability | Description | +===========+===========+===+=======+============+=================+ | value | string |yes| no | immutable | Stable | | | | | | | identifier for | | | | | | | the role. If | | | | | | | the role is a | | | | | | | resource, value | | | | | | | MUST equal the | | | | | | | id attribute of | | | | | | | that resource. | +-----------+-----------+---+-------+------------+-----------------+ | display | string |no | no | immutable | Human-readable | | | | | | | name of the | | | | | | | role. | +-----------+-----------+---+-------+------------+-----------------+ | $ref | reference |no | no | immutable | URI to a role | | | | | | | catalog entry | | | | | | | or role | | | | | | | resource, if | | | | | | | the role is a | | | | | | | resource. | +-----------+-----------+---+-------+------------+-----------------+ | type | string |no | no | immutable | Role type. If | | | | | | | the role is a | | | | | | | resource, type | | | | | | | MUST equal the | | | | | | | resource type | | | | | | | name of that | Poreddy Expires 8 May 2026 [Page 8] Internet-Draft SCIM RoleAssignment November 2025 | | | | | | resource. | +-----------+-----------+---+-------+------------+-----------------+ Table 4 _Role Discovery Guidance:_ Since role.$ref is optional, servers SHOULD support filtering on role and scope to enable discovery, for example: GET /RoleAssignments?attributes=role,scope& filter=scope.type eq "project" Providers that expose a role catalog MAY align discovery with the SCIM Roles and Entitlements approach [SCIM-ROLES-ENTITLEMENTS]. 4.6. grant Sub-Attributes +===========+=========+=====+=======+============+================+ | Attribute | Type | Req | Multi | Mutability | Description | +===========+=========+=====+=======+============+================+ | source | string | no | no | immutable | Originating | | | | | | | system or | | | | | | | process. | +-----------+---------+-----+-------+------------+----------------+ | reason | string | no | no | readWrite | Human-readable | | | | | | | justification. | +-----------+---------+-----+-------+------------+----------------+ | approver | complex | no | no | immutable | The approver | | | | | | | of this | | | | | | | assignment. | +-----------+---------+-----+-------+------------+----------------+ Table 5 4.6.1. approver Sub-Attributes +===========+===========+===+=======+============+=================+ | Attribute | Type |Req| Multi | Mutability | Description | +===========+===========+===+=======+============+=================+ | value | string |yes| no | immutable | Identifier of | | | | | | | the approver. | | | | | | | If the approver | | | | | | | is a resource, | | | | | | | value MUST | | | | | | | equal the id | | | | | | | attribute of | | | | | | | that resource. | +-----------+-----------+---+-------+------------+-----------------+ Poreddy Expires 8 May 2026 [Page 9] Internet-Draft SCIM RoleAssignment November 2025 | $ref | reference |no | no | immutable | URI to the | | | | | | | approver | | | | | | | resource, if | | | | | | | the approver is | | | | | | | a resource. | +-----------+-----------+---+-------+------------+-----------------+ | type | string |no | no | immutable | Approver type. | | | | | | | If the approver | | | | | | | is a resource, | | | | | | | type MUST equal | | | | | | | the resource | | | | | | | type name of | | | | | | | that resource. | +-----------+-----------+---+-------+------------+-----------------+ | display | string |no | no | immutable | A human- | | | | | | | readable name | | | | | | | for the | | | | | | | approver. | +-----------+-----------+---+-------+------------+-----------------+ Table 6 4.7. validity Sub-Attributes +===========+==========+=====+=======+============+=================+ | Attribute | Type | Req | Multi | Mutability | Description | +===========+==========+=====+=======+============+=================+ | validFrom | dateTime | no | no | readWrite | Start of | | | | | | | validity | | | | | | | window | | | | | | | ([RFC3339] | | | | | | | format with | | | | | | | optional | | | | | | | timezone | | | | | | | offset). | +-----------+----------+-----+-------+------------+-----------------+ | validTo | dateTime | no | no | readWrite | End of | | | | | | | validity | | | | | | | window | | | | | | | ([RFC3339] | | | | | | | format with | | | | | | | optional | | | | | | | timezone | | | | | | | offset). | +-----------+----------+-----+-------+------------+-----------------+ Table 7 Poreddy Expires 8 May 2026 [Page 10] Internet-Draft SCIM RoleAssignment November 2025 4.8. Resource Mutability RoleAssignment resources have restricted mutability to maintain audit integrity: IMMUTABLE attributes (cannot be changed after creation): - subject, scope, role: The core binding cannot change - grant.source, grant.approver: Provenance must be preserved MUTABLE attributes (can be updated via PATCH/PUT): - priority: Allow conflict resolution - validity: Allow time-bound extensions - grant.reason: Allow justification updates To change immutable attributes, clients MUST delete the existing assignment and create a new one. This ensures each role grant is an explicit, auditable event. 4.9. status Semantics The "status" attribute is readOnly and computed by the server. Clients cannot set this value directly. Status computation rules (evaluated in order): 1. If the resource has been soft-deleted (see Section 4.9): status = "revoked" 2. If the referenced subject.active is false: status = "suspended" 3. If current time < validity.validFrom: status = "pending" 4. If current time > validity.validTo: status = "expired" 5. Otherwise: status = "active" Special cases: * If validity.validFrom is null, the assignment is immediately eligible. * If validity.validTo is null, the assignment does not expire. Required status values: * "active": assignment is currently effective * "expired": validity window has ended Poreddy Expires 8 May 2026 [Page 11] Internet-Draft SCIM RoleAssignment November 2025 * "pending": assignment created but not yet effective * "suspended": subject inactive or assignment temporarily disabled * "revoked": assignment was explicitly withdrawn via DELETE operation 4.10. JSON Schema representation { "id": "urn:ietf:params:scim:schemas:core:2.0:RoleAssignment", "name": "RoleAssignment", "description": "SCIM RoleAssignment Resource", "attributes": [ { "name": "subject", "type": "complex", "description": "The subject receiving the role", "required": true, "mutability": "immutable", "returned": "always", "uniqueness": "none", "subAttributes": [ { "name": "value", "type": "string", "description": "Identifier of the subject. If the subject is a resource, value MUST equal the id attribute of that resource.", "required": true, "mutability": "immutable", "returned": "always", "caseExact": false, "uniqueness": "none" }, { "name": "$ref", "type": "reference", "description": "URI to the subject resource, if the subject is a resource", "required": false, "mutability": "immutable", "returned": "default", "referenceTypes": ["User", "Group"], "uniqueness": "none" }, { "name": "type", "type": "string", "description": "Subject type. If the subject is a resource, type MUST equal the resource type name of that resource.", "required": false, Poreddy Expires 8 May 2026 [Page 12] Internet-Draft SCIM RoleAssignment November 2025 "mutability": "immutable", "returned": "default", "caseExact": false, "canonicalValues": ["User", "Group"], "uniqueness": "none" }, { "name": "display", "type": "string", "description": "A human-readable name for the subject", "required": false, "mutability": "immutable", "returned": "default", "caseExact": false, "uniqueness": "none" } ] }, { "name": "scope", "type": "complex", "description": "The scope where the role applies", "required": true, "mutability": "immutable", "returned": "always", "uniqueness": "none", "subAttributes": [ { "name": "type", "type": "string", "description": "Scope type. Common values include 'project', 'tenant', 'organization', 'application', 'environment'", "required": true, "mutability": "immutable", "returned": "always", "caseExact": false, "uniqueness": "none" }, { "name": "value", "type": "string", "description": "Provider-meaningful identifier of the scope. If the scope is a resource, value MUST equal the id attribute of that resource.", "required": true, "mutability": "immutable", "returned": "always", "caseExact": false, "uniqueness": "none" }, { Poreddy Expires 8 May 2026 [Page 13] Internet-Draft SCIM RoleAssignment November 2025 "name": "$ref", "type": "reference", "description": "URI to the scope resource, if the scope is a resource", "required": false, "mutability": "immutable", "returned": "default", "referenceTypes": [], "uniqueness": "none" }, { "name": "display", "type": "string", "description": "A human-readable name for the scope", "required": false, "mutability": "immutable", "returned": "default", "caseExact": false, "uniqueness": "none" } ] }, { "name": "role", "type": "complex", "description": "The role granted within the scope", "required": true, "mutability": "immutable", "returned": "always", "uniqueness": "none", "subAttributes": [ { "name": "value", "type": "string", "description": "Stable identifier for the role. If the role is a resource, value MUST equal the id attribute of that resource.", "required": true, "mutability": "immutable", "returned": "always", "caseExact": false, "uniqueness": "none" }, { "name": "display", "type": "string", "description": "Human-readable name of the role", "required": false, "mutability": "immutable", "returned": "default", "caseExact": false, Poreddy Expires 8 May 2026 [Page 14] Internet-Draft SCIM RoleAssignment November 2025 "uniqueness": "none" }, { "name": "$ref", "type": "reference", "description": "URI to a role catalog entry or role resource, if available", "required": false, "mutability": "immutable", "returned": "default", "referenceTypes": [], "uniqueness": "none" }, { "name": "type", "type": "string", "description": "Role type. If the role is a resource, type MUST equal the resource type name of that resource.", "required": false, "mutability": "immutable", "returned": "default", "caseExact": false, "uniqueness": "none" } ] }, { "name": "priority", "type": "integer", "description": "Conflict resolution priority. Higher values take precedence. Default is 0.", "required": false, "mutability": "readWrite", "returned": "default", "uniqueness": "none" }, { "name": "grant", "type": "complex", "description": "Assignment metadata", "required": false, "mutability": "readWrite", "returned": "default", "uniqueness": "none", "subAttributes": [ { "name": "source", "type": "string", "description": "Originating system or process", "required": false, "mutability": "immutable", Poreddy Expires 8 May 2026 [Page 15] Internet-Draft SCIM RoleAssignment November 2025 "returned": "default", "caseExact": false, "uniqueness": "none" }, { "name": "reason", "type": "string", "description": "Human-readable justification for the assignment", "required": false, "mutability": "readWrite", "returned": "default", "caseExact": false, "uniqueness": "none" }, { "name": "approver", "type": "complex", "description": "The approver of this assignment", "required": false, "mutability": "immutable", "returned": "default", "uniqueness": "none", "subAttributes": [ { "name": "value", "type": "string", "description": "Identifier of the approver. If the approver is a resource, value MUST equal the id attribute of that resource.", "required": true, "mutability": "readWrite", "returned": "default", "caseExact": false, "uniqueness": "none" }, { "name": "$ref", "type": "reference", "description": "URI to the approver resource, if the approver is a resource", "required": false, "mutability": "readWrite", "returned": "default", "referenceTypes": ["User"], "uniqueness": "none" }, { "name": "type", "type": "string", "description": "Approver type. If the approver is a resource, type MUST equal the resource type name of that resource.", "required": false, Poreddy Expires 8 May 2026 [Page 16] Internet-Draft SCIM RoleAssignment November 2025 "mutability": "readWrite", "returned": "default", "caseExact": false, "canonicalValues": ["User"], "uniqueness": "none" }, { "name": "display", "type": "string", "description": "A human-readable name for the approver", "required": false, "mutability": "readWrite", "returned": "default", "caseExact": false, "uniqueness": "none" } ] } ] }, { "name": "validity", "type": "complex", "description": "Validity window", "required": false, "mutability": "readWrite", "returned": "default", "uniqueness": "none", "subAttributes": [ { "name": "validFrom", "type": "dateTime", "description": "Start of validity window (RFC3339 format with optional timezone offset)", "required": false, "mutability": "readWrite", "returned": "default", "uniqueness": "none" }, { "name": "validTo", "type": "dateTime", "description": "End of validity window (RFC3339 format with optional timezone offset)", "required": false, "mutability": "readWrite", "returned": "default", "uniqueness": "none" } ] Poreddy Expires 8 May 2026 [Page 17] Internet-Draft SCIM RoleAssignment November 2025 }, { "name": "status", "type": "string", "description": "Computed lifecycle status", "required": false, "mutability": "readOnly", "returned": "default", "caseExact": true, "canonicalValues": ["active", "expired", "pending", "suspended", "revoked"], "uniqueness": "none" } ] } 4.11. Soft Delete and Audit Trail RoleAssignment resources support soft deletion to maintain audit trails and compliance records. When a DELETE operation is performed on a RoleAssignment: - The resource is NOT physically removed from the system - The status is set to "revoked" - The meta.lastModified timestamp is updated - The resource remains queryable but is typically excluded from standard operational queries Servers SHOULD support filtering to exclude revoked assignments from normal operations: GET /RoleAssignments?filter=status ne "revoked" Servers MAY implement retention policies to permanently delete revoked assignments after a configurable period (e.g., 90 days, 1 year) for compliance purposes. Clients performing access control decisions MUST exclude assignments with status="revoked". 4.12. Complete Example Poreddy Expires 8 May 2026 [Page 18] Internet-Draft SCIM RoleAssignment November 2025 { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:RoleAssignment"], "id": "assignment-12345", "externalId": "ext-assign-001", "subject": { "value": "alice@company.com", "$ref": "https://example.com/scim/v2/Users/alice", "type": "User" }, "scope": { "type": "project", "value": "web-app-proj", "$ref": null }, "role": { "display": "Developer", "value": "developer", "$ref": null }, "priority": 100, "grant": { "source": "HR-System", "reason": "New team member onboarding", "approver": { "value": "manager@company.com", "$ref": "https://example.com/scim/v2/Users/manager", "type": "User", "display": "Alice Manager" } }, "validity": { "validFrom": "2025-09-01T00:00:00Z", "validTo": "2026-09-01T00:00:00Z" }, "status": "active" } Note: When this assignment is deleted via DELETE, the resource will remain with status changed to "revoked" and meta.lastModified updated, rather than being removed from the system. 5. Operations RoleAssignment resources support standard SCIM operations with the following requirements: Poreddy Expires 8 May 2026 [Page 19] Internet-Draft SCIM RoleAssignment November 2025 5.1. Create (POST) Servers MUST validate that subject, scope, and role reference valid resources or identifiers. Missing required attributes cause 400 Bad Request per RFC 7644. 5.2. Read (GET) Servers MUST support retrieval of individual RoleAssignment resources by id. 5.3. Replace (PUT) Servers MUST support full resource replacement. Attempts to modify immutable attributes (subject, scope, role, grant.source, grant.approver) MUST result in 400 Bad Request with appropriate error detail. 5.4. Patch (PATCH) If PATCH is supported (per ServiceProviderConfig), servers MUST: - Prevent modification of immutable attributes - Validate that changes do not create invalid states - Return 400 Bad Request for operations attempting to modify immutable attributes 5.5. Delete (DELETE) Servers MUST implement soft deletion: the DELETE operation sets status="revoked" and updates meta.lastModified rather than physically removing the resource. The resource remains queryable for audit purposes. Servers MUST immediately revoke the associated permissions in the target system. 5.6. Filter (GET with filter parameter) If filtering is supported (per ServiceProviderConfig), servers MUST support filters on: - subject.value - scope.value - scope.type - role.value - status Example: GET /RoleAssignments?filter=subject.value eq "alice@company.com" and status ne "revoked" 5.7. Pagination and Sorting Servers MUST support pagination using startIndex and count parameters per RFC 7644. Poreddy Expires 8 May 2026 [Page 20] Internet-Draft SCIM RoleAssignment November 2025 If sorting is supported (per ServiceProviderConfig), servers SHOULD support sorting by: - meta.created - meta.lastModified - validity.validFrom - validity.validTo 5.8. Bulk Operations Bulk operations MAY be supported per RFC 7644. Support is indicated in ServiceProviderConfig. Clients using bulk operations SHOULD populate externalId to enable idempotent retry of failed bulk requests. 5.9. Common Query Patterns 5.9.1. User's assignments (excluding revoked): GET /RoleAssignments?filter=subject.value eq "alice@company.com" and status ne "revoked" 5.9.2. All assignments in a scope: GET /RoleAssignments?filter=scope.value eq "project-x" 5.9.3. Role discovery within a scope type: GET /RoleAssignments?attributes=role,scope&filter=scope.type eq "project" 5.9.4. Expiring assignments: GET /RoleAssignments?filter=validity.validTo le "2025-12-31T23:59:59Z" and status ne "revoked" 5.9.5. Audit trail - recently revoked assignments: GET /RoleAssignments?filter=status eq "revoked" and meta.lastModified ge "2025-09-01T00:00:00Z" 5.9.6. All active assignments (operational query): GET /RoleAssignments?filter=status eq "active" # Error Handling RoleAssignment operations follow standard SCIM error handling per RFC 7644 Section 3.12. This section describes RoleAssignment-specific error conditions. Poreddy Expires 8 May 2026 [Page 21] Internet-Draft SCIM RoleAssignment November 2025 5.10. Invalid Validity Window Status: 400 Bad Request scimType: invalidValue Occurs when: - validity.validFrom is after validity.validTo - Date formats are invalid Example: json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "400", "scimType": "invalidValue", "detail": "validity.validFrom must be before validity.validTo" } 5.11. Invalid Resource Reference Status: 400 Bad Request scimType: invalidValue Occurs when: - subject.value references a non-existent or invalid resource - scope.value references a non-existent or invalid scope - role.value references a non-existent or invalid role Example: json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "400", "scimType": "invalidValue", "detail": "subject.value 'alice@example.com' does not reference a valid User resource" } 5.12. Duplicate Active Assignment Status: 409 Conflict scimType: uniqueness Occurs when attempting to create an assignment that would result in multiple active assignments with the same subject, scope, and role combination (unless distinguished by priority or validity windows). Example: json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "409", "scimType": "uniqueness", "detail": "Active assignment already exists for subject 'alice@company.com' with role 'Developer' in scope 'project-x'" } 5.13. Immutable Attribute Modification Status: 400 Bad Request scimType: mutability Occurs when attempting to modify immutable attributes (subject, scope, role, grant.source, grant.approver) via PUT or PATCH operations. Poreddy Expires 8 May 2026 [Page 22] Internet-Draft SCIM RoleAssignment November 2025 Example: json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "400", "scimType": "mutability", "detail": "Attribute 'subject' is immutable and cannot be modified. Delete and recreate the assignment to change the subject." } 6. Backward Compatibility Providers MAY continue to expose global roles via User.roles and coarse-grained membership via Groups. Providers SHOULD offer mapping guidance between legacy models and RoleAssignments. During migration, providers are RECOMMENDED to: - Maintain both User.roles and RoleAssignments representations (dual-writing) - Use RoleAssignments for new scoped role grants - Gradually migrate existing Group-based role patterns to RoleAssignments - Preserve audit history when converting legacy role assignments Clients transitioning to RoleAssignments SHOULD: - Query both User.roles and RoleAssignments during migration periods - Implement fallback logic for providers not yet supporting RoleAssignments - Use externalId to correlate legacy role grants with new RoleAssignment resources 7. Security Considerations * RoleAssignment creation and modification are privileged operations. * Servers MUST validate references to prevent privilege escalation. * Lifecycle events SHOULD be logged with actor and justification. * Replay and bulk abuse MUST be mitigated with rate limiting and idempotency. * Soft deletion preserves audit trails but increases storage requirements and query complexity. Servers MUST ensure that revoked assignments are excluded from authorization decisions, even though they remain in the data store. Servers SHOULD implement periodic cleanup of old revoked assignments according to organizational retention policies. Access to revoked assignments SHOULD be restricted to auditors and compliance personnel. Poreddy Expires 8 May 2026 [Page 23] Internet-Draft SCIM RoleAssignment November 2025 8. Privacy Considerations RoleAssignments may expose organizational structures and access patterns. Sensitive metadata SHOULD follow least-privilege disclosure. 9. IANA Considerations This specification requests registration of the following SCIM schema: * URN: urn:ietf:params:scim:schemas:core:2.0:RoleAssignment * Specification: this document * Contact: IETF SCIM Working Group * Change Controller: IESG Experimental namespace MAY also be used: * URN: urn:ietf:params:scim:schemas:extension:role:1.0:RoleAssignment URNs are assigned and interpreted in accordance with [RFC8141]. 10. Conformance 10.1. Server A conformant SCIM server implementation: * MUST implement RoleAssignment resource type and advertise it in /ResourceTypes * MUST validate subject, scope, and role references on all operations * MUST enforce authorization on RoleAssignment operations * MUST support GET, POST, PUT, DELETE operations * MUST enforce immutability of subject, scope, role, grant.source, and grant.approver attributes * MUST implement soft deletion: DELETE operations set status="revoked" rather than removing resources Poreddy Expires 8 May 2026 [Page 24] Internet-Draft SCIM RoleAssignment November 2025 * MUST exclude status="revoked" assignments from authorization decisions * MUST support filtering on subject.value, scope.value, scope.type, role.value, and status (if filtering is supported per ServiceProviderConfig) * SHOULD support PATCH operations per RFC 7644 * SHOULD support sorting by meta.created, meta.lastModified, and validity fields (if sorting is supported per ServiceProviderConfig) * SHOULD support bulk operations per RFC 7644 * MAY implement retention policies for permanent deletion of old revoked assignments 10.2. Client A conformant SCIM client implementation: * MUST construct RoleAssignments with all required attributes per the schema * MUST process error responses per RFC 7644 Section 3.12 * MUST NOT use assignments with status="revoked" for access control decisions * MUST NOT attempt to modify immutable attributes (subject, scope, role, grant.source, grant.approver) * SHOULD use externalId for idempotency, especially in bulk operations * SHOULD honor ETag preconditions for conditional updates * SHOULD filter out revoked assignments in operational queries using filter=status ne "revoked" * MAY query revoked assignments for audit and compliance purposes 11. Change Log Poreddy Expires 8 May 2026 [Page 25] Internet-Draft SCIM RoleAssignment November 2025 11.1. draft-poreddy-scim-role-assignment-01 Second version. Major changes based on working group feedback: - Added complete JSON Schema definitions with mutability specifications - Implemented soft deletion for audit trail preservation - Made subject, scope, and role immutable; priority and validity mutable - Restructured grant.approver as complex attribute with full reference pattern - Added explicit resource mutability section and design rationale - Updated all attribute tables to reflect immutability decisions - Enhanced error handling with RoleAssignment-specific scenarios - Clarified Operations section with ServiceProviderConfig references - Added comprehensive conformance requirements for servers and clients 11.2. draft-poreddy-scim-role-assignment-00 Initial version. Defines RoleAssignment schema, attributes, and operations. Adds priority, complete example, error examples, and query patterns. Includes error handling, backward compatibility, and IANA registration. Updates BCP14 boilerplate; replaces non-ASCII; converts ASCII tables to RFCXML tables; updates Roles/Entitlements reference to -02; cites RFC8141. 12. Author's Address Prithvi Poreddy Email: prithvikrishnab4u@gmail.com 13. References 13.1. Normative References [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. Mortimore, "System for Cross-domain Identity Management: Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 2015, . [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., and C. Mortimore, "System for Cross-domain Identity Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, September 2015, . [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, . Poreddy Expires 8 May 2026 [Page 26] Internet-Draft SCIM RoleAssignment November 2025 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 13.2. Informative References [GITLAB-SCIM] GitLab Documentation, "Set up SCIM for GitLab groups", September 2025, . [TANIUM-RBAC] Tanium Documentation, "Role-based access control in the Tanium Console", September 2025, . [AZURE-SCIM] Microsoft Learn, "Issue provisioning multiple roles to a SCIM app", September 2025, . [SCIM-ROLES-ENTITLEMENTS] Zöllner, C., "Roles and Entitlements Extension for SCIM", Work in Progress, Internet-Draft, draft-zollner-scim- roles-entitlements-extension-02, June 2025, . Author's Address Prithvi Poreddy Individual Contributor United States of America Email: prithvikrishnab4u@gmail.com Poreddy Expires 8 May 2026 [Page 27]