Tässä artikkelissa on ohjeet Secure Access -komponentin määrittämiseen niin, että se pystyy todentamaan asiakkaiden loppukäyttäjät Matrix42 Pro ja IGA -ratkaisuihin (kuten esimerkiksi IGA, ITSM jne.) käyttäen Keycloakia identiteetintarjoajana.

Asiakkaan tekemät määritykset IdP Keycloakiin

Asiakkaan tulee luoda OpenID Connect -asiakas (Client) omaan IdP Keycloakiinsa, jotta se voi toimia Secure Accessin IdP:nä.

1. Kirjaudu IdP Keycloakiin
2. Valitse oikea Realm
3. Siirry kohtaan Clients
4. Create client
   Valitse asiakastyypiksi (client type) OpenID Connect
   Aseta kuvaava Client ID
   Napsauta Next

   

5. Aseta Client authentication arvoon On
   Napsauta Next

   

6. Aseta Valid redirect URIs ja Valid post logout redirect URIs

Aseta Valid redirect URIs kopioimalla Redirect URI Secure Accessin identiteetintarjoajasta (Identity provider), jonka luot seuraavassa luvussa. Tämä Valid redirect URI täytyy siis asettaa yhdessä Matrix42:n kanssa, kun he tietävät sen Secure Access -puolelta.

Aseta Valid post logout redirect URIs esimerkiksi yrityksesi etusivuksi.

Web origins -kentän pitäisi täyttyä automaattisesti; jos näin ei käy, aseta se manuaalisesti oikein.

Vaiheittaiset ohjeet

1. Lisää asiakkaan Keycloakin https-sertifikaatti Secure Access (ESA) -keystoreen, jotta Secure Access voi muodostaa yhteyden asiakkaan Keycloakiin. Tämän voi tehdä vain Matrix42:n henkilöstö, sillä siihen tarvitaan pääsy palvelimelle. Katso ohjeet: FAQs-dokumentista ESA - How to Add a Certificate to Secure Access.

   Jos tätä sertifikaattia ei asenneta ennen seuraaviin vaiheisiin siirtymistä, Secure Access ei pysty hakemaan tietoja IdP Keycloakista discovery endpoint -URL:n avulla.

2. Kirjaudu Secure Access (ESA) -pääkäyttäjätunnuksella (main.admin) osoitteeseen domain.com/auth/admin
3. Valitse oikea realm valitsemalla ensin vasemmasta yläkulmasta Manage realms ja sitten napsauttamalla realmin nimen linkkiä. Realmin valinnan käyttöliittymä muuttui julkaisussa 2026.1.2 aiempiin verrattuna.

   

4. Avaa Identity Provider -asetukset vasemmasta sivupaneelista

   

5. Lisää uusi tarjoaja valitsemalla Keycloak OpenID Connect

   

6. Nimeä identiteetintarjoaja (haluamallasi tavalla)

   

7. Lisää todennukseen tarvittavat URL-osoitteet.
   On suositeltavaa käyttää IdP Keycloakin discovery endpointia, jotta nämä URL-osoitteet täyttävät automaattisesti oikeilla arvoilla. Asiakkaan tulisi antaa tämä URL, joka on muotoa: https://customeridpkeycloak.com/auth/realms/REALMNAMEHERE/.well-known/openid-configuration
   Käyttääksesi discovery endpointia, aseta Use discovery endpoint arvoon On ja aseta oikea URL.

   

   Tämän jälkeen kyseiset URL-osoitteet täyttävät automaattisesti.

   

8. Valinnainen: Validate signatures -asetus voidaan ottaa käyttöön; asiakas toimittaa JWKS-osoitteen

   

9. Lisää Client secret ja salasana (asiakas toimittaa nämä IdP Keycloakista)

   

10. Vieritä alaspäin ja valitse Add-painike (tallentaa identiteetintarjoajan)
11. Tarkista nämä asetukset juuri luomastasi identiteetintarjoajasta

    

    

12. Aseta Do not Store Users arvoon On

    

