SCIM RoleAssignment Draft Specification v0.1

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

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 (for example, User), a scope (for example, Project), and a role (for example, 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."¶

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.¶

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.¶

4.3. subject Sub-Attributes

4.4. scope Sub-Attributes

4.5. role Sub-Attributes

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

4.7. validity Sub-Attributes

4.8. status Semantics

The "status" attribute is readOnly and computed using the following rules:¶

1. If the referenced subject is inactive: status = "suspended".¶

2. If current time < validity.validFrom: status = "pending".¶

3. If current time > validity.validTo: status = "expired".¶

4. Otherwise: status = "active".¶

Special cases:¶

• If validity.validFrom is null, assignment is immediately eligible.¶

• If validity.validTo is null, assignment does not expire.¶

• If explicitly revoked via DELETE or PATCH: status = "revoked".¶

Required status values:¶

• "active": assignment is currently effective.¶

• "expired": validity window has ended.¶

• "pending": assignment created but not yet effective.¶

• "suspended": subject inactive or assignment temporarily disabled.¶

• "revoked": assignment was explicitly withdrawn.¶

4.9. Complete Example

{
  "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": {
    "name": "Developer",
    "value": "developer",
    "$ref": null
  },
  "priority": 100,
  "grant": {
    "source": "HR-System",
    "reason": "New team member onboarding",
    "approver": "manager@company.com"
  },
  "validity": {
    "validFrom": "2025-09-01T00:00:00Z",
    "validTo": "2026-09-01T00:00:00Z"
  },
  "status": "active"
}

5.1. Common Query Patterns

- User's assignments:
  GET /RoleAssignments?filter=subject.value eq "alice@company.com"

- Scope permissions:
  GET /RoleAssignments?filter=scope.value eq "project-x"

- Role discovery within a scope type:
  GET /RoleAssignments?attributes=role&filter=scope.type eq "project"

- Expiring access before a date/time:
  GET /RoleAssignments?filter=validity.validTo le "2025-12-31T23:59:59Z"

6.1. Error Example: Invalid Validity Window

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "validity.validFrom must be before validity.validTo"
}

6.2. Error Example: Conflicting Assignment

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "Active assignment exists for subject 'alice@company.com' with role 'admin' in scope 'project-x'"
}

11.1. Server

• MUST implement RoleAssignment and advertise it in /ResourceTypes.¶

• MUST validate subject, scope, and role.¶

• MUST enforce authorization on RoleAssignment operations.¶

• MUST support GET, POST, PUT, PATCH, DELETE, filtering.¶

• SHOULD support sorting and bulk operations.¶

11.2. Client

• MUST construct RoleAssignments per schema.¶

• MUST process error responses per [RFC7644] .¶

• SHOULD use externalId for idempotency.¶

• SHOULD honor ETag preconditions.¶

12.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC3339]

Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <https://www.rfc-editor.org/info/rfc3339>.

[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, <https://www.rfc-editor.org/info/rfc7643>.

[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, <https://www.rfc-editor.org/info/rfc7644>.

[RFC8141]

Saint-Andre, P. and J. Klensin, "Uniform Resource Names (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, <https://www.rfc-editor.org/info/rfc8141>.

12.2. Informative References

[GITLAB-SCIM]

Documentation, G., "Set up SCIM for GitLab groups", Online accessed September 2025, September 2025, <https://docs.gitlab.com/administration/settings/scim_setup/>.

[TANIUM-RBAC]

Documentation, T., "Role-based access control in the Tanium Console", Online accessed September 2025, September 2025, <https://help.tanium.com/bundle/ug_console_cloud/page/platform_user/console_roles.html>.

[AZURE-SCIM]

Learn, M., "Issue provisioning multiple roles to a SCIM app", Online accessed September 2025, September 2025, <https://learn.microsoft.com/en-us/answers/questions/1632657/issue-provisioning-multiple-roles-to-a-scim-app>.

[SCIM-ROLES-ENTITLEMENTS]

Zollner, C., "Roles and Entitlements Extension for SCIM", Work in Progress, Internet-Draft, draft-zollner-scim-roles-entitlements-extension-02, June 2025, <https://datatracker.ietf.org/doc/draft-zollner-scim-roles-entitlements-extension/>.

A.1. 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.¶