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

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.fi.

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.

Microsoft Entra ID ajaa synkronoinnin noin 40 minuutin välein, joten Entrassa tehty muutos voi kestää hetken ennen kuin se näkyy Systamissa.

Tärkeät huomioitavat asiat

Ennakkovaatimukset

Ennen käyttöönottoa tarvitset seuraavat:

• Microsoft Entra -tenantin.
• Microsoft Entra ID -käyttäjätilin, jolla on oikeus määrittää provisiointi, esimerkiksi Application Administrator, Cloud Application Administrator, Application Owner tai Global Administrator.
• Systam-organisaatiotilin osoitteessa app.systam.io sekä käyttäjätunnuksen, jolla on Organisaation omistaja -oikeudet.

Muut huomiot

• Organisaation omistajat ovat suojattuja. Systam ei koskaan poista Organization Owner -roolin käyttäjää, vaikka Entra ID poistaisi hänet synkronoinnin piiristä. Vain SCIM-linkitys tämän käyttäjän ja Entra ID:n välillä puretaan — tili ja sen käyttöoikeudet säilyvät ennallaan.
• Soft delete -tilaa ei tueta. 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ätilin pysyvästi. Jos käyttäjä palautetaan myöhemmin synkronoinnin piiriin, hänet luodaan uudelleen uutena käyttäjänä.
• Täsmäytyslogiikka. Provisiointi etsii ensin saman organisaation sisältä käyttäjää, jolla on sama SCIM-userName. Jos sellaista ei löydy, etsitään koko järjestelmästä käyttäjää, jolla on sama työsähköposti. Muussa tapauksessa Systam luo uuden käyttäjän. Microsoft Entra ID:n sisäistä object ID:tä ei koskaan käytetä täsmäytykseen.
• Ryhmät eivät anna rooleja tai käyttöoikeuksia. Provisioidut ryhmät vaikuttavat vain ensisijaisen työtilan määrittämiseen (ks. Vaihe 6) — ne eivät koskaan muuta sitä, mitä käyttäjä voi tehdä Systamissa.

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

Valmistelu

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

Aseta synkronoinnin asetukset

Valitse Systam Studiossa, miten työntekijät lisätään työtiloihin. Voit synkronoida vastaanottajat joko vain yhteen työtilaan (ensisijainen työtila) tai kaikkiin työtiloihin (tällöin työntekijöille määritellään kuitenkin aina myös ensisijainen työtila). Valitse organisaatiollesi sopiva vaihtoehto ennen provisioinnin käynnistämistä.

• Ensisijaiset työtilat

Synkronoi vastaanottajat vain yhteen työtilaan.

• Kaikki työtilat

Synkronoi vastaanottajat kaikkiin työtiloihin.

Huomio: Jos vaihdat asetuksen myöhemmin vaihtoehtoon Ensisijaiset työtilat, vastaanottajia ei poisteta muista työtiloista automaattisesti.

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

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

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

Microsoft Entra -provisiointipalvelulla voit määrittää, ketkä provisioidaan sovellukseen. Rajaus voidaan tehdä joko sovellukseen määritettyjen käyttöoikeuksien 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 hallita käyttöönottoa 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

1. Avaa Entra ID:ssä Systam-sovelluksen välilehti Provisioning.
2. Siirry kohtaan Manage → Provisioning ja aseta Provisioning Mode arvoksi Automatic.
3. Syötä Systam Studiossa näkyvät arvot:
   • Tenant URL
   • Secret Token
4. 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

• 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.

• 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ää Microsoft Entra ID:stä tulevia yhteystietoja vain, kun tyypiksi on määritetty work tai other. Muut tyypit hylätään ja ne voivat aiheuttaa provisioinnin epäonnistumisen kyseisen käyttäjän osalta.

• Sähköpostiosoitteet
  • Attribuutti, joka on mapattu emails[type eq "work"].value-kenttään, toimii käyttäjän ensisijaisena sähköpostiosoitteena Systamissa.
  • Work-tyyppinen sähköpostiosoite on pakollinen. Jos käyttäjällä ei ole work-tyyppistä sähköpostiosoitetta, provisiointi epäonnistuu kyseisen käyttäjän osalta.
