Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

When the /Me endpoint is implemented, PUT / POST / PATCH / DELETE should be supported #27

Closed
fflorent opened this issue Sep 6, 2024 · 4 comments

Comments

@fflorent
Copy link
Contributor

fflorent commented Sep 6, 2024

Quoting the RFC7644 on page 10:

Resource Endpoint         Operations             Description
 -------- ---------------- ---------------------- --------------------
  [...]

   Self     /Me              GET, POST, PUT, PATCH, Alias for operations
                             DELETE (Section 3.11)  against a resource
                                                    mapped to an
                                                    authenticated
                                                    subject (e.g.,
                                                    User).

I guess it would be fine to propose these operations. What do you think?

I can take a look at it when I have time if you want to.

@fflorent
Copy link
Contributor Author

fflorent commented Sep 6, 2024

Something that is unclear to me at the moment is this paragraph in section 3.11:

When using the SCIM Create Resource command (HTTP POST) with the
"/Me" alias, the desired resourceType being created is at the
discretion of the service provider, based on the authenticated
subject (if not anonymous) making the request and any request body
attributes (e.g., "schemas"). See Section 7.6 for information on
security considerations related to this operation.

I understand that submitting a POST /Me request should trigger a resource creation. If that makes sense for an anonymous user, it looks awkward to me when authenticated the user doesn't work on themselves… which is inconsistent regarding the semantic). Maybe differ this subject in another issue and return a 501 (NOT IMPLEMENTED) status code so we can at least implement the rest?

@sleelin
Copy link
Collaborator

sleelin commented Sep 9, 2024

Hi @fflorent,
I'm transferring this issue over to the scimmy-routers repository, and will address it there, as this is where SCIM routes are actually defined.

Thanks,
Sam

@sleelin sleelin transferred this issue from scimmyjs/scimmy Sep 9, 2024
jordigh added a commit to gristlabs/grist-core that referenced this issue Dec 4, 2024
## 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:
 - assign users to Groups (like the `owners of an team site`);
 - change immediately user information; 
 - delete the user when they are removed from the SSO;
 - get the list of users or groups in a normalized way;
 - ...


## Proposed solution

