API SCIM 2.0

Auris implementa il protocollo SCIM 2.0 (System for Cross-domain Identity Management) per il provisioning automatico di utenti e gruppi. SCIM consente agli identity provider come Okta, Azure AD (Entra ID), OneLogin e JumpCloud di creare, aggiornare e disattivare automaticamente gli account utente in Auris quando vengono apportate modifiche nella directory dell’IdP.

L’API SCIM segue le specifiche RFC 7643 (Core Schema) e RFC 7644 (Protocol).

Configurazione della Connessione SCIM

Prima che il tuo IdP possa effettuare il provisioning degli utenti, devi creare una connessione SCIM nella Console di Auris:

Vai su Console > Impostazioni > Provisioning SCIM
Clicca su Aggiungi Connessione
Annota l’URL Base SCIM e il Token Bearer
Configura questi valori nelle impostazioni di integrazione SCIM del tuo IdP

L’URL base SCIM segue questo formato:


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

Autenticazione

Tutti gli endpoint SCIM utilizzano l’autenticazione Bearer token. Il token viene generato durante la creazione di una connessione SCIM nella Console di Auris.


Authorization: Bearer scim_token_here

I token SCIM sono a lunga scadenza e garantiscono accesso completo al provisioning. Trattali come segreti. Ruota periodicamente i token dalla Console di Auris.

Gestione delle Connessioni

Questi endpoint servono per gestire le connessioni SCIM dalla Console di Auris (API admin). Non fanno parte del protocollo SCIM stesso.

GET/api/scim/connectionsRequires: view:scim_connections

Elenca tutte le connessioni SCIM per il tenant.

Risposta di successo


{
  "ok": true,
  "data": [
    {
      "id": "scim_conn_abc123",
      "name": "Okta Production",
      "provider": "okta",
      "keycloakRealm": "acme-corp",
      "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

Crea una nuova connessione SCIM. Restituisce i dettagli della connessione incluso il token Bearer generato. Il token viene restituito solo una volta — conservalo in modo sicuro.

Corpo della richiesta


{
  "name": "Okta Production",
  "provider": "okta",
  "keycloakRealm": "acme-corp"
}

Risposta di successo


{
  "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"
  }
}

Utenti

Elenca Utenti

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

Elenca gli utenti nel tenant. Supporta filtri SCIM, paginazione e selezione attributi. Restituisce gli utenti nel formato SCIM Core Schema.

Parametri di query

Parametro	Tipo	Descrizione
`filter`	string	Espressione di filtro SCIM (vedi Sintassi Filtro)
`startIndex`	integer	Indice iniziale base 1 (default: 1)
`count`	integer	Risultati massimi per pagina (default: 20, max: 100)
`sortBy`	string	Attributo per ordinamento (es. `userName`)
`sortOrder`	`ascending` \| `descending`	Direzione ordinamento (default: `ascending`)

Risposta di successo


{
  "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": "Smith",
        "formatted": "Alice Smith"
      },
      "displayName": "Alice Smith",
      "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"
      }
    }
  ]
}

Le risposte SCIM usano il formato schema SCIM (non l’envelope standard dell’API Auris). I campi schemas, l’array Resources e l’oggetto meta sono richiesti dalla specifica SCIM.

Crea Utente

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

Crea un nuovo account utente. L’utente viene creato sia nel database Auris che nel realm Keycloak associato alla connessione SCIM. Se viene fornito externalId, viene memorizzato per future riconciliazioni.

Corpo della richiesta


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

Mappatura campi SCIM → Auris (predefinita)

Campo SCIM	Campo Auris	Note
`userName`	`email` / `scimUserName`	Usato come identificatore primario
`externalId`	`scimExternalId`	Identificatore univoco lato IdP
`name.givenName`	`firstName`
`name.familyName`	`lastName`
`emails[primary].value`	`email`	L’email primaria diventa l’email Auris
`phoneNumbers[0].value`	`phoneNumber`
`active`	`enabled`

Risposta di successo (HTTP 201): Rappresentazione completa dell’utente SCIM.

Aggiornamento Parziale (PATCH)

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

Aggiorna parzialmente un utente usando operazioni SCIM PATCH. Questo è il metodo di aggiornamento più comunemente usato dagli IdP. Supporta le operazioni add, replace e remove.

Corpo della richiesta — Disattiva utente


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

Tipi di operazioni PATCH

Operazione	Descrizione
`add`	Aggiunge un nuovo valore a un attributo multi-valore o imposta un attributo a valore singolo
`replace`	Sostituisce il valore corrente di un attributo
`remove`	Rimuove un valore attributo

Elimina Utente

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

Elimina (disattiva) un utente. In Auris, l’eliminazione SCIM esegue un soft-delete: l’utente viene disabilitato e il suo account Keycloak viene rimosso, ma il record del database viene conservato per scopi di audit.

Risposta di successo: HTTP 204 No Content (corpo vuoto, per specifica SCIM).

Gruppi

Elenca Gruppi

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

Elenca i gruppi nel tenant. I gruppi in Auris corrispondono ai ruoli. Supporta filtri SCIM e paginazione.

Risposta di successo


{
  "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"
      }
    }
  ]
}

Aggiornamento Parziale Gruppo (PATCH)

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