• Puhelinnumerot
  • Jos päätät mapata puhelinnumerot, phoneNumbers[type eq "work"].value toimii käyttäjän ensisijaisena puhelinnumerona Systamissa.
  • Work-tyyppinen puhelinnumero on pakollinen, jos puhelinnumerot mapataan.
  • Jos et halua hallita puhelinnumeroita Systamissa, jätä puhelinnumerot kokonaan mapittamatta.
  • Jos mapaat puhelinnumerot, varmista että kaikilla synkronoinnin piirissä olevilla käyttäjillä on work-tyyppinen puhelinnumero.
  • Systam muuntaa puhelinnumeron automaattisesti kansainväliseen muotoon, ja käyttää oletusmaana työtilan maata (oletuksena Suomi, ellei toisin ole määritetty).

Käytännössä:

• work-sähköpostiosoite on aina käyttäjän ensisijainen sähköpostiosoite Systamissa
• kun puhelinnumerot on mapattu, work-puhelinnumero on käyttäjän ensisijainen numero Systamissa

Esimerkki mahdollisesta mäppäyskonfiguraatiosta

Vaihe 6: Ensisijaisen työtilan määrittäminen

Jokaisella työntekijällä täytyy olla jokin ensisijainen työtila. Ensisijaista työtilaa käytetään vakioarvona erilaisissa toiminnoissa. Alla on listattuna kolme eri tapaa, jolla määritys voidaan tehdä.

Jos käyttäjälle ei tule ensisijaista työtilaa lainkaan, Systam luo tilin silti, mutta käyttäjä ei näy Studiossa eikä voi kirjautua ennen kuin työtila on määritetty.

Työtilan kohdistus on pysyvä: käyttäjän poistaminen ryhmästä ei poista häntä työtilasta, ja ensisijainen työtila vaihtuu vain kun Entra ID lähettää uuden arvon. Silloin käyttäjä lisätään uuteen työtilaan — häntä ei poisteta edellisestä.

Huomio: Kun provisiointi lisää käyttäjän työtilaan ensimmäistä kertaa, kyseisen työtilan Uninvited visitors -asetus kytkeytyy automaattisesti päälle. Työtiloihin, joissa käyttäjä oli jo ennestään, tämä ei vaikuta.

6.1 Määritys yhteen työtilaan (Yleisin käyttötapaus)

Jos vastaanottajille halutaan määrittää vain yksi päätoiminen työtila, tämä on kaikista varmin tapa siihen.

Jatketaan vaiheen 5 määrityksiä lisäämällä loppuun vielä mukautettu attribuutti, urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace, joka määrittää käyttäjän ensisijaisen työtilan.

Attribuutin lisääminen skeemaan

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

Workspace-mäppäyksen täsmääminen kiinteään osoitteeseen

1. Palaa Attribute Mapping -näkymään.
2. Lisää uusi workspace-mäppäys:
   • vieritä listan loppuun ja valitse Add New Mapping
   • Mapping type: Constant
   • Constant Value: kirjoita tähän haluamasi arvo, jota Systamin järjestelmä kuuntelee. Esim. "systam".
   • Target attribute: valitse mukautettu attribuutti urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
3. Valitse OK.
4. Valitse Save.

Määritys Studiossa

1. Avaa Systam Studio ja siirry kohtaan Laajennukset → Microsoft Entra ID
2. Rullaa alas kohtaan "Aseta ensisijaisen työtilan attribuuttimääritykset"
3. Paina "Lisää määritys" ja lisää tähän aiemmin määritetty kiinteä arvo 
4. Valitse minkä työtilan haluat ensisijaiseksi valinnaksi ja tallenna muutokset
5. Valmis! Siirry vaiheeseen 7

6.2 Määritys Entra-ryhmän perusteella

