API SCIM 2.0

Auris implémente le protocole SCIM 2.0 (System for Cross-domain Identity Management) pour le provisioning automatique d’utilisateurs et de groupes. SCIM permet aux fournisseurs d’identité comme Okta, Azure AD (Entra ID), OneLogin et JumpCloud de créer, mettre à jour et désactiver automatiquement les comptes utilisateurs dans Auris lorsque des modifications sont apportées dans l’annuaire de l’IdP.

L’API SCIM suit les spécifications RFC 7643 (Core Schema) et RFC 7644 (Protocol).

Configuration de la Connexion SCIM

Avant que ton IdP puisse provisionner des utilisateurs, tu dois créer une connexion SCIM dans la Console Auris :

Va dans Console > Paramètres > Provisioning SCIM
Clique sur Ajouter une Connexion
Note l’URL Base SCIM et le Token Bearer
Configure ces valeurs dans les paramètres d’intégration SCIM de ton IdP

L’URL base SCIM suit ce format :


https://api.altovar.net/api/scim/v2

Authentification

Tous les endpoints SCIM utilisent l’authentification par Bearer token. Le token est généré lors de la création d’une connexion SCIM dans la Console Auris.


Authorization: Bearer scim_token_here

Les tokens SCIM ont une longue durée de vie et accordent un accès complet au provisioning. Traite-les comme des secrets. Fais pivoter les tokens périodiquement depuis la Console Auris.

Gestion des Connexions

Ces endpoints servent à gérer les connexions SCIM depuis la Console Auris (API admin). Ils ne font pas partie du protocole SCIM lui-même.

GET/api/scim/connectionsRequires: view:scim_connections

Liste toutes les connexions SCIM pour le tenant.

Réponse de succès


{
  "ok": true,
  "data": [
    {
      "id": "scim_conn_abc123",
      "name": "Okta Production",
      "provider": "okta",
      "isActive": true,
      "lastSyncAt": "2025-02-18T09:00:00Z",
      "userCount": 245,
      "groupCount": 12,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

POST/api/scim/connectionsRequires: manage:scim_connections

Crée une nouvelle connexion SCIM. Retourne les détails de la connexion incluant le token Bearer généré. Le token est retourné une seule fois — conserve-le en lieu sûr.

Corps de la requête


{
  "name": "Okta Production",
  "provider": "okta"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "id": "scim_conn_def456",
    "name": "Okta Production",
    "provider": "okta",
    "token": "scim_abc123def456...",
    "baseUrl": "https://api.altovar.net/api/scim/v2",
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Utilisateurs

Lister les Utilisateurs

GET/api/scim/v2/UsersRequires: Token Bearer SCIM

Liste les utilisateurs dans le tenant. Supporte les filtres SCIM, la pagination et la sélection d’attributs. Retourne les utilisateurs au format SCIM Core Schema.

Paramètres de query

Paramètre	Type	Description
`filter`	string	Expression de filtre SCIM (voir Syntaxe de Filtre)
`startIndex`	integer	Index de départ base 1 (défaut : 1)
`count`	integer	Résultats maximum par page (défaut : 20, max : 100)
`sortBy`	string	Attribut pour le tri (ex. `userName`)
`sortOrder`	`ascending` \| `descending`	Direction du tri (défaut : `ascending`)

Réponse de succès


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 245,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "usr_abc123",
      "externalId": "okta_user_001",
      "userName": "[email protected]",
      "name": {
        "givenName": "Alice",
        "familyName": "Martin",
        "formatted": "Alice Martin"
      },
      "displayName": "Alice Martin",
      "emails": [
        { "value": "[email protected]", "type": "work", "primary": true }
      ],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2025-01-15T10:00:00Z",
        "lastModified": "2025-02-18T09:00:00Z",
        "location": "https://api.altovar.net/api/scim/v2/Users/usr_abc123"
      }
    }
  ]
}

Les réponses SCIM utilisent le format schema SCIM (pas l’enveloppe standard de l’API Auris). Les champs schemas, le tableau Resources et l’objet meta sont requis par la spécification SCIM.

Créer un Utilisateur

POST/api/scim/v2/UsersRequires: Token Bearer SCIM

Crée un nouveau compte utilisateur. L’utilisateur est créé à la fois dans la base de données Auris et dans le realm associé à la connexion SCIM. Si externalId est fourni, il est stocké pour de futures réconciliations.

Corps de la requête


{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId": "okta_user_002",
  "userName": "[email protected]",
  "name": {
    "givenName": "Bob",
    "familyName": "Dupont"
  },
  "emails": [
    { "value": "[email protected]", "type": "work", "primary": true }
  ],
  "active": true
}