Aggiorna parzialmente un gruppo usando operazioni SCIM PATCH. Usato principalmente per aggiungere o rimuovere membri.

Corpo della richiesta — Aggiungi membri


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

Corpo della richiesta — Rimuovi un membro


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

Operazioni Bulk

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

Esegui multiple operazioni SCIM in una singola richiesta. Supporta fino a 100 operazioni per richiesta. Ogni operazione viene elaborata indipendentemente. Conforme a RFC 7644 Sezione 3.7.

Corpo della richiesta


{
  "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": "Brown" },
        "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"
    }
  ]
}

Le operazioni bulk sono non-transazionali. Ogni operazione viene elaborata indipendentemente. Se l’operazione #3 fallisce, le operazioni #1, #2, #4, ecc. vengono comunque elaborate.

Sintassi Filtro

La sintassi di filtro SCIM (RFC 7644 Sezione 3.4.2.2) supporta confronto attributi, operatori logici e raggruppamento.

Operatori di Confronto

Operatore	Descrizione	Esempio
`eq`	Uguale	`userName eq "[email protected]"`
`ne`	Diverso	`active ne false`
`co`	Contiene (sottostringa)	`name.familyName co "smith"`
`sw`	Inizia con	`userName sw "alice"`
`ew`	Termina con	`userName ew "@example.com"`
`gt`	Maggiore di	`meta.lastModified gt "2025-01-01T00:00:00Z"`
`lt`	Minore di	`meta.created lt "2025-02-01T00:00:00Z"`
`pr`	Presente (l’attributo esiste ed è non vuoto)	`phoneNumbers pr`

Operatori Logici

Operatore	Descrizione	Esempio
`and`	Entrambe le condizioni devono essere vere	`active eq true and name.familyName co "smith"`
`or`	Almeno una condizione deve essere vera	`userName eq "[email protected]" or userName eq "[email protected]"`

Esempi di Filtro


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

Mappatura Attributi

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

Elenca le mappature attributi per una connessione SCIM.

Direzioni di mappatura

Direzione	Descrizione
`inbound`	Solo da IdP ad Auris (durante il provisioning dall’IdP)
`outbound`	Solo da Auris all’IdP (quando l’IdP legge da Auris)
`both`	Mappatura bidirezionale

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

Crea una nuova mappatura attributi.

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

Elimina una mappatura attributi.

Statistiche di Sincronizzazione

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

Ottieni le statistiche di provisioning per una connessione SCIM, suddivise per periodo.

Risposta di successo


{
  "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 della Connessione

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

Testa una connessione SCIM eseguendo un health check. Verifica che il token Bearer sia valido, il realm Keycloak sia accessibile e la connessione possa elencare gli utenti.

Formato degli Errori SCIM

Gli errori SCIM seguono lo schema di errore RFC 7644:


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "Descrizione dell'errore leggibile",
  "status": "400",
  "scimType": "invalidValue"
}

Tipi di errore SCIM

scimType	HTTP	Descrizione
`invalidValue`	400	La richiesta contiene un valore attributo non valido
`invalidFilter`	400	L’espressione filtro ha un errore di sintassi
`tooMany`	400	La richiesta bulk supera il numero massimo di operazioni
`uniqueness`	409	Il valore dell’attributo viola un vincolo di unicità (es. email duplicata)
`mutability`	400	Tentativo di modificare un attributo di sola lettura
(nessuno)	401	Token Bearer non valido o mancante
(nessuno)	404	Risorsa non trovata

Note Specifiche per IdP

Okta

Okta invia userName come email dell’utente per impostazione predefinita. Imposta l’URL del connettore SCIM su https://api.altovar.net/api/scim/v2 e l’autenticazione su HTTP Header con il token Bearer.

Azure AD (Entra ID)

Azure AD usa externalId come chiave di riconciliazione primaria. Configura:

Modalità provisioning: Automatica
URL tenant: https://api.altovar.net/api/scim/v2
Token segreto: Il tuo token Bearer SCIM
Mappatura: Mappa userPrincipalName su userName

Azure AD invia richieste PATCH con un formato leggermente non standard per gli attributi multi-valore. Auris gestisce queste variazioni automaticamente.

OneLogin

OneLogin supporta il provisioning SCIM 2.0. Configura l’URL base SCIM e il token Bearer nelle impostazioni di provisioning dell’app OneLogin.

Riferimento Permessi

Permesso	Descrizione
`manage:scim_connections`	Crea, aggiorna ed elimina connessioni SCIM e mappature attributi
`view:scim_connections`	Visualizza connessioni SCIM e statistiche di sincronizzazione
`view:scim_logs`	Visualizza i log di provisioning SCIM

Gli endpoint del protocollo SCIM (/api/scim/v2/*) usano l’autenticazione con token Bearer della connessione SCIM, non i permessi admin standard di Auris. I permessi sopra elencati si applicano solo agli endpoint di gestione delle connessioni.

Correlati

Protocollo SCIM 2.0 — Come funziona il provisioning SCIM a livello di protocollo
Guida Provisioning SCIM 2.0 — Guida passo-passo alla configurazione SCIM
Provisioning SCIM — Configura le connessioni SCIM dalla Console
API Utenti — Endpoint di gestione utenti manuale
API Import ed Export Utenti — Alternativa di migrazione utenti bulk