Microsoft Entra ID -integraation SCIM käyttöönotto

Muokattu Ma, 26 Loka klo 2:24 PM

Jos käytössäsi on Microsoft Entra ID, voit yhdistää hakemistosi Systam Studioon. Tämän jälkeen Systam Visit -vastaanottajia ei tarvitse luoda käsin. Tässä ohjeessa kerromme, miten otat käyttöön Microsoft Entra ID:n automaattisen käyttäjäsynkronoinnin.

Huomio: Laajennus on maksullinen ja vaatii aktivoinnin. Ota yhteyttä asiakastukeemme osoitteessa support@systam.io.

Kun käyttöönotto on valmis, Microsoft Entra ID voi:

luoda käyttäjiä eli vastaanottajia Systam Studioon
päivittää käyttäjien tietoja Systam Studiossa, kuten ensisijaisen työtilan, nimen, sähköpostiosoitteet, puhelinnumerot ja aktiivisen tilan
poistaa käyttäjiä pysyvästi Systam Studiosta, kun käyttöoikeutta ei enää tarvita
pitää käyttäjätiedot synkronoituna Microsoft Entra ID:n ja Systamin välillä

Lue lisää Entra ID:stä ja provisioinnista: What is automated app user provisioning in Microsoft Entra ID.

Ennen kuin aloitat

Ennakkovaatimukset

Microsoft Entra -tenant
Microsoft Entra ID -käyttäjätili, jolla on Cloud Application Administrator- tai Application Administrator -rooli. Tarvitset jommankumman, jotta voit luoda yrityssovelluksen vaiheessa 3. Kun sovellus on luotu, myös sen Application Owner voi hallita provisiointia. Global Administrator käy myös, mutta se antaa enemmän oikeuksia kuin tämä määritys vaatii.
Systam-organisaatiotili osoitteessa app.systam.io sekä käyttäjätunnus, jolla on Organisaation omistaja -oikeudet

Hyvä tietää

Microsoft Entra ID ajaa synkronoinnin noin 40 minuutin välein, joten Entrassa tehty muutos voi kestää hetken ennen kuin se näkyy Systamissa.
Käyttäjät poistetaan pysyvästi. Systam ei tue keskeytettyä eli soft delete -tilaa. Kun käyttäjä poistetaan synkronoinnin piiristä tai poistetaan käytöstä Entra ID:ssä, Systam poistaa käyttäjän pysyvästi. Jos käyttäjä palautetaan myöhemmin synkronoinnin piiriin, hänet luodaan uudelleen uutena käyttäjänä.

Vaihe 1: Suunnittele provisioinnin käyttöönotto

Tutustu siihen, miten provisiointipalvelu toimii.
Määritä, ketkä kuuluvat provisioinnin piiriin.
Määritä, mitä tietoja yhdistetään Microsoft Entra ID:n ja Systamin välillä.

Vaihe 2: Valmistelu Systam Studiossa

Avaa Systam Studio ja siirry kohtaan Laajennukset → Microsoft Entra ID. Valitse Ota käyttöön.
Kopioi Studiossa näkyvät arvot Tenant URL ja Secret Token. Tarvitset niitä Entra ID:n määritykseen.
Voit halutessasi syöttää myös organisaation Tenant ID:n. Se helpottaa vikatilanteiden selvittämistä.
Et voi generoida uutta Secret Tokenia itse. Jos tarvitset uuden, esimerkiksi jos se on päässyt vuotamaan, ota yhteyttä Systamin tukeen.

Jos organisaatiollasi on useampi työtila, määrität samalla sivulla myös työtilojen kohdistuksen. Katso vaihe 6.

Vaihe 3: Lisää Systam Microsoft Entra ID:hen

Kirjaudu Microsoft Entra admin centeriin järjestelmänvalvojana.
Siirry kohtaan Identity → Applications → Enterprise applications.
Valitse New application.
Valitse Create your own application.
Anna sovellukselle nimeksi esimerkiksi Systam.
Valitse Integrate any other application you don't find in the gallery (Non-gallery).
Valitse Create.

Vaihe 4: Määritä, ketkä kuuluvat provisioinnin piiriin