Jos vastaanottajille halutaan määrittää päätoiminen työtila Entra-ryhmän perusteella, se onnistuu näin.

1. Määritä haluamasi ryhmät provisioinnin piiriin ja ota ryhmien tunnisteet (GroupID) talteen
2. Avaa Systam Studio ja siirry kohtaan Laajennukset → Microsoft Entra ID
3. Rullaa alas kohtaan "Aseta ensisijaisen työtilan ryhmämääritykset"
4. Paina "Lisää määritys" ja lisää provisioitu ryhmätunnus ensimmäiseen kenttään
5. Valitse minkä työtilan haluat ensisijaiseksi valinnaksi
6. Toista niin monta kertaa, kunnes jokainen provisioitu ryhmä on määritetty oikeaan työtilaan
7. Lopuksi tallenna muutokset
8. Valmis! Siirry vaiheeseen 7

6.3 Määritys attribuutin perusteella

Jos vastaanottajat halutaan määrittää hyvin tarkasti eri työtiloihin spesifin attribuutin, kuten toimipisteen tai maan perusteella, tämä onnistuu seuraavalla tavalla.

Tämä määritys voi olla käytössä Entra-ryhmämäärittelyn lisänä. Integraatio tarkistaa Attribuutin ensin ja sitten vasta Entra-ryhmätiedon. Ryhmäarvoa ei oteta lainkaan huomioon, jos päätoiminen työtila löytyy attribuutin perusteella.

Jatketaan vaiheen 5 määrityksiä lisäämällä loppuun vielä mukautettu attribuutti, urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace, joka määrittää käyttäjän ensisijaisen työtilan.

Attribuutin lisääminen skeemaan

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

Workspace-mäppäyksen lisääminen

1. Palaa Attribute Mapping -näkymään ja tarkista oletusmäppäykset.
2. Lisää uusi workspace-mä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 ensisijaisen fyysisen sijainnin tai 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
3. Valitse OK.
4. Valitse Save.

Määritys Studiossa

1. Avaa Systam Studio ja siirry kohtaan Laajennukset → Microsoft Entra ID
2. Rullaa alas kohtaan "Aseta ensisijaisen työtilan attribuuttimääritykset"
3. Paina "Lisää määritys" ja lisää tähän arvo, joka aiemmin määritellyssä kentässä voisi olla
4. Valitse minkä työtilan haluat ensisijaiseksi valinnaksi ja tallenna muutokset
5. Toista, kunnes jokainen haluamasi arvo on määritelty
6. Valmis! Siirry vaiheeseen 7

Vaihe 7: Testaa ja käynnistä synkronointi

Testaa yksittäinen käyttäjä

• Valitse Provision on demand.
• Valitse testikäyttäjä.
• Suorita toiminto.

Ota automaattinen synkronointi käyttöön

• Aseta Provisioning status arvoon On.
• Valitse haluttu laajuus.

Seuraa tilannetta

• Tarkista provisiointilogit.
• Seuraa provisioinnin statusta.

Yleisimmät virheet provisiointilokeissa

Microsoft Entra ID yrittää epäonnistuneet toiminnot automaattisesti uudelleen seuraavassa synkronointikierroksessa, joten korjattu mappaus 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 yritystä (enterprise application) Microsoftin Entra-tenantistanne — jos ette enää tarvitse sitä siellä, poistakaa se itse Entran admin centeristä.

Nykyiset rajoitteet

• Ryhmien nimien kannattaa olla uniikkeja Entra ID:ssä. Provisiointi täsmää olemassa oleviin ryhmiin nimen perusteella, joten samannimiset ryhmät voivat johtaa väärään ryhmämappaukseen.
• Synkattavia kenttiä ei voi ohittaa käyttäjäkohtaisesti. Microsoft Entra ID ylikirjoittaa ne aina seuraavassa synkronoinnissa.

Lisätietoja

• Managing user account provisioning for Enterprise Apps
• What is application access and single sign-on with Microsoft Entra ID?