Tämä artikkeli sisältää asiakkaalle ohjeet Microsoft Entra ID:n (aiemmin Azure AD) määrittämiseksi todennukseen OpenID Connectia (OIDC) käyttäen Matrix42 Pro- ja IGA-ratkaisuissa. 

Yleensä tämän määrityksen tekee asiakkaan Entra ID- tai todennusasiantuntija. Sen toteuttamiseen ja testaamiseen ei pitäisi kulua enempää kuin puoli päivää. Huomaa, että osa kuvakaappauksista saattaa näyttää erilaisilta asiakkaan Entra ID:ssä.

Nämä ohjeet koskevat kaikkia Matrix42 Pro- ja IGA-ratkaisuja (esim. ITSM, IGA, HR), jotka käyttävät Secure Access -komponenttia todennukseen.

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

Kuinka määrittää Entra ID OpenID Connectia (OIDC) varten

Application Registration

Asiakkaan on määritettävä oma Entra-vuokraajansa (tenant) siten, että Matrix42 Security Access -komponentti voi hakea käyttäjätili- ja ryhmätiedot. Määritys tehdään kirjautumalla Entra ID -konsoliin (aiemmin Azure AD). 

1. Siirry kohtaan https://entra.microsoft.com ja valitse kirjautumisen jälkeen App registrations (HUOM! Tämä ei ole "Enterprise Application", joka luodaan toista polkua pitkin, mutta se saatetaan sekoittaa tähän).
   
2. Valitse New registration.
   
3. Anna sovellukselle nimi.
4. Valitse oikea Supported Account Types käyttötapauksestasi riippuen. Tämä on erittäin tärkeä valinta, joten jos et ole varma, mitä valita, kysy neuvoa jollain, jolla on enemmän kokemusta tästä määrityksestä.
   1. Vaihtoehto 1 – suositeltu useimmissa tapauksissa: Jos rakennat perusmääritystä, jossa kaikki Matrix42-järjestelmään kirjautuvat käyttäjät kuuluvat omaan vuokraajaasi (tenant), valitse Accounts in this organizational directory only (<this tenant> only - Single tenant)
   2. Vaihtoehto 2: – Tässä käyttötapauksessa olet varma, että haluat myös muiden vuokraajien (tenant) käyttäjien pystyvän kirjautumaan Matrix42-ratkaisuihisi (sinulla on esimerkiksi Multi service provider, MSP). 
      Valitse: Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). 
      1. Huomaa, että käytettäessä multitenant-sovellusta, Azure ei lähetä ryhmiä nimillä, vaan lähettää ryhmät aina vain ID-tunnisteina. 
      2. Huom! Jos valitset tämän multitenant-vaihtoehdon, Matrix42:n on määritettävä kaikki sallitut vuokraajat (tenant) Identity providers -asetuksen Issuer-kenttään pilkuilla erotettuna luettelona.
         
5. Kohdassa Redirect URI, valitse Web alustaksi ja anna sitten Secure Accessin reply-URL-osoite (tämä voidaan lisätä myöhemmin, jos Matrix42 ei ole vielä toimittanut URI-osoitetta).
   
6. Valitse Register.

Kuinka asettaa Redirect URI sovelluksen luomisen jälkeen

1. Siirry kohtaan https://entra.microsoft.com ja valitse kirjautumisen jälkeen App registrations.
2. Etsi ja avaa luomasi sovellus.
3. Valitse vasemmasta valikosta Authentication.
   
4. Redirect URI:n lisääminen
   Platform type: Web
   Redirect URI: URL-osoite, jonka sait Matrix42:n OpenID Connect v1.0 Identity providers -kohdasta Redirect URI -attribuutti.
   

Certificates & Secrets

Secure Access tukee suojattua yhteyttä käyttäen Entra ID käyttämällä Client Secrets.

Client Secret -ohjeet

1. Microsoft Entra -hallintakeskuksessa, kohdassa App registrations, valitse sovelluksesi.
   
2. Valitse Certificates & secrets > Client secrets > New client secret.
   
3. Lisää kuvaus client secretillesi.
4. Valitse secretille voimassaoloaika tai määritä mukautettu kesto.
   1. Client secretin voimassaolo on rajoitettu enintään 730 päivään / 24 kuukauteen (kaksi vuotta). Et voi määrittää mukautettua voimassaoloaikaa, joka on pidempi kuin 730 päivää / 24 kuukautta.
   2. Microsoft suosittelee asettamaan voimassaolon päättymispäivän, joka on alle 365 päivän / 12 kuukauden päässä.
5. Valitse Add.
   
6. Tallenna secretin arvo käytettäväksi asiakassovelluksesi koodissa.
   

   Tätä secretin arvoa ei näytetä enää uudelleen tämän sivun jälkeen. Jos secretin arvo katoaa / sitä ei ole tallennettu, ainoa tapa saada uusi arvo on määrittää uusi secret.

    
   

Token Configuration