Microsoft Entra -provisiointipalvelulla voit määrittää, ketkä provisioidaan sovellukseen. Voit rajata joukon joko sovellukseen tehtyjen määritysten tai käyttäjän tai ryhmän attribuuttien perusteella. Jos käytät sovellukseen tehtyjä määrityksiä, voit määrittää käyttäjät ja ryhmät tämän ohjeen avulla: Assign users and groups to an application.

Aloita pienesti. Testaa ensin pienellä käyttäjä- ja ryhmäjoukolla.
Kun provisioinnin laajuudeksi on asetettu määritetyt käyttäjät ja ryhmät, voit ottaa integraation käyttöön vaiheittain.

Vaihe 5: Ota automaattinen synkronointi käyttöön

Tässä osiossa määrität Microsoft Entra -provisiointipalvelun luomaan, päivittämään ja poistamaan käyttäjiä Systamissa.

5.1 Admin Credentials

Avaa Entra ID:ssä Systam-sovelluksen välilehti Provisioning.
Siirry kohtaan Manage → Provisioning ja aseta Provisioning Mode arvoksi Automatic.
Syötä Systam Studiossa näkyvät arvot:
- Tenant URL
- Secret Token
Valitse Test Connection varmistaaksesi yhteyden.

Jos testaus epäonnistuu:

varmista, että token on kopioitu oikein
tarkista, ettei mukana ole ylimääräisiä välilyöntejä

5.2 Attribuuttien mäppäykset

Systam käyttää provisioinnissa rajattua joukkoa Microsoft Entra ID:n käyttäjäattribuutteja. Määritykset tehdään Systam-yrityssovelluksen Provisioning-välilehdellä.

Identiteetti ja tila

userName

Yksilöllinen tunniste käyttäjälle Systamissa.
Arvo otetaan siitä lähdeattribuutista, jonka määrität userName-mäppäykseen, yleensä käyttäjän kirjautumisnimestä kuten UPN:stä tai sähköpostiosoitteesta.

active

Määrittää, onko käyttäjätili aktiivinen Systamissa.
Arvo määräytyy active-mäppäyksessä määritellyn lausekkeen perusteella.

Yhteystiedot

Systam käyttää sähköpostiosoitteita ja puhelinnumeroita, joiden tyyppi on work tai other. Muut tyypit ohitetaan.

Sähköpostiosoitteet
- Jokaisella käyttäjällä pitää olla sähköpostiosoite, jonka tyyppi on work tai other. Jos molemmat ovat olemassa, Systam käyttää work-osoitetta.
- Käyttäjää, jolla ei ole work- eikä other-osoitetta, ei provisioida.
Puhelinnumerot
- Puhelinnumerot ovat vapaaehtoisia. Systam käyttää numeroita, joiden tyyppi on work tai other. Muut tyypit ohitetaan.
- Jos et halua hallita puhelinnumeroita Systamissa, jätä puhelinnumerot mäppäämättä.
- Systam muuntaa puhelinnumerot automaattisesti kansainväliseen muotoon. Katso alta Miten synkronointi toimii.

Esimerkki mäppäyskonfiguraatiosta

Systam-attribuutti	Microsoft Entra ID -attribuutti (esimerkki)	Pakollinen
`userName`	`userPrincipalName`	Kyllä
`active`	`Switch([IsSoftDeleted], , "False", "True", "True", "False")`	Kyllä
`name.givenName`	`givenName`	Kyllä
`name.familyName`	`surname`	Kyllä
`emails[type eq "work"].value`	`Coalesce(mail, userPrincipalName)`	Kyllä*
`emails[type eq "other"].value`	`first([otherMails])`	Ei
`phoneNumbers[type eq "work"].value`	`mobile`	Ei
`phoneNumbers[type eq "other"].value`	`telephoneNumber`	Ei
`preferredLanguage`	`preferredLanguage`	Ei

* Suositeltu. Jokaisella käyttäjällä pitää olla work- tai other-tyyppinen sähköpostiosoite.

Vaihe 6: Käyttäjien kohdistus työtiloihin

Jokaisella käyttäjällä pitää olla ensisijainen työtila, jotta hän näkyy Studiossa ja voi kirjautua. Ensisijaista työtilaa käytetään myös oletusarvona eri toiminnoissa.

