Open fflorent opened 3 weeks ago
Thanks @hexaltation for you feedback!
Thanks for this huge job. I think It could be great to have a documentation/scim.md file documenting at least :
* What part of the SCIM RFCs are not yet implemented, * What part of the RFCs are "adapted" to work with grist current logic
It could be a huge time saver for administrators of instances when doing the interconnection.
I am rather planing on documenting the API in the grist-help
repository and probably add a new page to explain how to setup SCIM and what is currently supported.
Context
As an IT asset administrator, I can create account of my users using a centralized solution like an SSO so they can log on Grist. It's quite convenient because I don't have to worry about creating accounts specifically for them.
Also Grist handles the update of Users when reconnect.
There are things the administrator cannot do though:
owners of an team site
);Proposed solution
SCIM is a standard proposed by the IETF through RFC7644 and RFC7643 which aims to through a simple Rest API provide solution for the above use cases.
Here is the abstract of the RFC7644 which introduces SCIM:
This PR provides the implementation of SCIM for Users Resources (Group will come in a future PR), and supports:
POST /Users/
,PUT /Users/:id
,GET /Users/
,GET /Users/:id
andDELETE /Users/:id
)./Schemas
,/ServiceProviderConfig
,/ResourceTypes
endpoints;/Me
endpoint (it takes advantage of theid
you returned in the authentication middleware);POST /Bulk
endpointPOST /Resources/.search
by using the Filters (actually to use them, you must have to fetch all the Resources from the DB, the filtering is done in JS, which is probably fine for small projects, I would just be cautious when using big databases + an ORM);PATCH /Resources/:id
endpoint! It reads a resource using the egress method, applies the asked changes, and calls the ingress method to update the record ;To do that, I take advantage of two libraries: scimmy and scimmy-routers. Scimmy is lightweight (0 dependency), and scimmy-routers will also be dependency-free be in a future version (reported in that issue and already fixed).
Two variables are introduced:
GRIST_ENABLE_SCIM
to let the administrator enable the scim API (defaults to false);GRIST_SCIM_EMAIL
to let the administrator specify a user that is allowed, they are granted rights to do any operation using SCIM (just like the administrators ofGRIST_DEFAULT_EMAIL
andGRIST_SUPPORT_EMAIL
);Assumption regarding the SCIM implementation
userName
corresponds to the normalized email (logins.email
), the SCIMemails
corresponds to thedisplayEmail
;How to test manually?
I can document the API in grist-help upon request (otherwise I will do that after this PR is merged).
You may:
GRIST_ENABLE_SCIM
:I described some examples of the SCIM API usage here (they need to be adaptated for the context of Grist): https://github.com/scimmyjs/scimmy-routers/blob/8ffa2221b542054c3f0cfb765ea6957f29ebe5e1/example/README.md#play-with-the-scim-server
Limitations of the current implementation
GRIST_DEFAULT_EMAIL
or the support account) or the user withGRIST_SCIM_EMAIL
are allowed to make operations on resources (other user are limited to use/Me
)./Me
endpoint implementation seems partial (issue);any
types or some casts until that is fixed (issue and issue);Content-Type
must beapplication/scim+json
, currentlyapplication/json
is not supported (will be fixed in the next scimmy-routers release)Related issues
It partly implements #870 (Users resource only for now).
Has this been tested?