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.

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. Systamissa Organization Owner -rooliin nimetyt käyttäjät ovat suojattuja. Jos näitä käyttäjiä yritetään päivittää tai poistaa SCIMin kautta, provisiointilokeihin tulee 403 Forbidden -virhe.
• 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. Jos Systamissa on jo käyttäjä samalla sähköpostiosoitteella, provisiointi linkittää olemassa olevan tilin tenantin SCIM-tietoihin. Muussa tapauksessa Systam luo uuden 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

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

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.

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

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.

Lisätietoja

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