Kun käyttäjällä on ensisijainen työtila, se pysyy. Ryhmämuutokset eivät koskaan siirrä sitä. Työtila vaihtuu vain, kun Entra ID lähettää käyttäjälle eri työtila-arvon.

Montako työtilaa organisaatiollasi on Systam Studiossa?

6.1 Yksi työtila

Mitään ei tarvitse määrittää. Systam liittää jokaisen uuden käyttäjän työtilaanne automaattisesti.
Voit jättää työtilan mäppäyksen Entra ID:ssä kokonaan pois. Studio näyttää työtilamääritykset vain, jos organisaatiolla on useampi työtila.

Huomio: Jos lisäätte myöhemmin toisen työtilan, sen jälkeen luodut käyttäjät tarvitsevat jonkin kohdan 6.2 tavoista.

Siirry vaiheeseen 7.

6.2 Useampi työtila

Vaihe A: Valitse synkronointitapa

Siirry Systam Studiossa kohtaan Laajennukset → Microsoft Entra ID ja valitse, miten käyttäjät lisätään työtiloihin:

Ensisijaiset työtilat: jokainen käyttäjä liitetään yhteen työtilaan.
Kaikki työtilat: jokainen käyttäjä liitetään kaikkiin työtiloihin, ja hänellä on silti yksi ensisijainen työtila. Tässä tilassa käyttäjä saa aina ensisijaisen työtilan, vaikka mikään alla olevista tavoista ei löytäisi sitä.

Huomio: Jos vaihdat asetuksen myöhemmin vaihtoehtoon Ensisijaiset työtilat, käyttäjiä ei poisteta muista työtiloista automaattisesti.

Vaihe B: Valitse, miten Entra ID kertoo käyttäjän työtilan

Valitse organisaatiollesi sopiva tapa. Vaihtoehdot ovat suosittelemassamme järjestyksessä.

Tavat 1 ja 3 tarvitsevat Entra ID:ssä mukautetun työtila-attribuutin. Lisää se ensin:

Avaa Entra ID:ssä Systam-sovelluksen välilehti Provisioning ja sieltä Attribute Mapping.
Valitse Provision Microsoft Entra ID Users.
Vieritä sivun alaosaan ja valitse Show advanced options.
Valitse Edit attribute list for Systam (tai sovelluksen nimi, jonka sille annoit).
Lisää attribuuttilistan loppuun uusi attribuutti:
- Name: urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
- Type: string
Valitse Save.

Tapa 1: Attribuutti (suositeltu)

Tällä tavalla voit kohdistaa käyttäjät tarkasti eri työtiloihin esimerkiksi osaston, toimipisteen tai maan perusteella.

Systam tarkistaa attribuutin ensin. Kun työtila löytyy attribuutin perusteella, ryhmämäppäystä ei oteta huomioon kyseisen käyttäjän kohdalla. Voit käyttää tätä tapaa yhdessä Entra-ryhmämäppäyksen (tapa 2) kanssa.

Entra ID:ssä:

Palaa Attribute Mapping -näkymään ja tarkista oletusmäppäykset.
Lisää uusi työtilamäppäys:
- vieritä listan loppuun ja valitse Add New Mapping
- Source attribute: valitse Entra ID:n attribuutti, jota haluat käyttää käyttäjän työtilan määrittämiseen, esimerkiksi department, officeLocation tai extension-attribuutti
- Target attribute: valitse mukautettu attribuutti urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
Valitse OK.
Valitse Save.

Systam Studiossa:

Siirry kohtaan Laajennukset → Microsoft Entra ID.
Vieritä alas kohtaan Aseta ensisijaisen työtilan attribuuttimääritykset.
Valitse Lisää määritys ja syötä arvo, joka mäppäämässäsi attribuutissa voi olla.
Valitse, mikä työtila on ensisijainen, ja tallenna muutokset.
Toista, kunnes jokainen haluamasi arvo on määritetty.

Tapa 2: Entra-ryhmä

Tällä tavalla työtila määräytyy sen Entra-ryhmän perusteella, johon käyttäjä kuuluu.

Ryhmä asettaa työtilan vain käyttäjälle, jolla sitä ei vielä ole, sillä hetkellä kun Entra ID lisää käyttäjän ryhmään. Jos käyttäjä sai työtilan jo tavalla 1, ryhmää ei oteta huomioon.

