Käyttäjien provisiointi (SCIM): Tekninen yleiskatsaus

Alusta tukee automaattista käyttäjien provisiointia Microsoft Entra ID:stä SCIM 2.0:n kautta. Entra ID luo, päivittää ja poistaa käyttäjiä Systamissa. Asiakas hallitsee ketä provisioidaan liittämällä käyttäjiä ja ryhmiä Systamin enterprise-sovellukseen Entrassa.

Protokolla

Integraatio käyttää SCIM 2.0:aa (RFC 7643/7644), endpointit /scim/v2/Users, /scim/v2/Groups, sekä discovery-endpointit ServiceProviderConfig, ResourceTypes ja Schemas.

Tuetut operaatiot: GET, POST ja PATCH käyttäjille, sekä GET, POST, PATCH ja DELETE ryhmille. PUT ja DELETE käyttäjille eivät ole tuettuja — deprovisiointi tehdään komennolla PATCH active=false. Bulk-operaatioita ei tueta.

Suodatus toimii ehdolla userName eq "value" käyttäjille ja displayName eq "value" ryhmille. Sivutus käyttää parametreja startIndex ja count, enintään 500 kerrallaan.

Tunnistautuminen käyttää organisaatiokohtaista bearer-tokenia (Secret Token), jonka alusta generoi. Pyynnöissä pitää käyttää otsaketta Content-Type: application/scim+json. Toistuvat tunnistautumisvirheet rajoitetaan.

Entra ID ajaa provisiointikierroksen noin 40 minuutin välein.

Asiakkaan käyttöönotto

1. Ota Microsoft Entra ID -laajennus käyttöön Systam Studiossa kohdassa Extensions. Alusta generoi Tenant URL:n ja Secret Tokenin, molemmat näkyvät siellä.
2. Luo Entrassa non-gallery-enterprise-sovellus, aseta Provisioning mode arvoon Automatic, syötä Tenant URL ja Secret Token, ja aja Test connection.
3. Mäppää attribuutit. Pakolliset: userName, name.givenName, name.familyName ja sähköposti tyyppiä work tai other (suositus emails[type eq "work"].value). Valinnaiset: emails[type eq "other"].value, phoneNumbers[type eq "work"].value, phoneNumbers[type eq "other"].value, preferredLanguage, ja työtila-laajennusattribuutti urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace.
4. Jos organisaatiolla on useampi työtila, määritä työtilan kohdistus Systam Studiossa kohdassa Extensions → Microsoft Entra ID (ks. Työtilan kohdistus), liitä käyttäjät ja/tai ryhmät sovellukseen Entrassa, ja käynnistä provisiointi.

Synkronoitavat attribuutit

userName toimii linkkinä Entra-identiteetin ja Systam-käyttäjän välillä.

Työsähköpostista tulee käyttäjän sähköposti ja kirjautumistunnus. Jos Entra ei lähetä työsähköpostia, käytetään other-tyypin sähköpostia. Etu- ja sukunimi, work- ja other-tyypin puhelinnumerot (E.164-muodossa työtilan maan mukaan, Suomi jos käyttäjällä ei vielä ole työtilaa, muunnetaan uudelleen kun työtila asetetaan), muut sähköpostit sekä kieliasetus tallennetaan. Muut kuin work- ja other-tyypin sähköpostit ja puhelinnumerot ohitetaan.

Attribuutit joita ei tallenneta ohitetaan ilman virhettä: displayName, title, department, addresses, externalId, ja enterprise-laajennus (manager, employeeNumber jne). Entran oletusmäppäykset voi siis jättää ennalleen.

Käyttäjätilit

Provisioidut käyttäjät ovat tavallisia työtilan käyttäjiä ilman salasanaa. Kirjautuminen tapahtuu SSO:n tai alustan omien kirjautumispolkujen kautta. Provisiointi ei anna admin-oikeuksia.