SCIM is a standard proposed by the IETF through [RFC7644](https://www.rfc-editor.org/rfc/rfc7644) and [RFC7643](https://www.rfc-editor.org/rfc/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:
   

> The System for Cross-domain Identity Management (SCIM) specification is an HTTP-based protocol that makes managing identities in multi-domain scenarios easier to support via a standardized service.
>  Examples include, but are not limited to, enterprise-to-cloud service providers and inter-cloud scenarios.  The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models.  SCIM's intent is to reduce the cost and complexity of user management operations by providing a common user schema, an extension model, and a service protocol defined by this document.

This PR provides the implementation of SCIM for Users Resources (Group will come in a future PR), and supports:

- All the basic actions (`POST /Users/`, `PUT /Users/:id`, `GET /Users/`, `GET /Users/:id` and `DELETE /Users/:id`).
- The `/Schemas`, `/ServiceProviderConfig`, `/ResourceTypes` endpoints;
- The `/Me` endpoint (it takes advantage of the `id` you returned in the authentication middleware);
- The `POST /Bulk` endpoint
- The `POST /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);
- There are some error utilities to help you;
- The `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 ;
- The pagination

To do that, I take advantage of two libraries: [scimmy](https://github.com/scimmyjs/scimmy) and [scimmy-routers](https://github.com/scimmyjs/scimmy-routers). Scimmy is lightweight (0 dependency), and scimmy-routers will also be dependency-free be in a future version (reported in that [issue](scimmyjs/scimmy-routers#20) 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 of `GRIST_DEFAULT_EMAIL` and `GRIST_SUPPORT_EMAIL`);

## Assumption regarding the SCIM implementation

- the ID is the technical ID in the database;
- SCIM's `userName` corresponds to the normalized email (`logins.email`), the SCIM `emails` corresponds to the `displayEmail`;
- I don't allow more than an email to be passed (as the Grist code requires currently IIRC);
- Anonymous users cannot call any SCIM endpoint;
- Authenticated non-admin and non-GRIST_SCIM_EMAIL users can only request [these endpoints](https://github.com/gristlabs/grist-core/pull/1199/files#diff-718d3e2193a1261bcf5cd6f6bba04e22bec1b0c4b162c6adbf0ae4847f107912R10);

## 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:
1. run a local Grist server setting either the GRIST_DEFAULT_EMAIL, GRIST_SUPPORT_EMAIL or GRIST_SCIM_EMAIL env variable without omitting to enable SCIM using `GRIST_ENABLE_SCIM`:
```bash
GRIST_SCIM_EMAIL="[email protected]" GRIST_ENABLE_SCIM=1 yarn start
```
2. Generate a bearer for [email protected]
3. then you may start using SCIM:
```bash
$ export BEARER=<paste the bearer here>
$ curl -H 'Content-Type: application/scim+json' -H "Authorization: Bearer $BEARER" -X POST -d '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], "sortBy": "userName", "sortOrder": "descending"}' https://localhost:8484/api/scim/v2/Users/.search
```

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

 - The user bearer not renewed automatically, so it does not comply with the request of limiting their lifetime ([source](https://www.rfc-editor.org/rfc/rfc7644#section-7.4));
 - Only an administrator (with the `GRIST_DEFAULT_EMAIL` or the support account) or the user with `GRIST_SCIM_EMAIL` are allowed to make operations on resources (other user are limited to use `/Me`).
 - A dedicated account (like `GRIST_SCIM_EMAIL`) is required to have access to the endpoints, which should have their API key generated. I considered instead having a bearer directly set in an env variable, but I rejected the idea because it would [have been rejected by the Authorizer](https://github.com/gristlabs/grist-core/blob/30e2cc47d2916410579421fe8af21b609a73f468/app/server/lib/Authorizer.ts#L177-L182). 
 - The `/Me` endpoint implementation seems partial ([issue](scimmyjs/scimmy-routers#27));
 - I forgot to add tests for the pagination… I am noting to do that;
 - The SCIMMY and scimmy-routers libraries lack of typing support, so you may see many `any` types or some casts until that is fixed ([issue](scimmyjs/scimmy#45) and [issue](scimmyjs/scimmy-routers#24));
 - [now fixed] The `Content-Type` must be `application/scim+json`, currently `application/json` is not supported ([will be fixed in the next scimmy-routers release](scimmyjs/scimmy-routers#22))

## Documentation

I opened this PR in draft to start documenting SCIM: gristlabs/grist-help#434

It can be previewed here:
 - the documentation (including an intro): https://deploy-preview-434--grist-help-preview.netlify.app/install/scim/
 - the API reference: https://deploy-preview-434--grist-help-preview.netlify.app/api/#tag/scim

## Related issues

It partly implements #870 (Users resource only for now).

## Has this been tested?

<!-- Put an `x` in the box that applies: -->

- [x] 👍 yes, I added tests to the test suite
- [ ] 💭 no, because this PR is a draft and still needs work
- [ ] 🙅 no, because this is not relevant here
- [ ] 🙋 no, because I need help <!-- Detail how we can help you -->

## Original commit messages.

* WIP

* SCIM: Implement egress + tests

* Implement ingress

* Add tests

* SCIM: Implement DELETE

* More tests and cleanups

* Rebase fix + check GRIST_SCIM_USER

* Add GRIST_ENABLE_SCIM env variable

* Move logic for Users to its own controller

* An unknown error should return a 500

* Add a test for pagination

* Add tests for the new UsersManager methods

* Document methods of the controller

* Rename ex → err in catch block

* Bump Scimmy and Scimmy-Routers

* Log errors

* Only warn when the userName differ from the primary email

* Rename overrideUser → overwriteUser

* Use full path for import

* Improve user deletion test description

Co-authored-by: jordigh <[email protected]>

* Improve error message for anonymous users

Co-authored-by: jordigh <[email protected]>

* Fix styling issue

* Disallow deleting technical users

* Disallow technical user modifications

* Update FIXME in ScimUserController

Co-authored-by: jordigh <[email protected]>

* rename "technical user" to "system user"

* Document SCIM feature flag in the README

---------

Co-authored-by: jordigh <[email protected]>
@sleelin
Copy link
Collaborator

sleelin commented Dec 17, 2024

Hi @fflorent, apologies for the delay in properly addressing this!
In RFC7644§3.11 the /Me endpoint is defined as being one of: not supported, redirecting to the canonical resource location, or processing the requests directly.

The current approach taken by scimmy-routers is to blur this definition slightly and process GET requests directly, whilst responding with 501 Not Implemented for POST/PUT/PATCH/DELETE requests.

In theory it should be straightforward to implement handling for the other requests, however it raises a whole plethora of other considerations that are very much out of scope of scimmy and scimmy-routers, including:

  • Potentially/inadvertently facilitating undesired anonymous user creation (POST),
  • Possible authenticated user privilege escalation (PUT/PATCH)
  • Accidental deletion of authenticated user (DELETE)

Granted these issues would only exist for poorly secured implementations (i.e. when there's no verification that a given request is authorised before it goes ahead), it still seemed prudent to minimise this risk. I suppose it would be possible to implement the remaining methods behind a configuration value (something like directMe or completeMe or similar?) that is disabled by default, so as not to introduce these issues unless explicitly opted into?

Let me know what you think.

Thanks,
Sam

fflorent added a commit to fflorent/grist-help that referenced this issue Dec 18, 2024
@fflorent
Copy link
Contributor Author

Hi @sleelin,

My turn for apologizing answering you with delays.

Thank you for your feedback. Indeed, there are questions to address before enabling these endpoints.

Your point of view totally makes sense. My issue was more in a "comply with the standard" mindset rather than asking for answering a particular need.

I close this ticket, regarding my need. Feel free to reopen it if you would like this question remain open.

Thank you for your valuable work!
Florent

fflorent added a commit to fflorent/grist-core that referenced this issue Jan 12, 2025
fflorent added a commit to fflorent/grist-core that referenced this issue Jan 17, 2025
fflorent added a commit to fflorent/grist-core that referenced this issue Jan 31, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

No branches or pull requests

2 participants