13. Kun edellä kuvattu määritys on tehty, Secure Access (ESA) -kirjautumissivulle ilmestyy uusi kirjautumispainike, joka ohjaa asiakkaan Keycloakin kirjautumissivulle
14. Testaa kirjautuminen ja uloskirjautuminen useammalla kuin yhdellä tilillä

Secure Access (ESA) -mappaajien määritys

Kun kirjaudutaan sisään uudella painikkeella, alla oleva näkymä tulee näkyviin. Tämä tarkoittaa, että Secure Access (ESA) tarvitsee lisämäärityksiä mappaajille (mappers).

Jotta käyttäjä voidaan välittää Secure Access (ESA):sta muihin järjestelmiin (ESM, Classic Self-Service, IGA), Secure Access (ESA):n on tunnettava käyttäjän konteksti. Tätä varten Secure Access (ESA) tallentaa pienen määrän metatietoa, joka kuvaa jokaista kirjautumista yrittänyttä käyttäjää.

Yllä oleva näkymä tulee esiin, koska Secure Access (ESA) ei pysty hakemaan kaikkia tarvittavia tietoja identiteetintarjoajalta ja pyytää käyttäjää syöttämään kaikki vaaditut tiedot manuaalisesti.

Tämän voi välttää valmistelemalla automaation, joka mappaa IdP Keycloakista tulevat tiedot automaattisesti Secure Access (ESA) -käyttäjän vaatimiin attribuutteihin.

1. Kirjaudu Secure Access (ESA) -pääkäyttäjätunnuksella (main.admin) osoitteeseen domain.com/auth
2. Valitse oikea realm valitsemalla ensin vasemmasta yläkulmasta Manage realms ja sitten napsauttamalla realmin nimen linkkiä. Realmin valinnan käyttöliittymä muuttui julkaisussa 2026.1.2 aiempiin verrattuna.

   

3. Avaa Identity Provider -asetukset vasemmasta sivupaneelista

   

4. Valitse identiteetintarjoaja, jonka loit tätä Keycloak-todennusta varten aiemmissa vaiheissa
5. Siirry Mappers-välilehdelle. Tässä on esimerkki siitä, miten ne tulisi määrittää.
   Käytä samoja attribuuttinimiä ja friendly name -arvoja kuin ne on määritetty Keycloakiin IdP:nä.
   Mappaukset voivat vaihdella eri ympäristöjen välillä, joten on myös tärkeää keskustella siitä, mitä claimeja IdP Keycloak lähettää ja miten ne tulisi mapata.
   Seuraavat kolme esimerkkimappausta toimivat tilanteessa, jossa IdP Keycloakin email-claim voidaan asettaa email-, upn- ja username-attribuutteihin.
   • Käytä email-kentälle mapper-tyyppiä Attribute Importer ja Sync mode override -arvoa Force.

     

   • Käytä username-kentälle mapper-tyyppiä Username Attribute Importer ja Sync mode override -arvoa Force.

     

   • Käytä upn-kentälle mapper-tyyppiä Username Attribute Importer ja Sync mode override -arvoa Force.

     

Näiden vaiheiden jälkeen:

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

Tarkista/aseta, että olet määrittänyt logout-URL:n oikein scc:hen ja/tai esm:ään sen mukaan, minne käyttäjät ohjautuvat tällä todennuksella.

Kun yllä olevat vaiheet on suoritettu, ESM luo kirjautumisprosessin aikana puuttuvan User-objektin, yhdistää sen olemassa olevaan Personiin - ja siirtyy annetun roolin ITSM:n aloitussivulle.

Esimerkki Keycloak OpenID Connect -identiteetintarjoajasta

Vianmääritys

Jos näet tämän näkymän todennuksen jälkeen IdP Keycloakia vastaan:

Silloin ongelma johtuu todennäköisesti siitä, että claims-mappaukset eivät täsmää Secure Accessin ja IdP Keycloakin välillä. Tarkista/korjaa määritykset molemmilla puolilla.

Jos näet tämän näkymän todennuksen jälkeen IdP Keycloakia vastaan, se tarkoittaa, että Secure Access tarvitsee lisämäärityksiä mappaajille. Tarkista myös Claim-määritykset IdP Keycloakin puolella.