Määritä haluamasi ryhmät provisioinnin piiriin ja ota talteen kunkin ryhmän Object ID Entra ID:stä.
Avaa Systam Studio ja siirry kohtaan Laajennukset → Microsoft Entra ID.
Vieritä alas kohtaan Aseta ensisijaisen työtilan ryhmämääritykset.
Valitse Lisää määritys ja syötä ryhmän Object ID ensimmäiseen kenttään.
Valitse, mikä työtila on ensisijainen.
Toista, kunnes jokainen provisioitu ryhmä on määritetty oikeaan työtilaan.
Tallenna muutokset.

Tapa 3: Kiinteä arvo

Käytä tätä, jos kaikkien ensisijainen työtila on sama.

Entra ID:ssä:

Palaa Attribute Mapping -näkymään.
Lisää uusi työtilamäppäys:
- vieritä listan loppuun ja valitse Add New Mapping
- Mapping type: Constant
- Constant Value: syötä arvo, jota Systam käyttää, esimerkiksi systam
- Target attribute: valitse mukautettu attribuutti urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
Valitse OK.
Valitse Save.

Systam Studiossa:

Siirry kohtaan Laajennukset → Microsoft Entra ID.
Vieritä alas kohtaan Aseta ensisijaisen työtilan attribuuttimääritykset.
Valitse Lisää määritys ja syötä aiemmin määrittämäsi kiinteä arvo.
Valitse, mikä työtila on ensisijainen, ja tallenna muutokset.

Tapa 4: Varatyötila

Varatyötilaan ohjautuu jokainen uusi käyttäjä, jonka työtilaa ei löytynyt attribuutin tai kiinteän arvon perusteella.

Siirry Systam Studiossa kohtaan Laajennukset → Microsoft Entra ID.
Valitse varatyötila ja tallenna muutokset.

Varatyötila otetaan käyttöön vain, kun käyttäjä luodaan. Se ei koskaan siirrä käyttäjää, jolla on jo työtila. Jos varatyötila poistetaan, asetus lakkaa vaikuttamasta.

Jos käytät Entra-ryhmämäppäystä, älä aseta varatyötilaa. Uudet käyttäjät saisivat varatyötilan ennen kuin Entra ID lisää heidät ryhmiinsä, eikä ryhmämäppäys enää vaikuttaisi.

Entä jos mikään ei täsmää?

Uusi käyttäjä luodaan silti. Pyyntö ei epäonnistu.
Jos varatyötila on asetettu, käyttäjä ohjautuu sinne.
Kun käytössä on Kaikki työtilat, käyttäjä liitetään kaikkiin työtiloihin.
Muuten käyttäjä on olemassa, mutta hän ei näy Studiossa eikä voi kirjautua ennen kuin saa työtilan: myöhemmin Entra-ryhmämäppäyksen kautta, Entra ID:stä tulevalla korjatulla arvolla tai pääkäyttäjän asettamana Studiossa.

Vaihe 7: Testaa ja käynnistä synkronointi

Testaa yksittäinen käyttäjä

Valitse Provision on demand.
Valitse testikäyttäjä.
Suorita toiminto.
Tarkista Systam Studiosta, että käyttäjä näkyy oikeassa työtilassa.

Ota automaattinen synkronointi käyttöön

Aseta Provisioning status arvoon On.
Valitse haluamasi laajuus.

Seuraa tilannetta

Tarkista provisiointilokit.
Seuraa provisioinnin tilaa.

Miten synkronointi toimii

