Utilisation de l'API SCIM de Cato pour les applications SCIM personnalisées

Cet article décrit comment utiliser l'API SCIM de Cato pour le provisionnement des utilisateurs et des groupes d'utilisateurs avec un fournisseur d'identité (IdP).

Pour plus d'informations sur les applications SCIM personnalisées dans le locataire IdP, voir Créer une application SCIM personnalisée pour un IdP.

Application SCIM Cato personnalisée

Pour utiliser une application SCIM personnalisée pour provisionner les utilisateurs et les groupes d'utilisateurs sur votre compte Cato, créez l'application dans l'application de gestion Cato (CMA). De plus, vous devez mapper les attributs SCIM de Cato aux attributs de votre IdP.

Créer une application SCIM personnalisée dans le CMA

Pour utiliser l'API SCIM, vous devez d'abord créer une application SCIM personnalisée dans le CMA. Cette application vous permet d'intégrer votre fournisseur d'identité (IdP) à la plateforme Cato.

Pour créer une application SCIM personnalisée dans le CMA :

1. Dans le menu de navigation, sélectionnez Accès > Services d'annuaire.

2. Sous l'onglet SCIM, cliquez sur Nouveau.

3. Entrez un nom pour l'application.

4. Sous Fournisseur, sélectionnez Personnalisé.

5. Cliquez sur Générer un jeton et copiez la valeur ; elle ne sera plus disponible après l'enregistrement et vous devrez créer un nouveau jeton. 

6. Cliquez sur Sauvegarder.

7. Lors de l'appel des points de terminaison de l'API SCIM décrits ci-dessous, vous aurez besoin des valeurs suivantes pour vous authentifier :

   • URL de base SCIM : Utilisée comme chemin de base pour les requêtes API

   • Jeton d'accès : Utilisé pour l'authentification des requêtes API

Attributs SCIM de Cato

Voici les attributs SCIM pour les utilisateurs et groupes d'utilisateurs Cato que vous devez mapper aux attributs correspondants de l'IdP.

Comprendre l'API SCIM de Cato

Authentification à l'API SCIM de Cato

Les clients s'authentifient à l'API SCIM en utilisant l'authentification par jeton d'accès, comme défini par le RFC 6750. Toutes les requêtes API doivent inclure les en-têtes HTTP suivants :

Authorization: Bearer <access_token>
Content-Type: application/json

Vous pouvez obtenir le jeton d'accès depuis l'application de gestion Cato.

Chemin de base pour les points d'extrémité SCIM

Tous les points d'extrémité API SCIM utilisent le chemin de base suivant :

/scim/v2/{accountId}/{sourceId}

Paramètres de chemin : 

• accountId (string): Identifiant unique de votre compte locataire Cato

• sourceId (integer): Identifiant assigné par Cato pour représenter de manière unique une intégration IdP spécifique

Ces paramètres sont requis dans toutes les requêtes mais sont omis des chemins de points d'extrémité individuels dans cet article pour la brièveté.

Gestion des utilisateurs

Cette section décrit comment créer, mettre à jour, supprimer et récupérer les entités utilisateur SCIM en utilisant l'API SCIM de Cato.

Créer un utilisateur

Méthode HTTP :POST /Utilisateurs 

Champs requis : 

• userName (string): Nom d'utilisateur unique (par exemple, adresse e-mail)

• externalId (string): Identifiant externe provenant de l'IdP

• active (boolean): Doit être true pour activer l'utilisateur

Remarque :id est renvoyé par le service SCIM et doit être utilisé dans les appels API suivants. externalId est optionnel et ne peut pas être utilisé dans les chemins API.

Réponse : 

• Statut : 201 Créé

Erreurs : 

• 400 Bad Request: Schéma invalide

• 401 Non autorisé 

• 409 Conflit: Dupliquer Nom d'utilisateur ou identifiant externe

Mettre à jour un utilisateur

PUT

Méthode HTTP :PUT /Utilisateurs/{id} 

Champ requis : 

• id: ID SCIM interne de Cato

Réponse : 

• Status: 200 OK

Erreurs : 

