Miten todennus määritetään Entra ID SSO:lle käyttäen OpenID Connectia (OIDC)?

Tässä artikkelissa kuvataan ohjeet Secure Access -komponentin määrittämiseen, jotta se voi todentaa asiakkaan loppukäyttäjät Matrix42 Pro- ja IGA-ratkaisuihin (kuten esimerkiksi IGA, ITSM jne.) käyttäen Entra ID (Azure AD) -kertakirjautumista (Single Sign-On) OpenID Connectilla (OIDC).

Kaikki alla olevat vaiheet ovat pakollisia, ellei toisin erikseen mainita valinnaiseksi.

Asiakasohjeet: https://docs.efecte.com/customer-instructions/efecte-secure-access-customer-instructions-for-entra-id-configuration-openid

Vaiheittaiset ohjeet

1. Matrix42 asentaa https-juurisertifikaatin Secure Accessiin.
   

   Jos Microsoftiin liittyviä juurisertifikaatteja ei ole asennettu, discovery endpoint -osoite ei toimi.

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

    
2. Kirjaudu ESA:n hallintakonsoliin (käyttäjällä main.admin) siirtymällä osoitteeseen https://<YOUR_ENVIRONMENT_FQDN>/auth/admin 
   tai partner.admin -käyttäjällä osoitteeseen https://<YOUR_ENVIRONMENT_FQDN>/auth/admin/<YOUR_ENVIRONMENT_REALM>/console/.
3. 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.
   
    
4. Avaa Identity Provider -asetukset vasemmasta sivupaneelista:
   
5. Lisää Identity Provider.
   1. Avaa Identity Providers vasemmasta valikosta ja napsauta Add provider, valitse OpenID Connect V1.0
   2. Aseta Use discovery endpoint arvoon On.
   3. Lisää URL-osoite kenttään Discovery endpoint. Tämän URL-osoitteen tulee olla v1-muodossa: https://login.microsoftonline.com/[TENANT]/.well-known/openid-configuration. Korvaa [TENANT] asiakkaan Entra-vuokralaisen Directory (tenant) ID-arvolla.
   4. Aseta Client authentication -asetukseksi Client secret sent as post. 
      1. Tätä määritystä varten tarvitset Client secret -arvon asiakkaan Entra ID -vuokralaisen sovelluksesta, katso lisätietoja artikkelista Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC) . 
         
   5. Aseta asiakkaan Entran Application (client) ID kenttään Client ID attribute.
   6. Aseta Entra-sovelluksen secret-arvo kenttään Client Secret attribute.
      

      Jos Entra-sovellus on määritetty multidomain -käyttöön (katso Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC)), kaikki sallitut verkkotunnukset tulee asettaa issuer -attribuuttiin tälle Identity Providerille, muuten on turvallisuusriski, että joku ei-toivotusta vuokralaisesta voi kirjautua portaaliin. 

      Voit lisätä useita vuokralaisia kenttään issuer pilkulla erotettuna; älä käytä välilyöntejä.

      Esimerkki issuer -arvosta monivuokralaismäärityksessä:

      https://sts.windows.net/cbd5fb36-aad31-4d23-9b42-2f11dfaa5b33/,https://sts.windows.net/cbd5fb36-aad31-4d23-9b42-2f11dfaa5b52/,https://sts.windows.net/cbd5fb36-aad31-4d23-9b42-2f11dfaa5b44/

       
   7. Sinun OpenID Connect V1.0 Identity Providerin pitäisi näyttää tältä ennen kuin napsautat “Add”:
      
   8. Kun olet lisännyt tämän Identity Providerin, sinun tulee vielä asettaa nämä asetukset:
      1. Prompt: Login
      2. Accept prompt=none forward from client: On
         
      3. Validate Signatures: On
      4. Use JWKS URL: On
      5. JWKS URL: https://login.microsoftonline.com/common/discovery/keys
         
      6. Trust email: On
      7. First login flow override: first broker login
      8. Post login flow: None
      9. Do not store users: On
         1. On suositeltavaa asettaa “Do not store users” On-tilaan, muuten saattaa syntyä ongelmia, kun käyttäjän tiedot muuttuvat Entra ID:ssä. Voit kuitenkin pitää tämän Off -tilassa testaus- ja virheenkorjausvaiheessa, se helpottaa ongelmien selvittämistä.
            
