libre.sh/scimserviceprovider
1
0
Fork 0
Code Issues 10 Pull requests Projects Releases Packages Wiki Activity Actions

doc: update README

Browse source
This commit is contained in:
Hugo Renard 2024-02-06 18:04:49 +01:00
parent 362ab2b4c1
commit a6fa19ca53
Signed by: hougo
GPG key ID: 3A285FD470209C59
1 changed files with 25 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
README.md
View file

@ -4,105 +4,49 @@ This app allows to provision users and groups in Nextcloud from a scim client. I
You can see the [video](https://hot-objects.liiib.re/meet-liiib-re-recordings/pair_2022-05-02-15-40-37.mp4) that shows how it works.
---
## Installation
## Table of content
Like any other app, it's available on Nextcloud's [app store](https://apps.nextcloud.com/apps/scimserviceprovider).
1. [How to use](#how-to-use)
1. [Installation](#installation)
2. [Authentication](#authentication)
1. [Basic authentication](#basic-authentication)
2. [Bearer token authentication](#bearer-token-authentication)
1. [JWT generation (for admins only!)](#jwt-generation-for-admins-only)
2. [Usage of the JWT](#usage-of-the-jwt)
2. [Use with Keycloak](#use-with-keycloak)
3. [Use with AzureAD](#use-with-azuread)
4. [Running tests](#running-tests)
5. [Todo](#todo)
6. [Disclaimer](#disclaimer)
7. [NextGov Hackathon](#nextgov-hackathon)
## Authentication
---
Basic and bearer authentication are supported. For now, only admin users are authorized to access SCIM APIs.
## How to use
### Basic authentication
### Installation
We plan to publish on the Nextcloud app store, but in the mean time you can use instructions bellow.
You just have to generate an app password in `/settings/user/security`.
```
cd apps
wget https://lab.libreho.st/libre.sh/scim/nextcloud-scim/-/archive/main/nextcloud-scim-main.zip
unzip nextcloud-scim-main.zip
rm nextcloud-scim-main.zip
rm -rf scimserviceprovider
mv nextcloud-scim-main scimserviceprovider
### Bearer authentication
It requires a JWT secret, to be enabled.
```shell
php occ config:app:set scimserviceprovider jwt-secret --value="CHANGE_ME"
```
### Authentication
Currently, this app supports both Basic authentication, as well as Bearer token authentication via JWTs. One can change between these two authentication modes by setting the `auth_type` config parameter in the config file under `/lib/Config/config.php` to either `basic` or `bearer`.
#### Basic authentication
In order to authenticate via Basic auth, send SCIM requests to the SCIM endpoints of the following form:
> `http://<path-to-nextcloud>/index.php/apps/scimserviceprovider/<Resource>`
where `<Resource>` designates a SCIM resource, such as `Users` or `Groups`.
For example:
```
$ curl http://<path-to-nextcloud>/index.php/apps/scimserviceprovider/<Resource> -u someusername:pass123 -H 'Content-Type: application/scim+json'
Then you should generate a JWT signed with this secret and with `sub` in the payload referring to an existing username. ([Handy CLI tool](https://github.com/mike-engel/jwt-cli))
```shell
jwt encode --secret "CHANGE_ME" '{"sub":"admin"}'
```
#### Bearer token authentication
In order to authenticate via a Bearer token, send SCIM requests to the SCIM endpoints of the following form:
> `http://<path-to-nextcloud>/index.php/apps/scimserviceprovider/bearer/<Resource>`
where `<Resource>` designates a SCIM resource, such as `Users` or `Groups`. Also, make sure to provide the Bearer token in the `Authorization` header of the SCIM HTTP request.
##### JWT generation (for admins only!)
Before providing the token, though, you'd need to obtain one. This is done with the help of a script which can generate JWTs and which is part of `scim-server-php`, the SCIM library by audriga, used as a dependency in this app.
A JWT can be generated as follows:
## Usage
```
$ vendor/audriga/scim-opf/bin/generate_jwt.php --username someusername --secret topsecret123
$ curl http://<path-to-nextcloud>/index.php/apps/scimserviceprovider/<Resource> -H 'Authorization: <Auth>' -H 'Content-Type: application/scim+json'
```
where
Where `<Resource>` designates a SCIM resource, such as `Users` or `Groups`.
- `--username` is the username of the user that you want to generate a JWT
- `--secret` is the secret key set in the `jwt` config parameter in the config file under `/lib/Config/config.php`, used for signing the JWT
**Note:** the generated JWT has a claim, called `user` which contains the username that was passed to the JWT generation script and which is later also used for performing the actual authentication check in Nextcloud. For example, it could look like something like this: `{"user":"someusername"}.`
##### Usage of the JWT
A sample usage of JWT authentication as an example:
```
$ curl http://<path-to-nextcloud>/index.php/apps/scimserviceprovider/<Resource> -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYWRtaW4ifQ.Oetm7xvhkYbiItRiqNx-z7LZ6ZkmDe1z_95igbPUSjA' -H 'Content-Type: application/scim+json'
```
## Use with Keycloak
### With Keycloak
You can use with the [SCIM plugin we developped for keycloak](https://lab.libreho.st/libre.sh/scim/keycloak-scim).
## Use with AzureAD
### With AzureAD
You can provision users from AzureAD to Nextcloud with this app. For this, you need to do the following:
- Enable Bearer token authentication via JWTs (see [Authentication](#authentication))
- Generate a JWT (see [JWT Generation](#jwt-generation-for-admins-only)) and provide it to AzureAD
- Finally, point AzureAD to `https://<path-to-nextcloud>/index.php/apps/scimserviceprovider/bearer`
You can provision users from AzureAD to Nextcloud with this app. For this, you need to setup [Bearer authentication](#bearer-authentication).
## Running tests
To run the test, you can use [insomnia UI](https://docs.insomnia.rest).
![screenshot insomnia ui](./screenshots/insomnia.png)
For CI, there is still [a bug](https://github.com/Kong/insomnia/issues/4747) we need to find a fix.
Broken.
## Todo
@ -112,23 +56,14 @@ For CI, there is still [a bug](https://github.com/Kong/insomnia/issues/4747) we
- [ ] ExternalID
- [ ] Groups - [waiting for feedback](https://help.nextcloud.com/t/add-metadata-to-groups/139271)
- [ ] json exceptions
- [ ] group member removal
- [ ] pagination
- [x] group member removal
- [x] pagination
- [ ] CI/CD
- [ ] Lint cs:check
- [ ] test psalm
- [ ] test insomnia
- [ ] publish app on app store
- [ ] Allow for simultaneous usage of basic auth and bearer token auth (see **Authentication TODOs / Open issues**)
### Authentication TODOs / Open issues
#### Support for simultaneously using basic auth and bearer token auth in parallel
Solution idea:
- Instead of having two different sets of endpoints which are disjunct from each other for supporting both auth types, one could add an authentication middleware which intercepts requests and checks the `Authorization` header's contents
- Depending on whether the header has as first part of its value the string `Basic` or `Bearer`, the middleware can decide which authentication logic to call for performing the authentication with the provided authentication credentials
- In case of `Bearer`, the current implementation of bearer token authentication via JWTs can be used
- In case of `Basic`, one could take a closer look at how Nextcloud performs basic authentication for API endpoints and possibly make use of methods like [checkPassword](https://github.com/nextcloud/server/blob/master/lib/private/User/Manager.php#L237) from the [Manager](https://github.com/nextcloud/server/blob/master/lib/private/User/Manager.php) class for Nextcloud users
- [x] publish app on app store
- [x] Allow for simultaneous usage of basic auth and bearer token auth (see **Authentication TODOs / Open issues**)
## Disclaimer
This app relies on the fixes, being introduced to Nextcloud in [PR #34172](https://github.com/nextcloud/server/pull/34172), since Nextcloud can't properly handle the `Content-Type` header value for SCIM (`application/scim+json`) otherwise. In the meantime until this PR is merged, SCIM clients interacting with this app might need to resort to using the standard value of `application/json` instead.