Olemassa olevien käyttäjien tunnistus. Provisiointi etsii ensin saman organisaation käyttäjää, jolla on sama SCIM-userName. Jos sellaista ei löydy, etsitään käyttäjää, jolla on sama sähköpostiosoite missä tahansa Systam-organisaatiossa. Vertailussa käytetään osoitetta, jonka Systam tallentaa käyttäjälle: work-osoitetta, tai other-osoitetta, jos Entra ID ei lähetä work-osoitetta. Muuten Systam luo uuden käyttäjän. Microsoft Entra ID:n sisäistä object ID:tä ei käytetä tunnistukseen.
Työtila pysyy. Kun ensisijainen työtila on asetettu, se säilyy. Käyttäjän poistaminen ryhmästä ei poista työtilaa. Vain Entra ID:stä tuleva uusi työtila-arvo siirtää sen. Ryhmän poistaminen Entra ID:stä ei vaikuta käyttäjiin eikä heidän työtiloihinsa.
Ryhmät eivät koskaan anna rooleja tai käyttöoikeuksia. Ne vaikuttavat vain työtilan ensimmäiseen kohdistukseen.
Uninvited visitors kytkeytyy päälle. 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 ID lähettää työtila-arvon olemassa olevalle käyttäjälle, vaikka pääkäyttäjä olisi kytkenyt asetuksen pois Studiossa. Kaikki työtilat -tilassa asetus on päällä jokaisessa työtilassa, johon käyttäjä lisätään.
Poistaminen. Kun käyttäjä poistetaan synkronoinnin piiristä tai poistetaan käytöstä Entra ID:ssä, käyttäjä poistetaan pysyvästi.
Organisaation omistajia ei koskaan poisteta. Vain heidän linkityksensä Entra ID:hen puretaan. Käyttäjä ja hänen roolinsa säilyvät.
Synkronoituja kenttiä ei voi ohittaa käyttäjäkohtaisesti Studiossa. Microsoft Entra ID ylikirjoittaa ne joka kierroksella.
Puhelinnumerot muunnetaan kansainväliseen muotoon käyttäjän työtilan maan perusteella. Jos käyttäjällä ei ole työtilaa, käytetään Suomea. Jos käyttäjä saa työtilan myöhemmin eikä numerossa ollut maatunnusta, numero muunnetaan uudelleen kyseisen työtilan maan mukaan.

Vianmääritys

Yleisimmät virheet provisiointilokeissa

Virhe	Mitä se tarkoittaa	Mitä tehdä
401 Unauthorized	Entra ID:ssä oleva Secret Token ei täsmää Studiossa olevaan.	Kopioi nykyinen Secret Token Studiosta uudelleen Entra ID:hen. Yli 20 epäonnistunutta yritystä minuutissa aiheuttaa hetkellisen eston.
403 Forbidden	Käyttäjän sähköpostiosoite on jo toisen Systam-organisaation käyttäjällä.	Ota yhteyttä Systamin tukeen, niin selvitämme, kumpaan organisaatioon käyttäjä kuuluu.
409 Conflict	SCIM-`userName` on jo linkitetty toiseen käyttäjään tässä organisaatiossa.	Ota yhteyttä Systamin tukeen olemassa olevan linkityksen selvittämiseksi.
400 Bad Request: "primaryWorkspace not mapped"	Entra ID päivitti olemassa olevaa käyttäjää työtila-arvolla, jolle ei ole määritystä Studiossa.	Lisää arvolle määritys Studiossa tai korjaa arvo Entra ID:ssä. Entra ID yrittää uudelleen seuraavalla kierroksella.

Microsoft Entra ID yrittää epäonnistuneet toiminnot automaattisesti uudelleen seuraavalla synkronointikierroksella, joten korjattu määritys tai token ratkaisee useimmat virheet ilman muita toimenpiteitä.

Integraation poistaminen käytöstä

Avaa Systam Studiossa kohta Laajennukset → Microsoft Entra ID ja valitse Lopeta laajennuksen käyttö. Tämä pysäyttää synkronoinnin ja poistaa integraation Systamista.

Se ei poista yrityssovellusta (enterprise application) Microsoft Entra -tenantistanne. Jos ette enää tarvitse sitä, poistakaa se Entran admin centerissä.

Nykyiset rajoitteet

Pidä ryhmien nimet yksilöllisinä Entra ID:ssä. Entra ID etsii olemassa olevan ryhmän Systamista nimen perusteella.
Synkronoituja kenttiä ei voi ohittaa käyttäjäkohtaisesti. Microsoft Entra ID ylikirjoittaa ne aina seuraavassa synkronoinnissa.

Siinä se! Uudet kollegat näkyvät nyt Studiossa ilman, että kenenkään tarvitsee lisätä heitä käsin.

Viimeaikaiset haut

Microsoft Entra ID -integraation SCIM käyttöönotto