Een OpenID Connect (OAuth 2.0)-applicatie aanmaken in XFA

Een OpenID Connect (OIDC)-applicatie in XFA voegt toestelverificatie toe aan een OpenID Connect-aanmelding. OpenID Connect is de identiteitslaag bovenop OAuth 2.0: in die termen is je applicatie de Relying Party en je identity provider de OpenID Provider. XFA staat tussen die twee, controleert het toestel tijdens het aanmelden en stuurt de gebruiker pas door wanneer je beleid toegang toestaat. Gebruik deze pagina om de juiste waarden in te vullen en de aanmeldflow te testen.

Hoe het werkt

Is alles ingesteld, dan verloopt het aanmelden bij een applicatie via de OpenID Connect Authorization Code Flow zo:

Applicatie → OpenID Provider: de applicatie stuurt de gebruiker naar het Authorization Endpoint van je OpenID Provider (bijvoorbeeld Google Workspace of Okta) om te authenticeren. Omdat de redirect_uri op het endpoint van XFA staat (zie stap 4 hieronder), stuurt de OpenID Provider de gebruiker na de authenticatie terug naar XFA.
OpenID Provider → XFA: na de authenticatie stuurt de OpenID Provider de gebruiker naar de Redirect URI van XFA, samen met de authorization code.
XFA verifieert het toestel: XFA toetst de beveiligingsstatus van het toestel aan je beleid. Voldoet het toestel niet, dan wordt de toegang geweigerd.
Token Request, applicatie → XFA → OpenID Provider: komt het toestel door de controle, dan stuurt XFA de gebruiker terug naar de applicatie met de authorization code. De applicatie stuurt daarna haar Token Request naar het Token Endpoint van XFA, en XFA geeft die transparant door aan het Token Endpoint van je OpenID Provider. XFA leest de email-claim uit het ID Token in de Token Response om de geauthenticeerde gebruiker aan zijn toestel te koppelen. De tokens die de applicatie terugkrijgt blijven ongewijzigd: XFA past ze niet aan.

Wat je waar instelt

Waar	Wat je instelt
Applicatie (OpenID Connect-instellingen)	Vervang de `redirect_uri` door de XFA Redirect URI
XFA	Integration Name, de oorspronkelijke Redirect URI van je applicatie en het Token Endpoint van de OpenID Provider

Let op: dit artikel gaat ervan uit dat je organisatie een XFA-account heeft en dat jij daar beheerder van bent. Heb je nog geen account, maak er dan een aan op https://dashboard.xfa.tech/signup.

2. Maak een nieuwe applicatie aan via Enforcement > New > OpenID Connect (OAuth 2.0) Integration

Een nieuwe applicatie aanmaken

3. Vul de OpenID Connect-instellingen in

Instellingen in XFA