Luonnissa olemassa olevaa käyttäjää käytetään uudelleen, jos sama userName on jo linkitetty organisaatiossa tai jos organisaatiossa on käyttäjä, jolla on sama tallennettu sähköpostiosoite (work, muuten other). Muuten luodaan uusi käyttäjä. Entran sisäistä object ID:tä ei käytetä täsmäytykseen. Jos sähköpostiosoite kuuluu jo toisen organisaation käyttäjälle, pyyntö hylätään (403). Sama userName kahdesti samassa organisaatiossa hylätään (409).

PATCH-päivitykset kohdistuvat tuettuihin attribuutteihin ja ohittavat loput.

Deprovisiointi (active=false) poistaa käyttäjätilin kokonaan. Soft-delete- tai inaktiivista tilaa ei ole, joten myöhemmin uudelleen liitetty käyttäjä luodaan uutena tilinä. Organisaation omistajia ei koskaan poisteta, vain irrotetaan provisioinnista.

Työtilan kohdistus

Jokainen käyttäjä sijoitetaan ensisijaiseen työtilaan ensimmäisen osuvan säännön mukaan:

1. Attribuuttimäppäys — Entran lähettämä primaryWorkspace-arvo mäpätään työtilaan admin-näkymässä. Attribuuttimäppäykset ohittavat ryhmämäppäykset.
2. Ryhmämäppäys — Entra-ryhmän Object ID mäpätään työtilaan. Käytetään vain, kun käyttäjällä ei vielä ole ensisijaista työtilaa, sillä hetkellä kun Entra lisää käyttäjän ryhmään, ja ryhmä osuu täsmälleen yhteen mäppäykseen.
3. Varatyötila — asetetaan Systam Studiossa kohdassa Extensions → Microsoft Entra ID. Käytetään vain, kun uusi käyttäjä luodaan eikä mikään mäppäys osu. Älä käytä sitä yhdessä ryhmämäppäyksen kanssa: uudet käyttäjät saisivat varatyötilan ennen kuin Entra lisää heidät ryhmiinsä, eikä ryhmämäppäys enää vaikuttaisi.

Yhden työtilan organisaatio ei tarvitse mäppäyksiä: jokainen uusi käyttäjä linkitetään työtilaan automaattisesti, ja Studio näyttää mäppäykset vain, kun työtiloja on useampi. Jos mikään ei osu, käyttäjä luodaan silti. All workspaces -tilassa käyttäjä linkitetään kaikkiin työtiloihin. Muuten käyttäjä ei voi kirjautua eikä näy Studiossa ennen kuin hänelle asetetaan työtila.

Aina kun provisiointi asettaa käyttäjän ensisijaisen työtilan, käyttäjän Uninvited visitors -asetus kytkeytyy päälle siinä työtilassa. Näin käy myös, kun Entra lähettää työtila-arvon olemassa olevalle käyttäjälle, vaikka pääkäyttäjä olisi kytkenyt asetuksen pois Studiossa.

Kohdistus on pysyvä: käyttäjän poistaminen ryhmästä ei poista työtilaa, ja ensisijainen työtila vaihtuu vain kun Entra lähettää uuden primaryWorkspace-arvon. Synkronointiasetus määrittää lisätäänkö käyttäjät vain ensisijaiseen työtilaan vai organisaation kaikkiin työtiloihin.

Ryhmät

Ryhmät provisioidaan vain datana — ne eivät anna rooleja tai oikeuksia. Ainoa vaikutus on yllä kuvattu ryhmäpohjainen työtilan kohdistus. Ryhmien nimien kannattaa olla uniikkeja, koska Entra täsmää olemassa oleviin ryhmiin displayName:n perusteella.

Nykyinen toiminta

• Deprovisioidut käyttäjät poistetaan, ei deaktivoida.
• Synkronoitavia attribuutteja ei voi määrittää käyttäjäkohtaisesti — Entra ylikirjoittaa aina synkronoitavat kentät.
• Ryhmäjäsenyys ei mäpätä rooleihin tai oikeuksiin.

Siinä SCIM-provisioinnin tekninen ydin. Jos jokin kohta kaipaa lisätarkennusta tiettyyn asiakastapaukseen, kannattaa olla yhteydessä.