6. Tallenna Identity provider-määrityksesi.
7. Luo tarvittavat mapperit kohteeseen Identity provider.
   1. Avaa juuri luomasi identity provider ja siirry Mappers -välilehdelle:
      
      1. Username - Tämä on tärkein mapperi, koska sitä käytetään Matrix42 Pro- ja IGA-kirjautumisprosessissa.
         
         
         1. Jos tämä mapperi puuttuu: kun käyttäjä yrittää kirjautua, hän näkee näytön, jossa häneltä pyydetään kirjautumistietoja ja käyttäjätunnus näkyy oudonnäköisenä merkkijonona.
      2. Email - Tämä claim (tieto) ei tule oletuksena Entralta, joten tarkista, että asiakas on määrittänyt tämän mukautetun email-claimin Entraan ohjeen mukaisesti: Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC).
         
8. Valinnainen ryhmien mappaus - Tämä claim (tieto) ei tule oletuksena Entralta, joten tarkista, että asiakas on määrittänyt tämän groups-claimin Entraan ohjeen mukaisesti: Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC).
   1. 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”.
      
9. Jos lisäsit kaikki 3 mapperia, mapperiluettelosi pitäisi nyt näyttää tältä (muista, että sinulla tulee olla vähintään username_mapper, ja on erittäin suositeltavaa, että sinulla on myös email_mapper):
   
