Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/catalyst/moodle-local_user_provisioning

SCIM plugin for user provisioning
https://github.com/catalyst/moodle-local_user_provisioning

Last synced: 3 days ago
JSON representation

SCIM plugin for user provisioning

Host: GitHub
URL: https://github.com/catalyst/moodle-local_user_provisioning
Owner: catalyst
Created: 2022-12-03T00:42:42.000Z (almost 2 years ago)
Default Branch: MOODLE_39_STABLE
Last Pushed: 2022-12-03T01:48:49.000Z (almost 2 years ago)
Last Synced: 2023-04-18T23:29:58.925Z (over 1 year ago)
Language: PHP
Size: 198 KB
Stars: 2
Watchers: 17
Forks: 0
Open Issues: 4
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# SCIM 2.0 compliant user provisioning plugin for Moodle

This plugin makes use of 3rd party AltoRouter class for routing the SCIM endpoints (https://github.com/dannyvankooten/AltoRouter)

## How to use

### Add Client identifier:

1. Go to *Site Administration > Server > OAuth provider settings*

2. Click *Add new client*

3. Fill in the form. Your Client Identifier and Client Secret (which will be given later) will be used for you to authenticate. The Redirect URL is not used for this plugin as we using `client_credentials` as the authorization grant type.

* Client identifier: must be same as set in the Organisation short name for the Portal organisation.
e.g. If we are creating a Client secret key for Organisation `MSI Reproductive Choices`, the Client identifier will be `portal-61`
* Redirect URL: is not in use and can be set to N/A
* Grant Types: should be set to `client_credentials`
* Scope: should be set to `SCIMv2`
* User ID: should be set to `0`

### The URL for Azure AD user provisioning is:
`https://{siteurl}/local/user_provisioning/scim/rest.php/v2`

The client will have to create two Custom extention attribues for `Team` and `Auth`

### Field mapping of Moodle to Azure AD are as follows:

* idnumber : id (Azure AD - unique identifier)
* Username : userName
* Firstname : name.givenName
* Lastname : name.familyName
* Email address : emails.value (Type = Work AND primary = True)
* Alternate name : displayName
* Preferred language : preferredLanguage
* City : addresses.locality (Type = Work AND primary = True)
* Country : addresses.country (Type = Work AND primary = True)
* Position : title
* Suspended : active
* Manager : urn:ietf:params:scim:schemas:extension:enterprise:2.0:User manager.value
* Department : urn:ietf:params:scim:schemas:extension:enterprise:2.0:User department
* Authentication : urn:ietf:params:scim:schemas:extension:CustomExtension:2.0:User auth
* Team : urn:ietf:params:scim:schemas:extension:CustomExtension:2.0:User team

Schemas endpoint provides a fair representation of Azure AD fields.

### Generate a Long-lived bearer token:

### Valid end points for this API are:

#### `/token` - To validate / generate a token using the Client identifier and Client secret.

curl https://{siteurl}/local/user_provisioning/scim/rest.php/v2/token -d 'grant_type=client_credentials&client_id=&client_secret='

Where CLIENT_ID is the Client identifier and the CLIENT_SECRET is the key generated when adding a new client as part of `Add Client identifier`

#### `/ServiceProviderConfig` - To view the SCIM service provider config.

curl --location --request GET 'https://{SITE_URL}/local/user_provisioning/scim/rest.php/v2/ServiceProviderConfig' \
--header 'Authorization: Bearer {BEARER_TOKEN}'

#### /Schemas` - To view the SCIM schemas that are used. Append following to view the individual User, Enterprise and Custom extention schema:

* urn:ietf:params:scim:schemas:core:2.0:User
* urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
* urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User

curl --location --request GET 'https://{SITE_URL}/local/user_provisioning/scim/rest.php/v2/Schemas' \
--header 'Authorization: Bearer {BEARER_TOKEN}'

#### `/Users?filters={SEARCH_CRITERIA}` - GET request to fetch a given user's data

curl --location --request POST 'https://{SITE_URL}/local/user_provisioning/scim/rest.php/v2/Users?filter={SEARCH_CRITERIA}' \
--header 'Authorization: Bearer {BEARER_TOKEN}'

Supported SEARCH_CRITERIA fields are:
userName, name.familyName, name.givenName and emails.

Supported SCIM filter types are:
eq (equal) Ee.g. filter=userName+eq+"[email protected]"
neq (Not Equal) Ee.g. filter=userName+neq+"[email protected]"
co (Contains) e.g. filter=userName+co+"[email protected]"
sw (Starts With) e.g. filter=userName+sw+"[email protected]"
ew (Ends With) e.g. filter=userName+ew+"[email protected]"

#### `/Users/{USER_ID}` - GET request to fetch a given user's data

curl --location --request POST 'https://{SITE_URL}/local/user_provisioning/scim/rest.php/v2/Users' \
--header 'Authorization: Bearer {BEARER_TOKEN}'

#### `/Users` - POST request to create / provision a new user.

curl --location --request POST 'https://{SITE_URL}/local/user_provisioning/scim/rest.php/v2/Users' \
--header 'Authorization: Bearer {BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "XXXXXXXX",
"userName": "[email protected]",
"active": true,
"addresses": [{
"primary": true,
"type": "work",
"country": "United Kingdom",
"locality": "Brighton"
}],
"displayName": "Catalyst Admin",
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]"
}],
"name": {
"familyName": "Catalyst",
"givenName": "Admin"
},
"title": "Site Administrator",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "Internet Technologist",
"manager": {
"value": ""
}
},
"urn:ietf:params:scim:schemas:extension:CustomExtension:2.0:User": {
"auth": "saml2",
"team": "IT"
}
}'

#### `/Users` - PATCH request to update given user's data.

curl --location --request PATCH 'https://{SITE_URL}/local/user_provisioning/scim/rest.php/v2/Users' \
--header 'Authorization: Bearer {BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Add",
"path": "displayName",
"value": "Catalyst Admin"
},
{
"op": "Add",
"path": "emails[type eq \"work\"].value",
"value": "[email protected]"
},
{
"op": "Replace",
"path": "name.givenName",
"value": "Admin"
},
{
"op": "Replace",
"path": "name.familyName",
"value": "Catalyst"
}
]
}'