[API] Ajouter un endpoint SCIM pour la gestions des utilisateurs
Introduction
Afin de permettre à la boite d'être un service provider SCIM, il faut dans un premier temps ajouter le support de la création des utilisateurs On pourrait se baser sur le endpoint /createuser mais ce endpoint n'est pas au format SCIM. Il serait donc intéressant d'ajouter un endpoint dédié à SCIM afin de faire une bascule en douceur des clients.
Endpoint
Un endpoint SCIM doit avoir le format suivant :
- https://example.com/{v}/{resource} avec {v} = v2 (la version actuelle de SCIM) et {resource} = Users, et il faudrait pouvoir le différencier des autres API pour assurer, donc on aurait https://example.com/scim/v2/Users comme endpoint pour la gestion des utilisateurs
Méthodes
Ensuite pour le CRUD, cela se fait en fonction des requêtes HTTP :
- Create: POST https://example.com/{v}/{resource}
- Read: GET https://example.com/{v}/{resource}/{id}
- Replace: PUT https://example.com/{v}/{resource}/{id}
- Delete: DELETE https://example.com/{v}/{resource}/{id}
- Update: PATCH https://example.com/{v}/{resource}/{id}
- Search: GET https://example.com/{v}/{resource}?filter={attribute}{op}{value}&sortBy={attributeName}&sortOrder={ascending|descending}
Le Search n'est peut être pas le plus utile pour commencer, on peut donc mettre en place le POST, GET, PUT, DELETE et PATCH
Pour plus d'informations sur les endpoints et les methodes HTTP : https://datatracker.ietf.org/doc/html/rfc7644#section-3.2
Données
Pour le format de données, voici ce qu'on a avec l'API createuser :
{
"username": "tpayen",
"email": "thomas.payen@i-carre.net",
"firstname": "Thomas",
"lastname": "Payen",
"structure": "Ministère de la Transition Écologique"
}
Pour transformer cela en format SCIM il faut avoir :
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "2819c223-7f76-453a-919d-413861904646",
"externalId": "tpayen",
"meta": {
"resourceType": "User",
"created": "2011-08-01T18:29:49.793Z",
"lastModified": "2011-08-01T18:29:49.793Z",
"location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version": "W\/\"f250dd84f0671c3\""
},
"name":{
"familyName": "Payen",
"givenName": "Thomas"
},
"userName": "tpayen",
"emails":[
{
"value": "thomas.payen@i-carre.net",
"type": "work",
"primary": true
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"organization": "Ministère de la Transition Écologique"
}
}
Pour avoir plus d'informations sur chacun des champs, cela se passe dans la RFC : https://datatracker.ietf.org/doc/html/rfc7643#section-3.1
Authentification
Pour simplifier on peut se baser sur la même authentification que l'API createuser via l'API Key
Erreurs
La gestion des erreurs est détaillée dans la RFC 7644. Par exemple, pour une action (read, update, delete) sur un utilisateur non trouvé, voici le format de retour
HTTP/1.1 404 Not Found
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"status": "404"
}
Compléments
Le content type à utiliser est Content-Type: application/scim+json