Een OAuth2-applicatie aanmaken in XFA

Een OAuth2-applicatie in XFA voegt toestelverificatie toe aan een OAuth2-aanmeldflow. XFA staat tussen je applicatie en je identity provider, 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 OAuth2 zo:

Applicatie → identity provider: de applicatie stuurt de gebruiker naar je identity 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 identity provider de gebruiker na de authenticatie terug naar XFA.
Identity provider → XFA: na de authenticatie stuurt de identity provider de gebruiker terug naar de redirect URL 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 uitwisselen, applicatie → XFA → identity provider: komt het toestel door de controle, dan stuurt XFA de gebruiker terug naar de applicatie met de authorization code. De applicatie wisselt die code daarna in voor een access token via het token endpoint van XFA, dat het verzoek transparant doorgeeft aan het token endpoint van je identity provider. XFA gebruikt die uitwisseling om de geauthenticeerde gebruiker aan zijn toestel te koppelen. Het token dat de applicatie terugkrijgt blijft ongewijzigd: XFA past het niet aan.

Wat je waar instelt

Waar	Wat je instelt
Applicatie (OAuth2-instellingen)	Vervang de `redirect_uri` door de XFA Redirect URL
XFA	Integration Name, de oorspronkelijke Redirect URL van je applicatie en het Token Endpoint van je identity 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 > OAuth2 Integration

Een nieuwe applicatie aanmaken

3. Vul de OAuth2-instellingen in

Instellingen in XFA

Integration Name: een duidelijke naam voor deze integratie
Redirect URL: de oorspronkelijke redirect URL van je applicatie, waar XFA de gebruiker na de toestelcontrole naartoe stuurt
Token Endpoint: het OAuth2-token-endpoint van je identity provider, dat XFA gebruikt om de authorization code in te wisselen voor een 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 OAuth2-instellingen invullen

4. Pas de OAuth2-instellingen van je applicatie aan

Kopieer na het opslaan de XFA Redirect URL uit de details van de integratie. Vervang in de OAuth2-configuratie van je applicatie de bestaande redirect_uri door die XFA Redirect URL. Zo stuurt de identity 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 identity 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 identity provider de authorization code heeft teruggegeven, vlak voor het inwisselen van die code bij het Token Endpoint (zie Hoe het werkt hierboven). Sommige identity 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 het inwisselen 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 voor de doorverwijzing naar de identity provider uitvoeren. De authorization code van de provider wordt dan pas aangemaakt 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 OAuth2-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 OAuth2-integratie in het XFA-dashboard het nieuwe veld Authorize Endpoint of Provider op het OAuth2- of OIDC-authorisatie-endpoint van je identity provider. Dat is dezelfde authorize-URL waar je applicatie vandaag naar wijst, bijvoorbeeld https://<your-domain>/oauth2/v1/authorize.
Wijzig in de OAuth2-configuratie van je applicatie de autorisatie-URL (AuthUrl) zodat die naar het authorize-endpoint van XFA wijst in plaats van rechtstreeks naar de identity provider:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Vervang <applicationId> door de application-ID van je XFA-applicatie.

De rest blijft ongewijzigd. De redirect URI van je applicatie, je clientregistratie bij de identity provider en het Token Endpoint in XFA blijven ongewijzigd.

Wat er verandert

XFA: zet Authorize Endpoint of Provider op de authorize-URL van de provider
Applicatie: laat AuthUrl wijzen naar https://device-api.xfa.tech/<applicationId>/oauth2/authorize
Ongewijzigd: de redirect URI, de clientregistratie bij de provider en het Token Endpoint

Terugdraaien

Wil je terug naar het standaardgedrag, laat de AuthUrl van je applicatie dan weer naar het autorisatie-endpoint van je identity provider wijzen. Laat je het veld Authorize Endpoint of Provider in XFA leeg, dan geldt weer de flow waarbij de toestelcontrole na authorize gebeurt.

1. Meld je aan bij het XFA-dashboard