Perusmuotoista OpenID Connect (OIDC) -kirjautumisen toimimiseksi sinun ei tarvitse lisätä Optional claim.

Email-claimin lisääminen

On kuitenkin erittäin suositeltavaa lähettää myös käyttäjän sähköpostiosoite kohteesta Entra kohteeseen Secure Access. Sieltä käyttäjän sähköpostitieto lähetetään Matrix42 Pro- ja IGA-ratkaisuun. Tämä tarvitaan Chat-toiminnallisuutta varten (jos sähköposti puuttuu, chat ei ole käytettävissä). 

Tätä varten sinun on lisättävä email-claim:

1. Siirry kohtaan Token configuration, napsauta Add optional claim lisätäksesi email-claimin.
2. Valitse token-tyyppi: ID and Claim: email
   

Add Groups Token

Valinnaisesti, jos haluat lähettää myös käyttäjän ryhmätiedot kohteesta Entra kohteeseen Secure Access, sinun on lisättävä groups-claim. 

Kohdassa Secure Access voit käyttää groups-claim-tietoa laskeaksesi userLevel ja esm roolit:

1. Siirry kohtaan Token configuration, napsauta Groups-claimin lisääminen.
2. Valitse oikeat ryhmätyypit sen mukaan, minkä tyyppisiä ryhmiä haluat lähettää Secure Access -komponentille. 
   1. Yleensä Security groups riittää, mutta se riippuu siitä, miten asiakkaat ovat Entra ID ryhmät on suunniteltu.
3. Valitse Tokenin ominaisuuksien mukauttaminen tyypin mukaan.
   1. Huomaa, että oletusarvo on Group ID, mutta Matrix42 Professional- ja IGA-ratkaisussa sAMAccountName on yleensä parempi vaihtoehto, jos ryhmiä ei luoda suoraan Entra.
      
   2. Jos haluat lähettää pilviryhmät claimissa muodossa groupIDs, valitse vain "group type" ja valitse IDs.
      

API Permissions

API-käyttöoikeudet myönnetään vähimmäistasoisena käyttöoikeusjoukkona. Tämä tarkoittaa, että Secure Access -sovellukselle sallitaan vain välttämätön pääsy.

1. Valitse sivupalkista “API permissions”.
2. Valitse kyseiseltä sivulta “Add a permission”. 
   1. Sinulla pitäisi jo olla Microsoft Graph > User.Read lisättynä, voit jättää tämän ennalleen.
      
3. Valitse "Microsoft Graph".
4. Valitse Delegated permissions
   
5. Vieritä alaspäin ja valitse tarvittavat käyttöoikeudet.
   1. Käyttöoikeus: User.Read, tyyppi: Delegated
   2. Käyttöoikeus: email, tyyppi: Delegated
      1. Tämä on tarpeen vain, jos email-claim on määritetty ja vaaditaan.
6. Napsauta “Add permissions”.
7. Nyt määritetyt käyttöoikeudet (Configured permissions) näytetään.
   

Valinnainen: Entra ID:n määrittäminen lähettämään federoitu/vierailija-UPN OIDC ID-tokeneissa

Tämä määritys suositellaan tehtäväksi, jos sallit vierailijakäyttäjien kirjautumisen.

1. Avaa App Registration.
2. Valitse luomasi sovellus (Riku M42 native connectors kuvakaappauksessa). 
3. Siirry kohtaan Token configuration
4. Valitse Add optional claim.
5. Valitse Token type tyyppinä ID ja Claim tyyppinä upn
6. Napsauta Add lisätäksesi kyseisen tokenin.
   
7. Ponnahdusikkuna avautuu, valitse valintaruutu ja napsauta Add.
   
8. Muokkaa juuri määritettyä claimia valitsemalla Edit -vaihtoehto kolmen pisteen takana:
   
9. Aseta Ulkoisesti todennettu kohteeseen Yes ja Save.

Federoitujen/vierailijakäyttäjien määritys on nyt valmis. 

Heidän upn-tietonsa näytetään ID-tokenissa tässä muodossa: <upn>_<homedomain>#EXT#@<resourcedomain> esimerkiksi:  john_contoso.com#EXT#@contoso.onmicrosoft.com

Tämä asetus ei vaikuta sisäisten käyttäjien upn-muotoon, se on edelleen normaalissa upn-muodossa, esimerkiksi: john.doe@contoso.com

Asiakkaan toimitettavat tiedot

Toimita seuraavat tiedot Matrix42:lle, jotta ne voidaan määrittää Secure Accessiin.

Tiedot	Esimerkki
Application (client) ID Luomasi sovellusrekisteröinnin (app registration) ID Näkyy sovelluksesi yleiskatsauksessa	56cf0dabc-1a1b-12ca-3bca-bca4bc56a78b
Directory (tenant) ID Entra-vuokraajan (tenant) ID	abc1fb23-dd24-5a67-8b91-1a123ab123a12
Discovery URL in v1.0 format
Secret	Toimita secretin arvo Matrix42:lle turvallista toimitustapaa käyttäen.