10. Avaa Clients -asetukset vasemmasta työkalurivistä:
    1. Valitse rivi, joka liittyy Shibboleth -todennukseen (esimerkiksi: https://customer.efectecloud-test.com/shibboleth), jonka tyyppi on SAML.
    2. Avaa Client scopes-välilehti työkalurivistä.
    3. Avaa linkki, joka päättyy /shibboleth-dedicated.
    4. Tarkista, että nämä mapperit löytyvät (jos sinulla on useampia mappereita, tarkista osio “userLevel mapper information”):
       
    5. userLevel -mapperin tiedot – jos seuraava userLevel -mapperi on listattu: com:efecte:esm:userLevel:
       
       1. Avaa se napsauttamalla sitä.
       2. Arkkitehtuurisuunnittelusta riippuen saatat haluta tai olla haluamatta laskea userLevel kohteessa Secure Access.
       3. Jos et halua, että Secure Access laskee userLevel -arvon puolestasi, voit joko poistaa tämän userLevel -mapperin tai muuttaa sen SAML Attribute Name -arvoa niin, ettei alusta enää tunnista sitä, esimerkiksi lisäämällä tekstin _Disabled sen loppuun.
       4. Jos haluat, että Secure Access laskee userLevel-arvon, niin SAML Attribute Name tulee olla com:efecte:esm:userLevel
          
11. Kaikki peruskonfiguraatio pitäisi nyt olla tehty, joten testaa todennus Matrix42 Pro- tai IGA-portaaliin sekä Agent UI:hin. 
    1. Muista testata myös uloskirjautuminen. Ja kirjaudu uudelleen uloskirjautumisen jälkeen varmistaaksesi, että uloskirjautuminen onnistui.

Ota automaattinen kirjautuminen käyttöön – valinnainen, jos automaattista SSO-kirjautumista ei tarvita 

Jos asiakas haluaa ohjata käyttäjät suoraan SSO-tarjoajalle (Secure Accessin kirjautumissivua ei näytetä lainkaan), 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.
   1. Huom! Jos et luo kopiota vaan muokkaat sen sijaan sisäänrakennettua browser-flow'ta, seuraava Secure Access Keycloak -version päivitys saattaa ylikirjoittaa muutoksesi.
      
5. Aseta Identity Provider Redirector arvoon Alternative pudotusvalikosta:
   
   1. HUOM! Jos Identity Provider Redirector puuttuu browser-vaiheista, voit lisätä sen täältä:
      
6. Määritä oletusarvoinen identity provider painamalla muokkauspainiketta (hammasratas). 
   1. Alias = määrityksen nimi. 
   2. Default Identity Provider = olemassa olevan Identity Provider-arvo. Tarkista alias omasta Identity Provider-arvostasi.
      
      1. Määritä tämä Alias kenttään Default Identity Provider -attribuuttiin valitsemalla hammasratas:
         
      2.  Kirjoita nyt uusi Alias -nimi siihen. Aseta nyt Alias -arvo Identity Provider -lähteestäsi vastaamaan Default Identity Provider -attribuuttia ("oidctest" kuvakaappauksessa):
         
7. Muuta Identity Providerin Prompt -asetuksia Advanced-osiosta tarvittaessa:
   
   1. Unspecified - Tämä vaihtoehto jättää päätöksen Entra ID:lle.
   2. None - Tämä vaihtoehto tekee aina Entra ID -kirjautumisen, eikä Entra ID -tunnuksia voi käyttää manuaalisesti.
   3. 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.
   4. 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.
   5. Select_Account - Käyttäjä voi valita tilin selaimen sisäisistä istunnoista (kirjautumista ei tarvita).
      
8. Tarkista Secure Access -flow't: Authentication -> Flows. 
   1. Jos Browser flow käyttää joko Efecte Login tai Built-in Browser-flow'ta, vaihda uusi flow'si kohteeksi Browser flow seuraavassa vaiheessa.
      
      
       
   2. Etsi uusi flow'si (tässä tapauksessa nimeltään M42 browser SSO) ja napsauta sen kolmea pistettä ja valitse Bind flow:
      
   3. Valitse "Browser flow" ja napsauta Save.
      
9. ESM:n uloskirjautumis-URL:t ja portaalin uloskirjautuminen
   1. Jos et määritä näitä oikein, uloskirjautumisen jälkeen Secure Access yrittää kirjautaa käyttäjän automaattisesti takaisin Matrix42 Pro:hon ja IGA:han (tämä voi pakottaa käyttäjän uloskirjautumis-sisäänkirjautumis-silmukkaan). 
      1. Uloskirjautumis-URL voi olla esimerkiksi asiakkaan intranet-osoite tai mikä tahansa sivu, jota asiakas haluaa käyttää.
      2. ESM:n uloskirjautumis-URL-asetus löytyy kohdasta Maintenance / System Settings / Edit platform settings.
   2. ESM:n uloskirjautumis-URL-asetus löytyy kohdasta Maintenance - System Settings - Edit platform settings - sessionterminator.redirecturl
      1. Asetuksen muoto on (anna uloskirjautumissivun osoite kohdan ?return=jälkeen):  
         <your matrix42 system url>/Shibboleth.sso/Logout?return=https://companyintranet.companyexample.com
      2.  Koko asetusarvo näyttäisi tältä:
         
   3. Portaalin (ssc) osalta uloskirjautumis-URL-asetus on ssc-hallinnassa: <your matrix42 system url>/ssc/admin, kohdassa Setting - General Setting - Sign-out page:
      
      1. Suosittelemme käyttämään seuraavaa muotoa portaalin asetuksissa: 
         /Shibboleth.sso/Logout?return=https://mycompanyintra.company.com
      2. Huomaa, että portaalin Sign-out page -asetus on vuokralaiskohtainen, joten jokaisella vuokralaisella voi olla oma uloskirjautumissivunsa tarvittaessa.
10. Testaa automaattinen kirjautuminen ja testaa myös uloskirjautuminen.