1. Asenna https-juurisertifikaatti Secure Accessiin (tämän voi tehdä vain Matrix42)
Lisää Entra ID:hen liittyvät https-sertifikaatit Secure Access -komponenttiin. Näitä sertifikaatteja tarvitaan suojatun yhteyden muodostamiseen Entra ID:n ja Secure Access -järjestelmien välille.

Noudata ohjetta luvussa “Add Microsoft related certificates to Secure Access”: https://docs.efecte.com/configure-authentication/download-and-install-certificates-to-secure-access-esa
 

2. Kirjaudu Secure Accessiin luodaksesi SAML v.2.0 Identity Providerin
Kirjaudu ESA:n hallintakonsoliin (käyttäjällä main.admin) osoitteessa https://<YOUR_ENVIRONMENT_FQDN>/auth/admin 
tai partner.admin-käyttäjällä osoitteessa https://<YOUR_ENVIRONMENT_FQDN>/auth/admin/<YOUR_ENVIRONMENT_REALM>/console/
 

Valitse oikea realm valitsemalla ensin vasemmasta yläkulmasta Manage realms ja napsauttamalla sitten realmin nimen linkkiä. Realmin valinnan käyttöliittymä muuttui julkaisussa 2026.1.2 aiempiin verrattuna.

 

Valitse valikosta Identity providers

3. Lisää SAML v2.0 Identity Provider

4. Kopioi ESA:n määritysnäytöltä Redirect URI -kohdassa oleva URL-osoite ja toimita se asiakkaalle (se tulee määrittää heidän Entra-sovellukseensa redirect URI:na).



5. Hae IdP-metatiedot Entrasta

Aseta Use entity descriptor On ja aseta SAML entity descriptor -arvoksi URL, jonka asiakas antoi Entrastaan (App Federation Metadata URL)

 