Integration Name: een duidelijke naam voor deze integratie
Redirect URI: de oorspronkelijke Redirect URI (redirect_uri) van je applicatie, waar XFA de gebruiker na de toestelcontrole naartoe stuurt
Token Endpoint: het Token Endpoint van je OpenID Provider, dat XFA gebruikt om de authorization code in te wisselen voor het ID Token en het access token (bijvoorbeeld https://accounts.google.com/o/oauth2/token voor Google Workspace of https://<your-domain>/oauth2/v1/token voor Okta)

Klik op Opslaan om je integratie op te slaan.

De OpenID Connect-instellingen invullen

4. Pas de OpenID Connect-instellingen van je applicatie aan

Kopieer na het opslaan de XFA Redirect URI uit de details van de integratie. Vervang in de OpenID Connect-configuratie van je applicatie de bestaande redirect_uri door die XFA Redirect URI. Zo stuurt de OpenID Provider de gebruiker na de authenticatie naar XFA voor de toestelcontrole in plaats van rechtstreeks naar de applicatie.

5. Test de verbinding

Test de aanmeldflow door je via de applicatie aan te melden. De browser hoort eerst naar je OpenID Provider te gaan om te authenticeren, daarna naar XFA voor de toestelcontrole, en pas daarna terug naar de applicatie.

De toestelcontrole voor authorize uitvoeren (bij kortlevende authorization codes)

Standaard voert XFA de toestelcontrole uit nadat de OpenID Provider de authorization code heeft teruggegeven, vlak voor de Token Request naar het Token Endpoint (zie Hoe het werkt hierboven). Sommige OpenID Providers geven authorization codes uit die heel snel verlopen. Duurt de toestelcontrole langer dan de code geldig blijft, bijvoorbeeld omdat de gebruiker de XFA-agent nog moet installeren, dan kan de Token Request mislukken met de fout invalid_grant en ziet de gebruiker een mislukte authenticatie. Bij de OpenID Connect-handler van Microsoft kan dezelfde situatie opduiken als de fout IDX21106, "Failed to parse token response body as JSON".

Bij die providers kan XFA de toestelcontrole ook uitvoeren voordat het de Authentication Request naar de OpenID Provider stuurt. De authorization code van de provider wordt dan pas uitgegeven nadat de controle geslaagd is, zodat die binnen enkele seconden wordt ingewisseld en ruim binnen zijn geldigheidsduur blijft.

Deze optie is opt-in en geldt alleen voor de OpenID Connect-proxy-integratie die op deze pagina beschreven staat. Laat je het nieuwe veld leeg, dan houdt XFA het standaardgedrag aan (toestelcontrole nadat de code is teruggegeven).

De toestelcontrole voor authorize aanzetten

Zet in je OpenID Connect-integratie in het XFA-dashboard het veld Authorization Endpoint van de OpenID Provider op het Authorization Endpoint van je OpenID Provider. Dat is dezelfde autorisatie-URL waar je applicatie vandaag naar wijst, bijvoorbeeld https://<your-domain>/oauth2/v1/authorize.
Wijzig in de OpenID Connect-configuratie van je applicatie het Authorization Endpoint (AuthUrl) zodat het naar het authorize-endpoint van XFA wijst in plaats van rechtstreeks naar de OpenID Provider:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Vervang <applicationId> door de application-ID van je XFA-applicatie.
Zet in de OpenID Connect-configuratie van je applicatie de redirect_uri terug op de eigen Redirect URI van je applicatie. Die moet exact overeenkomen met de Redirect URI die je in XFA hebt ingevuld.
Laat bij je OpenID Provider de XFA Redirect URI staan in de toegelaten redirect URI's van je client. XFA stuurt die naar de OpenID Provider in plaats van de eigen Redirect URI van je applicatie.

Je client-ID en clientsecret en het Token Endpoint in XFA blijven ongewijzigd.

Stuurt je applicatie in deze flow al de XFA Redirect URI mee als redirect_uri, dan blijft dat werken. We raden aan om over te schakelen op de eigen Redirect URI van je applicatie.

Wat er verandert

XFA: zet Authorization Endpoint van de OpenID Provider op het Authorization Endpoint van de provider
Applicatie: laat AuthUrl wijzen naar https://device-api.xfa.tech/<applicationId>/oauth2/authorize en stuur de eigen Redirect URI van je applicatie mee als redirect_uri
OpenID Provider: laat de XFA Redirect URI toe als redirect URI
Ongewijzigd: de client-ID, het clientsecret en het Token Endpoint

Terugdraaien

Wil je terug naar het standaardgedrag, laat de AuthUrl van je applicatie dan weer naar het Authorization Endpoint van de OpenID Provider wijzen. Zet ook de redirect_uri van je applicatie weer op de XFA Redirect URI, zoals in de standaardflow. Laat je het veld Authorization Endpoint van de OpenID Provider in XFA leeg, dan geldt weer de flow waarbij de toestelcontrole na authorize gebeurt.

1. Meld je aan bij het XFA-dashboard