Mapping des champs SCIM → Auris (par défaut)

Champ SCIM	Champ Auris	Notes
`userName`	`email` / `scimUserName`	Utilisé comme identifiant primaire
`externalId`	`scimExternalId`	Identifiant unique côté IdP
`name.givenName`	`firstName`
`name.familyName`	`lastName`
`emails[primary].value`	`email`	L’email primaire devient l’email Auris
`phoneNumbers[0].value`	`phoneNumber`
`active`	`enabled`

Réponse de succès (HTTP 201) : Représentation complète de l’utilisateur SCIM.

Mise à Jour Partielle (PATCH)

PATCH/api/scim/v2/Users/[id]Requires: Token Bearer SCIM

Met à jour partiellement un utilisateur en utilisant des opérations SCIM PATCH. C’est la méthode de mise à jour la plus couramment utilisée par les IdP. Supporte les opérations add, replace et remove.

Corps de la requête — Désactiver un utilisateur


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

Types d’opérations PATCH

Opération	Description
`add`	Ajoute une nouvelle valeur à un attribut multi-valeur ou définit un attribut à valeur unique
`replace`	Remplace la valeur actuelle d’un attribut
`remove`	Supprime une valeur d’attribut

Supprimer un Utilisateur

DELETE/api/scim/v2/Users/[id]Requires: Token Bearer SCIM

Supprime (désactive) un utilisateur. Dans Auris, la suppression SCIM effectue un soft-delete : l’utilisateur est désactivé et son accès est révoqué, mais l’enregistrement en base de données est conservé à des fins d’audit.

Réponse de succès : HTTP 204 No Content (corps vide, selon la spécification SCIM).

Groupes

Lister les Groupes

GET/api/scim/v2/GroupsRequires: Token Bearer SCIM

Liste les groupes dans le tenant. Les groupes dans Auris correspondent aux rôles. Supporte les filtres SCIM et la pagination.

Réponse de succès


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "role_abc123",
      "displayName": "engineering",
      "members": [
        { "value": "usr_abc123", "display": "[email protected]" }
      ],
      "meta": {
        "resourceType": "Group",
        "created": "2025-01-01T00:00:00Z",
        "lastModified": "2025-02-15T10:00:00Z",
        "location": "https://api.altovar.net/api/scim/v2/Groups/role_abc123"
      }
    }
  ]
}

Mise à Jour Partielle Groupe (PATCH)

PATCH/api/scim/v2/Groups/[id]Requires: Token Bearer SCIM

Met à jour partiellement un groupe en utilisant des opérations SCIM PATCH. Utilisé principalement pour ajouter ou retirer des membres.

Corps de la requête — Ajouter des membres


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "usr_ghi789" },
        { "value": "usr_jkl012" }
      ]
    }
  ]
}

Corps de la requête — Retirer un membre


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"usr_abc123\"]"
    }
  ]
}

Opérations Bulk

POST/api/scim/v2/BulkRequires: Token Bearer SCIM

Exécute plusieurs opérations SCIM en une seule requête. Supporte jusqu’à 100 opérations par requête. Chaque opération est traitée indépendamment. Conforme à RFC 7644 Section 3.7.

Corps de la requête


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "userName": "[email protected]",
        "name": { "givenName": "Charlie", "familyName": "Leblanc" },
        "emails": [{ "value": "[email protected]", "primary": true }],
        "active": true
      }
    },
    {
      "method": "PATCH",
      "path": "/Users/usr_abc123",
      "data": {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [{ "op": "replace", "path": "active", "value": false }]
      }
    },
    {
      "method": "DELETE",
      "path": "/Users/usr_old999"
    }
  ]
}

Les opérations bulk sont non-transactionnelles. Chaque opération est traitée indépendamment. Si l’opération #3 échoue, les opérations #1, #2, #4, etc. sont quand même traitées.

Syntaxe de Filtre

La syntaxe de filtre SCIM (RFC 7644 Section 3.4.2.2) supporte la comparaison d’attributs, les opérateurs logiques et le regroupement.

Opérateurs de Comparaison

Opérateur	Description	Exemple
`eq`	Égal	`userName eq "[email protected]"`
`ne`	Différent	`active ne false`
`co`	Contient (sous-chaîne)	`name.familyName co "martin"`
`sw`	Commence par	`userName sw "alice"`
`ew`	Termine par	`userName ew "@example.com"`
`gt`	Supérieur à	`meta.lastModified gt "2025-01-01T00:00:00Z"`
`lt`	Inférieur à	`meta.created lt "2025-02-01T00:00:00Z"`
`pr`	Présent (l’attribut existe et est non vide)	`phoneNumbers pr`

Opérateurs Logiques