• 401 Non autorisé 

• 404 Non trouvé 

• 409 Conflit: Dupliquer Nom d'utilisateur ou identifiant externe

PATCH

Méthode HTTP :PATCH /Utilisateurs/{id} 

Réponse : 

• Status: 200 OK

Erreurs : 

• 400 Bad Request: Schéma invalide ou syntaxe de patch invalide

• 401 Non autorisé 

• 404 Non trouvé 

• 409 Conflit: Identifiants en double

Supprimer un utilisateur

Méthode HTTP :DELETE /Users/{id}

Réponse :

• État : 204 No Content

Il s'agit d'une suppression douce. L'utilisateur reste dans le système mais n'est pas renvoyé dans les recherches.

Obtenir un utilisateur par ID

Méthode HTTP :GET /Users/{id}

Réponse :

• Status: 200 OK

Erreurs :

• 401 Non autorisé

• 404 Non trouvé

Rechercher des utilisateurs

Méthode HTTP :GET /Users

Paramètres de requête :

• filter: Requête pour filtrer les utilisateurs (par exemple, userName eq "user@domain.com")

• count (optionnel)

• startIndex (optionnel)

Filtres pris en charge :

• Seul eq est pris en charge

• Attributs pris en charge : userName, email, givenName, familyName

• Les filtres composés sont pris en charge uniquement dans ce format :

  filter=emails[type eq "work"] et email eq "bob@cato.com"

Réponse :

• Status: 200 OK

Erreurs :

• 401 Non autorisé

Gestion des Groupes

Cette section explique comment utiliser l'API SCIM pour créer, mettre à jour, supprimer et récupérer des entités de groupe dans votre environnement Cato.

Créer un Groupe

Méthode HTTP :POST /Groups

Réponse :

• Statut : 201 Créé

Erreurs :

• 401 Non autorisé

• 409 Conflit : displayName ou ID d'objet en double

Mettre à jour un Groupe

PUT

Méthode HTTP :PUT /Groups/{id}

Réponse :

• Status: 200 OK

Erreurs :

• 401 Non autorisé

• 404 Non trouvé

• 409 Conflit

PATCH

Méthode HTTP :PATCH /Groups/{id}

Chemins de Patch pris en charge :

• displayName

• membres

Réponse :

• Status: 200 OK

Erreurs :

• 400 Bad Request: Schéma invalide ou syntaxe de patch invalide

• 401 Non autorisé

• 404 Non trouvé

• 409 Conflit

Supprimer un Groupe

Méthode HTTP :DELETE /Groups/{id}

Réponse :

• État : 204 No Content

Important :

Il s'agit d'une suppression définitive. Le groupe est supprimé définitivement.

Récupérer un Groupe par ID

Méthode HTTP :GET /Groups/{id}

Paramètres de requête optionnels :

• excludeAttributes (par exemple, membres)

Réponse :

• Status: 200 OK

Erreurs :

• 401 Non autorisé

• 404 Non trouvé

Rechercher des Groupes

Méthode HTTP :GET /Groups

Paramètres de requête :

• filter : Seul displayName eq "Nom du Groupe" est pris en charge

• count (optionnel)

• startIndex (optionnel)

Les filtres composés ou opérateurs non pris en charge renvoient tous les groupes sans filtrage.

Réponse :

• Status: 200 OK

Erreurs :

• 401 Non autorisé

Remarque

Comportement du champ id lors de la Création

• Le champ id est optionnel dans les requêtes de création d'utilisateur et de groupe.

• S'il est omis, le service SCIM génère un id unique.

• Utilisez toujours la valeur id retournée dans les appels API suivants.

Important :

Évitez d'utiliser des IDs générés par le client sauf si nécessaire. L'id SCIM est l'identifiant d'autorité.

Comportement de Suppression

• Suppression d'utilisateur via DELETE /Users/{id} effectue une suppression douce en réglant le champ active à false. L'utilisateur est récupérable via GET /Users/{id} mais exclu des résultats de GET /Users.

• Suppression de groupe via DELETE /Groups/{id} effectue une suppression totale. Le groupe est supprimé définitivement.