6. Muista tarkistaa “Allowed Clock Skew” -asetus ja määritä se esimerkiksi arvoon 3 tai 5 sekuntia. Oletusarvo on '0' (mikä tarkoittaa, että mikä tahansa ero ESA:n sisäisen kellon ja Identity Providerin kellon välillä aiheuttaa virheen: “Assertion expired”.




 

7. Kun yllä oleva määritys on tehty, ESA:n kirjautumissivulle ilmestyy uusi kirjautumisvaihtoehto

8. Testaa kirjautuminen ja uloskirjautuminen eri käyttäjillä

1. SAML-pohjaisen kirjautumisen käyttöönottamiseksi ADFS:lle asiakkaan tulee määrittää AD näillä ohjeilla.
    
2. Asenna https-juurisertifikaatti Secure Accessiin (tämän voi tehdä vain Matrix42).
   Lisää Active Directory Federation Service (AD FS) -liittyvät https-sertifikaatit Secure Access -komponenttiin. Näitä sertifikaatteja tarvitaan suojatun yhteyden muodostamiseen Entra ID:n ja Secure Access -järjestelmien välille.  
   1. Noudata ohjetta luvussa “Add Microsoft related certificates to Secure Access”: https://docs.efecte.com/configure-authentication/download-and-install-certificates-to-secure-access-esa
       

      Huomaa

      Jos AD FS:ään liittyviä juurisertifikaatteja ei ole asennettu, metatietojen tuominen AD FS -URL:sta ei toimi (Use entity descriptor ja SAML entity descriptor -attribuutit).

      Myöskään koko todennus ei toimi ilman näitä juurisertifikaatteja.

       
3. Kirjaudu Secure Accessiin luodaksesi SAML v.2.0 Identity Providerin
   Kirjaudu ESA:n hallintakonsoliin (käyttäjällä main.admin) osoitteessa https://<YOUR_ENVIRONMENT_FQDN>/auth/admin 
   tai partner.admin-käyttäjällä osoitteessa https://<YOUR_ENVIRONMENT_FQDN>/auth/admin/<YOUR_ENVIRONMENT_REALM>/console/
4. Valitse oikea realm yläkulmasta
   
5. Valitse valikosta Identity providers
   
6. Lisää SAML v2.0 Identity Provider
   
7. Määritä Identity Provider:
   • Backchannel Logout 
     • Backchannel logout on mekanismi, jonka tarkoituksena on varmistaa, että kun käyttäjä kirjautuu ulos identity providerista (IdP/ESA), hänet kirjataan ulos myös kaikista siihen liittyvistä relying party -tahoista (RP) tai sovelluksista.
     • Jos “Want AuthnRequests signed” on käytössä ADFS:ssä, backchannel logout on pakollinen.
   • HTTP-POST Binding Response
   • HTTP-POST Binding for AuthnRequest
   • Validate Signature
     
     
     
     
     
     
      
8. Jos AD FS -instanssille lähetettävien todennuspyyntöjen odotetaan olevan allekirjoitettuja, ota käyttöön Want AuthnRequests Signed -asetus. Tällöin SAML Signature Key Name -kenttä tulee näkyviin. Aseta SAML Signature Key Name -kentän arvoksi CERT_SUBJECT. AD FS odottaa, että allekirjoitusavaimen nimivihje on allekirjoitussertifikaatin subject-kenttä.
   
    
9. Jos AD FS on määritetty vastaamaan name ID:llä Windows Domain Qualified Name -muodossa, aseta NameID Policy Format -kenttä sen mukaisesti.
   

Jotta käyttäjä voidaan välittää ESA:sta muihin järjestelmiin (ESM, ESS, IGA), ESA:n tulee tuntea käyttäjän konteksti. Tätä varten ESA tallentaa hieman metatietoa, joka kuvaa jokaista kirjautumista yrittänyttä käyttäjää.

Tämän voi ratkaista valmistelemalla automaation, joka mappaa automaattisesti Entralta tulevat tiedot ESA-käyttäjän vaatimiin attribuutteihin.

1. Kirjaudu ESA-hallintaan (main.admin) osoitteeseen domain.com/auth
   
    
2. Valitse oikea realm yläkulman valikosta
   
   
3. Avaa Identity Provider -asetukset vasemmasta sivupaneelista
   
    
4. Siirry Mappers-osioon. Tässä on esimerkki siitä, miten ne tulisi määrittää.
   
    

• Käytä sähköpostille mapperityyppiä Attribute Importer.
  Mappaa käyttäjän email-attribuutti kohteeseen http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  
• Käytä käyttäjätunnukselle mapperityyppiä Username Attribute Importer.
  Mappaa käyttäjätunnusattribuutti username kohteeseen http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  
  Oletuksena Microsoft Entra ID (aiemmin Azure AD) täyttää tyypillisesti SAML http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name -attribuutin käyttäjän User Principal Namella (UPN), kuten user@contoso.com. Tämä claim toimii yksilöllisenä tunnisteena SSO-tilanteissa. Username-attribuutin arvo lähetetään sen jälkeen urn:mace:dir:attribute-def:principal-claimissa Matrix42 Shibboleth -komponentille, jotta oikea käyttäjä tunnistetaan ess-, ssc- ja itsm-palveluissa.
  
  
• Käytä sukunimelle mapperityyppiä Attribute Importer.
  Mappaa käyttäjän lastName-attribuutti kohteeseen http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  
• Käytä etunimelle mapperityyppiä Attribute Importer.

Mappaa käyttäjän firstName-attribuutti kohteeseen http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

 

Valinnainen groups_mapper

Jos groups-mapperi tarvitaan, lisää Groups-mapperi Identity Providerin asetuksiin.
Mappaa käyttäjän attribuutti groups kohteeseen http://schemas.microsoft.com/ws/2008/06/identity/claims/groups 

Noudata myös tätä ohjetta mapataksesi groups-claimit ESM-rooleiksi: https://docs.efecte.com/configure-authentication/configure-esa-to-use-esm-roles luku: How to configure ESA to assign ESM roles from Entra ID.

Näiden vaiheiden jälkeen:

• Varmista, että ESM:ään on luotu Person-tietokortti.
• Varmista, että Personilla on oikea arvo attribuutissa servlet.auth.person.uid.attribute.code – sitä käytetään myöhemmin kirjautumisnimenä.

Kun yllä olevat vaiheet on tehty, ESM luo kirjautumisprosessin aikana puuttuvan User-objektin, linkittää sen jo olemassa olevaan Personiin ja siirtyy ITSM:n aloitussivulle annetulle roolille.

HUOM! Jos käyttäjiä ei ole syytä tallentaa ESA:aan, voit valita Do not store users identity providerissa. Tämä tarkoittaa, ettei käyttäjiä tallenneta ESA:aan. Tätä voidaan käyttää esimerkiksi silloin, kun käyttäjätieto sisältää arkaluontoista tietoa, kuten henkilötunnuksen. Huomaa, että tämän jälkeen käyttäjää ei enää näy ESA:ssa, mutta mapperit toimivat normaalisti. Oletuksena käyttäjät tallennetaan ESA:aan. 

Vaihtoehtoja on kaksi:

1. Asenna SAML-viestien purkaja selaimeesi. SAML-purkajia on saatavilla selainlaajennuksina (esim. SAML Tracer Firefoxille, SAML Chrome Panel Google Chromelle).
   
   TAI
2. Aseta ESA:n loki DEBUG-tasolle
   
   
   1. Muokkaa ESA-kontin sisällä tätä tiedostoa:
      /etc/containerpilot/jobs/esa/start_primary
      
      muuta tästä:
      --log-level=INFO
      
      tähän:
      --log-level=DEBUG
      
       
   2. sammuta sen jälkeen java-prosessi:
      $ pkill java
      
       
   3. muutosten peruuttamiseksi vaihda “--log-level” takaisin arvoon INFO ja sammuta sen jälkeen java-prosessi ($ pkill java)
      
      HUOM! jos ESA-kontti käynnistetään uudelleen, kaikki muutokset peruuntuvat – tässä tapauksessa debug-taso palautuu takaisin INFO-tasolle)
      
       

