Skip to main content

XFA:n määrittäminen todennustekijäksi Keycloakiin

Määritä XFA Keycloakiin lisätäksesi laitteen vahvistuksen sen jälkeen, kun käyttäjä on todentautunut. XFA toimii kirjautumisen jälkeisenä vaiheena, tarkistaa laitteen määrittämääsi käytäntöä vasten ja antaa kirjautumisen jatkua, kun laitepäätös sallii pääsyn. Varmista sen avulla tarvittavat asetukset ja testaa todennuskulku ennen käyttöönottoa.

Huomaa: tämä opas olettaa, että organisaatiollasi on XFA-tili ja että olet siinä organisaatiossa järjestelmänvalvoja sekä XFA:ssa että Keycloakissa. Jos sinulla ei ole XFA-tiliä, voit luoda sellaisen osoitteessa https://dashboard.xfa.tech/signup.

Integraation luominen XFA:n hallintapaneelissa

Kun olet kirjautunut XFA:n hallintapaneeliin, siirry Enforcement-sivulle, napsauta Uusi ja valitse integraatiotyypiksi Keycloak.

Sivulla näkyy useita arvoja, joita tarvitset seuraavissa vaiheissa (Client ID, Client Secret ja OpenID Connect -päätepisteet). Siellä on myös Redirect URI -kenttä, jonka täytät alla olevissa vaiheissa Keycloakista saatavalla arvolla.

Pidä tämä sivu auki seuraavien vaiheiden ajan.

XFA:n login-hint-providerin asentaminen Keycloakiin

Keycloak ei oletuksena välitä jo todennetun käyttäjän henkilöllisyyttä ulkoiselle identiteetintarjoajalle. XFA tarvitsee tuon henkilöllisyyden (käyttäjän sähköpostiosoitteen) tietääkseen, mikä laite vahvistetaan. Pieni avoimen lähdekoodin Keycloak-provider hoitaa tämän: se lukee todennetun käyttäjän istunnosta ja asettaa login_hint-parametrin XFA:han ohjaukseen. Provider löytyy osoitteesta github.com/gl-ventures/xfa-keycloak-login-hint-mapper.

  1. Kloonaa providerin repositorio ja käännä se (tai hanki valmiiksi käännetty jar-tiedosto):

    mvn clean package
  2. Kopioi syntynyt login-hint-idp-<version>.jar Keycloakin providers-hakemistoon:

    cp target/login-hint-idp-*.jar /opt/keycloak/providers/
  3. Käännä Keycloak uudelleen, jotta provider rekisteröityy, ja käynnistä sitten käynnissä oleva instanssi uudelleen, jotta muutos tulee voimaan:

    /opt/keycloak/bin/kc.sh build
    # then restart Keycloak, e.g. restart the service or container running it,
    # or start it again directly:
    /opt/keycloak/bin/kc.sh start
Miksi tämä tarvitaan

Provider hakee sähköpostiosoitteen todennetusta Keycloak-istunnosta (getAuthenticatedUser()), ei asiakkaan antamasta parametrista. Näin varmistetaan, että XFA:n vahvistama laite kuuluu sille käyttäjälle, joka todella kirjautui sisään.

XFA-identiteetintarjoajan luominen Keycloakiin

Valitse Keycloakin Admin Consolessa realmisi ja siirry kohtaan Identity providers. Napsauta Add provider ja valitse OpenID Connect v1.0.

Täytä seuraavat tiedot kopioimalla arvot XFA:n hallintapaneelin sivulta, jonka jätit auki.

Provider

  • Alias: XFA (juuri tähän aliakseen viitataan alla olevassa Post Login Flow -kulussa)
  • Display name: XFA

OpenID Connect -asetukset

  • Kytke Use discovery endpoint pois käytöstä. Silloin näkyviin tulevat kentät, joihin syötät päätepisteet käsin.
  • Authorization URL
  • Token URL
  • User Info URL
  • Issuer
  • Kytke Validate Signatures käyttöön, jotta JWKS URL -kenttä tulee näkyviin, ja täytä sitten JWKS URL.
  • Aseta Client authentication arvoon Client secret sent in the request body.
  • Client ID
  • Client Secret

