SCIM provisioning API basic implementation

[azmeuk]

This is an implementation of MSC4098. It implements a subset of the SCIM provisioning protocol defined in RFC7643 and RFC7644.

It contains:

• A SCIM servlet implementing the minimal SCIM endpoints.
  • The data edition/retrieval part largely takes inspiration (and shameless copied) from synapse/rest/admin/users.py.
  • The SCIM payload validation and production is achieved with scim2-models, a library based on pydantic which I maintain.
• Unit tests for those endpoints.
• Documentation on the state of the SCIM implementation, and examples of requests and response payloads.

The SCIM requires needs python 3.9+ (because of the use of typing.Anotated in scim2-models) and pydantic 2.7.0+

SCIM implementation details

Only a subset of the SCIM endpoints are implemented:

What's implemented:

• The main endpoints:
  • /Users (GET, POST)
  • /Users/<user_id> (GET, PUT, DELETE)
  • /ServiceProviderConfig (GET)
  • /Schemas (GET)
  • /Schemas/<schema_id> (GET)
  • /ResourceTypes (GET)
  • /ResourceTypes/<resource_type_id>
• pagination
• The user attributes:
  • userName
  • password
  • emails
  • phoneNumbers
  • displayName
  • photos (as a MXC URI)
  • active

What is defined in the SCIM specs but not implemented here:

• A few endpoints:
  • /Users (PATCH)
  • /Me (GET, POST, PUT, PATCH, DELETE)
  • /Groups (GET, POST, PUT, PATCH) (but this no relevant)
  • /Bulk (POST)
  • /.search (POST)
• filtering
• sorting
• attributes selection
• ETags

What do you think?

Pull Request Checklist

• Pull request is based on the develop branch
• Pull request includes a changelog file. The entry should:
  • Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
  • Use markdown where necessary, mostly for code blocks.
  • End with either a period (.) or an exclamation mark (!).
  • Start with a capital letter.
  • Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
• Code style is correct
  (run the linters)

[erikjohnston]

(I've taken this out of the review queue as its in draft, let us know if you want feedback)

[azmeuk]

Hi @erikjohnston
Thank you for your feedback offering. Indeed this is a draft, but I hope to take back the development soon.

There is one design question though. I see that there is a dependency to pydantic in synapse, and I recently published scim2-models that is a library that helps to parse and serialize SCIM2 payloads using pydantic. I think the SCIM implementation would greatly benefit from using scim2-models, as a big part of the specification compliance would be delegated to the library.

Would it be acceptable to add a dependency towards scim2-models in synapse, or should I continue checking and building SCIM2 payloads manually?

[azmeuk]

Hi @erikjohnston
I think the PR can be reviewed now. I edited the OP to detail what's in there.
I am available on #synapse-dev too if there are things to discuss.

[azmeuk]

@reivilibre I think all your comments have been addressed now. Most of them have been fixed in the code and I responded to some with new questions.
The implementation have been tested against Keycloak with the keycloak-scim extension.

I am sorry for the many commits, the PR looks like a mess. If it is easier for the review, I can close it and open a new one. Let me know.