ESA:n loki löytyy ESM:n käyttöliittymästä. 

1. Kirjaudu Efecteen root-tason käyttäjänä
2. Valitse IGA-moduuli
3. Valitse EPE/ESA-määritys
4. Valitse ESA logs ja keycloak.log
   

Tärkeimmät tarkistettavat asiat SAML-viesteistä

SAML-viesti identity providerin ja Secure Accessin välillä

• Sisältävätkö claimit kaiken tiedon, jota odotat saavasi Identity Providerilta

SAML-viesti Secure Accessin ja ess-/ssc-/itsm-ratkaisujen välillä
Sisältävätkö claimit oikeat arvot näissä claimeissa:

• urn:mace:dir:attribute-def:principal (tulee sisältää käyttäjän käyttäjätunnus)
• com:efecte:esm:roles (tulee sisältää käyttäjän roolit), jos vaatimuksena on hakea käyttäjän ryhmäjäsenyydet Identity Providerilta ja käyttää niitä käyttäjän ESM-rooleihin liittämiseen
• com:efecte:esm:userLevel (tulee sisältää käyttäjän userlevel, esimerkiksi Normal). Jos vaatimuksena on hakea userlevel Identity Providerilta ja käyttää sitä käyttäjän userlevelinä ESM:ssä
• com:efecte:esm:firstName
• com:efecte:esm:lastName
• com:efecte:esm:email

Jos asiakas haluaa ohjata käyttäjät SSO-tarjoajalle (Secure Accessin kirjautumissivua ei tarvitse nähdä ensin), tee seuraava määritys Secure Accessissa. 

1. Valitse oikea realm vasemman yläkulman pudotusvalikosta

2. Avaa Authentication vasemmasta sivupaneelista

3. Valitse browser (Build-in) -riviltä kolme pistettä vasemmalta ja valitse duplicate

4. Anna sille nimi ja kuvaus, ja napsauta sitten Duplicate

Huomaa! Jos et luo kopiota vaan muokkaat sen sijaan sisäänrakennettua browser-flow'ta, seuraava ESA:n Keycloak-version päivitys saattaa ylikirjoittaa muutoksesi.

5. Aseta Identity Provider Redirector arvoksi 'Alternative'

HUOM! Jos Identity Provider Redirector puuttuu browser-vaiheista, voit lisätä sen täältä:

4. Määritä oletusarvoinen identity provider “wheel config button” -painikkeesta. Alias = määrityksen nimi. Default Identity Provider = jotta ohjaus tapahtuu automaattisesti identity provideriin, aseta arvoksi kyseisen identity providerin alias.

Tarkista alias identity providerista, jonka olet luonut SAML:lle tämän ohjeen aiemmissa vaiheissa

Määritä tämä alias kohteeseen Default Identity Provider -attribuutti valitsemalla hammasratas ja antamalla sille uusi alias-nimi, ja aseta identity providerin alias kohteeseen Default Identity Provider -attribuutti. Vaatimus: Alternative.