Opérateur	Description	Exemple
`and`	Les deux conditions doivent être vraies	`active eq true and name.familyName co "martin"`
`or`	Au moins une condition doit être vraie	`userName eq "[email protected]" or userName eq "[email protected]"`

Exemples de Filtre


GET /api/scim/v2/Users?filter=userName eq "[email protected]"
GET /api/scim/v2/Users?filter=active eq true and name.familyName eq "Martin"
GET /api/scim/v2/Users?filter=meta.lastModified gt "2025-02-01T00:00:00Z"

Mapping des Attributs

GET/api/scim/connections/[id]/mappingsRequires: manage:scim_connections

Liste les mappings d’attributs pour une connexion SCIM.

Directions de mapping

Direction	Description
`inbound`	Uniquement de l’IdP vers Auris (lors du provisioning depuis l’IdP)
`outbound`	Uniquement d’Auris vers l’IdP (quand l’IdP lit depuis Auris)
`both`	Mapping bidirectionnel

POST/api/scim/connections/[id]/mappingsRequires: manage:scim_connections

Crée un nouveau mapping d’attributs.

DELETE/api/scim/connections/[id]/mappings/[mappingId]Requires: manage:scim_connections

Supprime un mapping d’attributs.

Statistiques de Synchronisation

GET/api/scim/connections/[id]/statsRequires: view:scim_connections

Obtient les statistiques de provisioning pour une connexion SCIM, ventilées par période.

Réponse de succès


{
  "ok": true,
  "data": {
    "last24Hours": { "created": 5, "updated": 12, "deactivated": 1, "errors": 0 },
    "last7Days": { "created": 23, "updated": 89, "deactivated": 4, "errors": 2 },
    "last30Days": { "created": 67, "updated": 312, "deactivated": 11, "errors": 5 }
  }
}

Test de la Connexion

POST/api/scim/connections/[id]/testRequires: manage:scim_connections

Teste une connexion SCIM en effectuant un health check. Vérifie que le token Bearer est valide et que la connexion peut lister les utilisateurs.

Format des Erreurs SCIM

Les erreurs SCIM suivent le schéma d’erreur RFC 7644 :


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "Description de l'erreur lisible",
  "status": "400",
  "scimType": "invalidValue"
}

Types d’erreur SCIM

scimType	HTTP	Description
`invalidValue`	400	La requête contient une valeur d’attribut invalide
`invalidFilter`	400	L’expression de filtre a une erreur de syntaxe
`tooMany`	400	La requête bulk dépasse le nombre maximum d’opérations
`uniqueness`	409	La valeur de l’attribut viole une contrainte d’unicité (ex. email dupliqué)
`mutability`	400	Tentative de modifier un attribut en lecture seule
(aucun)	401	Token Bearer invalide ou manquant
(aucun)	404	Ressource introuvable

Notes Spécifiques par IdP

Okta

Okta envoie userName comme email de l’utilisateur par défaut. Définis l’URL du connecteur SCIM sur https://api.altovar.net/api/scim/v2 et l’authentification sur HTTP Header avec le token Bearer.

Azure AD (Entra ID)

Azure AD utilise externalId comme clé de réconciliation primaire. Configure :

Mode de provisioning : Automatique
URL tenant : https://api.altovar.net/api/scim/v2
Token secret : Ton token Bearer SCIM
Mapping : Mappe userPrincipalName sur userName

Azure AD envoie des requêtes PATCH avec un format légèrement non standard pour les attributs multi-valeurs. Auris gère ces variations automatiquement.

OneLogin

OneLogin supporte le provisioning SCIM 2.0. Configure l’URL base SCIM et le token Bearer dans les paramètres de provisioning de l’application OneLogin.

Référence des Permissions

Permission	Description
`manage:scim_connections`	Créer, mettre à jour et supprimer les connexions SCIM et les mappings d’attributs
`view:scim_connections`	Visualiser les connexions SCIM et les statistiques de synchronisation
`view:scim_logs`	Visualiser les logs de provisioning SCIM

Les endpoints du protocole SCIM (/api/scim/v2/*) utilisent l’authentification par token Bearer de la connexion SCIM, pas les permissions admin standard d’Auris. Les permissions ci-dessus s’appliquent uniquement aux endpoints de gestion des connexions.

Pages Associées

Protocole SCIM 2.0 — Comment fonctionne le provisioning SCIM au niveau du protocole
Guide Provisioning SCIM 2.0 — Guide étape par étape pour configurer SCIM
Provisioning SCIM (Console) — Configure les connexions SCIM depuis la Console
API Utilisateurs — Endpoints de gestion manuelle des utilisateurs
API Import et Export Utilisateurs — Alternative de migration d’utilisateurs en masse