Tallenna provider. Keycloak näyttää nyt tälle identiteetintarjoajalle Redirect URI -osoitteen (se näyttää tältä: https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Kopioi arvo takaisin XFA:n hallintapaneelin sivun Redirect URI -kenttään ja tallenna XFA-integraatio.

Lisäasetukset

Avaa juuri luomasi provider ja laajenna osio Advanced (oletuksena suljettu):

  • Aseta Default Scopes arvoon openid email profile.
  • Kytke Pass login_hint käyttöön, jotta Keycloak välittää todennetun käyttäjän sähköpostiosoitteen (jonka yllä asennettu provider asettaa) XFA:lle.
Attribuuttien kohdistus

Jätä oletusmapperit paikoilleen. XFA palauttaa käyttäjän email-osoitteen (ja sub-arvon) allekirjoitetussa tunnuksessa, ja Keycloak yhdistää sen avulla vahvistuksen tuloksen jo todennettuun käyttäjään.

XFA:n lisääminen Post Login Flow -kulkuun

XFA:n on toimittava sen jälkeen, kun käyttäjä on todentautunut, joten se määritetään ensisijaisen todennuksen Post Login Flow -kuluksi.

1. Luo todennuskulku

Siirry Admin Consolessa kohtaan Authentication > Flows ja luo uusi kulku (esimerkiksi XFA Device Verification), tyypiksi Basic flow.

Lisää kaksi suoritusta, molemmat tilaan Required, tässä järjestyksessä:

  1. IdP Redirector (login_hint): tulee asentamastasi jar-tiedostosta. Avaa sen Settings (rataskuvake) ja aseta Default Identity Provider arvoon XFA.
  2. Identity Provider Redirector: avaa sen Settings ja aseta Default Identity Provider arvoon XFA.

2. Sido se Post Login Flow -kuluksi

Avaa ensisijainen todennus, joka suorittaa ensimmäisen kirjautumisvaiheen (esimerkiksi Microsoft-identiteetintarjoajasi kohdassa Identity providers), siirry sen lisäasetuksiin ja aseta Post login flow juuri luomaasi kulkuun XFA Device Verification.

Kun käyttäjä on nyt suorittanut tavallisen kirjautumisensa, Keycloak ohjaa hänet XFA:han vahvistamaan laitteensa, ennen kuin istunto muodostetaan.

Ota XFA käyttöön useammissa ryhmissä

Suorita XFA:n kirjautumisen jälkeinen kulku vain ryhmille, joilla on xfa-test=true. Aloita pienellä testiryhmällä ja merkitse testauksen jälkeen lisää ryhmiä. Käyttäjät, joiden tilillä tai ryhmillä ei ole tätä attribuuttia, kirjautuvat ilman tätä XFA:n laitetarkistusta.

Käytä Keycloak 26.x:ää ja edellä asennettua login-hint-palveluntarjoajaa. Ryhmäattribuuttiehto on saatavilla Keycloak 26.0:ssa; palveluntarjoajan nykyinen koontiversio on tarkoitettu versiolle 26.7.2. Määritä uuden integraation rajaus ennen kirjautumisen jälkeisen kulun sitomista.

  1. Luo pieni ryhmä, kuten XFA test, kohdassa Groups.
  2. Lisää attribuutti xfa-test arvolla true kyseisen ryhmän Attributes-välilehdellä.
  3. Tallenna ryhmäattribuutti valitsemalla Save.
  4. Lisää testikäyttäjä, jolla ei ole ylläpitäjän oikeuksia, ryhmään kohdassa Users > käyttäjä > Groups > Join Group.
  5. Avaa Authentication > Flows > XFA Device Verification.
  6. Luo Add sub-flow -toiminnolla Generic -tyyppinen alikulku nimeltä XFA groups.
  7. Aseta alikulun Requirement-arvoksi Conditional.
  8. Lisää Condition - user attribute alikulkuun Add condition -toiminnolla.
  9. Aseta ehdon Requirement-arvoksi Required.
  10. Avaa ehdon Settings rataskuvakkeesta.
  11. Määritä ehdon Alias-arvoksi xfa-groups-condition ja Attribute name -arvoksi xfa-test ja Expected attribute value -arvoksi true sekä ota Include group attributes käyttöön. Jätä Negate output ja regex pois käytöstä.
  12. Tallenna ehto valitsemalla Save.
  13. Siirrä IdP Redirector (login_hint) vetokahvastaan alikulkuun ehdon alle.
  14. Siirrä Identity Provider Redirector alikulkuun IdP Redirector (login_hint) -vaiheen alle.
  15. Varmista, että molemmat uudelleenohjaajat ovat Required-tilassa, molempien Default Identity Provider on edelleen XFA eikä kumpikaan jää ehdollisen alikulun ulkopuolelle.
  16. Testaa uutta kirjautumista ryhmän jäsenellä, jolla ei ole ylläpitäjän oikeuksia. Käyttäjän pitäisi saapua XFA:han tavallisen kirjautumisen jälkeen.
  17. Testaa uutta kirjautumista käyttäjällä, joka ei kuulu merkittyihin ryhmiin. Käyttäjän pitäisi voida kirjautua ilman tätä XFA-tarkistusta.
  18. Lisää xfa-test=true seuraavaksi mukaan otettavan ryhmän Attributes-välilehdelle.
  19. Tallenna ryhmäattribuutti valitsemalla Save.
  20. Toista kirjautumistestit ennen seuraavan ryhmän lisäämistä.

Käytä tätä merkintää vain ryhmillä. Ehto lukee myös käyttäjäattribuutit, joten saman merkinnän asettaminen suoraan käyttäjälle ottaa myös tämän käyttäjän mukaan. Jos loit alkuasetuksissa jo XFA test -ryhmän ja ehdollisen alikulun, säilytä ne ja jatka testivaiheista.