5. Muuta Identity Providerin prompt -asetuksia Advanced-osiosta tarvittaessa. Kysy oikea arvo asiakkaalta sen mukaan, miten he haluavat automaattisen kirjautumisen toimivan.

• Unspecified
  Tämä vaihtoehto jättää päätöksen Entra ID:lle
• None
  Tämä vaihtoehto tekee aina Entra ID -kirjautumisen, eikä Entra ID -tunnuksia voi käyttää manuaalisesti
• Consent
  Yleensä ei käytetä. Vaatii käyttäjää antamaan suostumuksen pyydettyihin käyttöoikeuksiin. Jos käyttäjä on jo aiemmin antanut suostumuksen, mitään vuorovaikutusta ei tapahdu. Jos käyttäjä ei ole vielä antanut suostumusta, järjestelmä näyttää suostumusnäytön, jossa näkyvät sovelluksen pyytämät käyttöoikeudet.
• Login
  Oletus. Pakottaa käyttäjän kirjautumaan sisään, vaikka hän olisi jo todennettu. Tämä varmistaa, että käyttäjä todennetaan uudelleen ja uusi istunto muodostetaan.
• Select_Account
  Käyttäjä voi valita tilin selaimen sisäisistä istunnoista (kirjautumista ei tarvita)
  

6. Tarkista ESA-flow't: Authentication -> Flows. Jos Efecte Login on käytössä Browser flow'ssa tai Built-in Browser on käytössä Browser flow'ssa, vaihda uusi flow'si Browser flow'ksi vaiheessa 6.1 

6.1 Valitse uusi flow'si (tässä tapauksessa nimeltään M42 browser SSO) ja kolme pistettä, ja Bind flow

6.2 Valitse browser ja tallenna muutokset

7. Määritä portaalin ja ESM:n uloskirjautumis-URL:t

Jos et määritä näitä oikein, uloskirjautumisen jälkeen Secure Access yrittää kirjautaa käyttäjän automaattisesti takaisin Matrix42 Core-, Pro- ja IGA-ratkaisuihin (käyttäjä voi päätyä uloskirjautumis-sisäänkirjautumis-silmukkaan). Uloskirjautumis-URL voi olla esimerkiksi asiakkaan intranet-osoite tai mikä tahansa sivu, jota asiakas haluaa käyttää.

ESM:n uloskirjautumis-URL-asetus löytyy kohdasta Maintenance / System Settings / Edit platform settings

Setting: sessionterminator.redirecturl    

Asetuksen muoto on <your matrix42 system url>/Shibboleth.sso/Logout?return=https://companyintranet.companyexample.com

 kuvakaappauksen mukaisesti, anna uloskirjautumissivun osoite kohdan ?return=

Portaalin (ssc) uloskirjautumis-URL-asetus on ssc-hallinnassa <your matrix42 system url>/ssc/admin  kohdassa Setting / General

Setting: Sign-out page

Portaalin Sign-out page -asetus on vuokralaiskohtainen, joten jokaisella vuokralaisella voi olla oma uloskirjautumissivunsa tarvittaessa.

8. Testaa automaattinen kirjautuminen ja testaa myös uloskirjautuminen

Automaattiseen kirjautumiseen liittyvät lisämääritykset, jos kumppanien tai asiakkaiden tarvitsee kirjautua Secure Access -hallintaan paikallisilla tai hakemistotileillä

Jos kumppanien tai asiakkaiden tarvitsee kirjautua https://YOUR_ENVIRONMENT_FQDN/auth/admin/YOUR_ENVIRONMENT_REALM/console/-osoitteella Secure Access -hallintaan samalla realmilla, jolle otit automaattisen kirjautumisen käyttöön, tee seuraavat vaiheet.

Edellytys:

• Luo “Browser flow” ilman automaattista kirjautumista, jos sinulla ei jo ole sellaista.

Varsinaiset vaiheet:

1. Valitse oikea realm -arvo, johon haluat sallia kirjautumisen customer.admin- tai partner.admin-tunnuksella
2. Valitse clients
3. Valitse security-admin-console client
4. Avaa advanced -välilehti
5. Aseta override-arvoksi “Browser Flow” flow, jossa ei ole automaattista kirjautumista (loit sen edellytys-vaiheessa)
6. Testaa kirjautuminen ja uloskirjautuminen customer.admin or partner.admin