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.

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.

Kloonaa providerin repositorio ja käännä se (tai hanki valmiiksi käännetty jar-tiedosto):
```
mvn clean package
```
Kopioi syntynyt login-hint-idp-<version>.jar Keycloakin providers-hakemistoon:
```
cp target/login-hint-idp-*.jar /opt/keycloak/providers/
```

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 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ä:

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

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.

Lisäasetukset

Tarkempia asetuksia varten, kuten tekijän rajaaminen tiettyihin käyttäjiin tai XFA:n käynnistäminen vain tietyissä tilanteissa, käytä Keycloakin conditional authenticator -toimintoja kulussa XFA Device Verification ja katso Keycloakin dokumentaatio.