Enhance the clarity of the SCIM documentation regarding the various REST API offerings
Issue description
While dealing with SAML/SCIM-related issues, I found the documentation to be quite confusing. I believe that improving the documentation's clarity would greatly benefit users and contributors like myself.
In the SCIM APIdocumentation, it is stated:
GitLab provides an SCIM API that both implements the RFC7644 protocol and provides the
/Users
endpoint. The base URL is/api/scim/v2/groups/:group_path/Users/
.
However, I found that this SCIM API
does not implement the RFC7644 protocol; rather, it is the internal group SCIM API
that implements RFC7644. Additionally, there are references in a few places [1][2] to this SCIM API
as the main SCIM API
, which can be confusing. This SCIM API
is specifically designed for managing SCIM identities within a group context, and it might be more appropriate to refer to it as the group SCIM API
for clarity.
The second thing is The documentation lacks a clear explanation of the distinctions between the SCIM API
and the internal group SCIM API
. It only provides a brief note saying, 'Not to be confused with the internal group SCIM API', without elaborating on their respective functionalities.
Another issue is that the SCIM API
lacks the capability to create an SCIM identity. Instead, the creation of SCIM identities is facilitated through the internal group SCIM API
. It might be more helpful to convey this by suggesting something along the lines of, 'To create SCIM identities, please utilize the internal group SCIM API
, while the SCIM API
is primarily intended for checking/updating/deleting SCIM identities.
Lastly, after creating a group SCIM identity for a user based on the group SCIM settings, the SCIM identity isn't visible on the group page. Instead, it can only be found on the admin user page. While this behavior is acceptable, it would be helpful to include this information in the documentation for clarity.
Related issues
Allow Group owners to delete user's SCIM identities via API
Reference
[1]. https://docs.gitlab.com/ee/development/internal_api/index.html#group-scim-api
[2]. https://docs.gitlab.com/ee/development/internal_api/index.html#instance-scim-api