Eine OAuth2-Anwendung in XFA erstellen

Eine OAuth2-Anwendung in XFA fügt einem OAuth2-Anmeldeablauf eine Geräteverifizierung hinzu. XFA sitzt zwischen Ihrer Anwendung und Ihrem Identity Provider, prüft das Gerät während der Anmeldung und leitet den Benutzer erst weiter, wenn Ihre Richtlinienentscheidung den Zugriff erlaubt. Nutzen Sie diese Seite, um die richtigen Werte einzutragen und den Anmeldeablauf zu testen.

So funktioniert es

Ist alles eingerichtet, läuft die Anmeldung an einer Anwendung über OAuth2 so ab:

Anwendung → Identity Provider: Die Anwendung leitet den Benutzer an Ihren Identity Provider (zum Beispiel Google Workspace oder Okta) weiter, damit er sich authentifiziert. Weil die redirect_uri auf den Endpunkt von XFA gesetzt ist (siehe Schritt 4 unten), schickt der Identity Provider den Benutzer nach der Authentifizierung zurück an XFA.
Identity Provider → XFA: Nach der Authentifizierung leitet der Identity Provider den Benutzer zusammen mit dem Authorization Code zurück an die Redirect URL von XFA.
XFA prüft das Gerät: XFA gleicht den Sicherheitsstatus des Geräts mit Ihrer Richtlinie ab. Erfüllt das Gerät Ihre Richtlinie nicht, wird der Zugriff verweigert.
Token-Austausch, Anwendung → XFA → Identity Provider: Besteht das Gerät die Prüfung, leitet XFA den Benutzer mit dem Authorization Code zurück an die Anwendung. Die Anwendung tauscht diesen Code anschließend über den Token-Endpunkt von XFA gegen ein Access Token ein; XFA reicht diese Anfrage transparent an den Token Endpoint Ihres Identity Providers weiter. XFA nutzt diesen Austausch, um den authentifizierten Benutzer mit seinem Gerät zu verknüpfen. Das Token, das die Anwendung zurückerhält, bleibt unverändert: XFA passt es nicht an.

Was Sie wo einstellen

Wo	Was Sie einstellen
Anwendung (OAuth2-Einstellungen)	Ersetzen Sie die `redirect_uri` durch die XFA Redirect URL
XFA	Integration Name, die ursprüngliche Redirect URL Ihrer Anwendung und den Token Endpoint Ihres Identity Providers

Hinweis: Dieser Artikel setzt voraus, dass Ihre Organisation ein XFA-Konto hat und dass Sie Administrator dieser Organisation sind. Wenn Sie noch kein Konto haben, können Sie eines unter https://dashboard.xfa.tech/signup erstellen.

2. Erstellen Sie eine neue Anwendung über Enforcement > Neu > OAuth2 Integration

Eine neue Anwendung erstellen

3. Tragen Sie die OAuth2-Einstellungen ein

Einstellungen in XFA

Integration Name: ein aussagekräftiger Name für diese Integration
Redirect URL: die ursprüngliche Redirect URL Ihrer Anwendung, an die XFA den Benutzer nach dem Gerätecheck weiterleitet
Token Endpoint: der OAuth2-Token-Endpunkt Ihres Identity Providers, über den XFA den Authorization Code gegen ein Access Token eintauscht (zum Beispiel https://accounts.google.com/o/oauth2/token für Google Workspace oder https://<your-domain>/oauth2/v1/token für Okta)

Klicken Sie auf Speichern, um Ihre Integration zu sichern.

Die OAuth2-Einstellungen eintragen

4. Passen Sie die OAuth2-Einstellungen Ihrer Anwendung an

Kopieren Sie nach dem Speichern die XFA Redirect URL aus den Details der Integration. Ersetzen Sie in der OAuth2-Konfiguration Ihrer Anwendung die bestehende redirect_uri durch diese XFA Redirect URL. So schickt der Identity Provider den Benutzer nach der Authentifizierung zum Gerätecheck an XFA statt direkt an die Anwendung.

5. Testen Sie die Verbindung

Testen Sie den Anmeldeablauf, indem Sie sich über die Anwendung anmelden. Der Browser sollte zuerst zur Authentifizierung an Ihren Identity Provider gehen, danach zum Gerätecheck an XFA und erst dann zurück an die Anwendung.

Den Gerätecheck vor authorize ausführen (bei kurzlebigen Authorization Codes)

Standardmäßig führt XFA den Gerätecheck aus, nachdem der Identity Provider den Authorization Code zurückgegeben hat, kurz vor dem Eintausch dieses Codes am Token Endpoint (siehe So funktioniert es oben). Manche Identity Provider geben Authorization Codes aus, die sehr schnell ablaufen. Dauert der Gerätecheck länger, als der Code gültig bleibt, etwa weil der Benutzer den XFA-Agenten noch installieren muss, kann der Token-Austausch mit dem Fehler invalid_grant scheitern, und der Benutzer sieht eine fehlgeschlagene Authentifizierung. Beim OpenID Connect-Handler von Microsoft kann dieselbe Situation als Fehler IDX21106, "Failed to parse token response body as JSON", auftreten.

Bei diesen Providern kann XFA den Gerätecheck stattdessen vor der Weiterleitung an den Identity Provider ausführen. Der Authorization Code des Providers wird dann erst erzeugt, nachdem der Check bestanden ist, sodass er innerhalb von Sekunden eingelöst wird und die Gültigkeitsdauer deutlich unterschreitet.

Diese Option ist opt-in und gilt nur für die auf dieser Seite beschriebene OAuth2-Proxy-Integration. Lassen Sie das neue Feld leer, behält XFA das Standardverhalten bei (Gerätecheck, nachdem der Code zurückgegeben wurde).

Den Gerätecheck vor authorize aktivieren

Setzen Sie in Ihrer OAuth2-Integration im XFA-Dashboard das neue Feld Authorize Endpoint of Provider auf den OAuth2- oder OIDC-Autorisierungsendpunkt Ihres Identity Providers. Das ist dieselbe Authorize-URL, auf die Ihre Anwendung heute zeigt, zum Beispiel https://<your-domain>/oauth2/v1/authorize.
Ändern Sie in der OAuth2-Konfiguration Ihrer Anwendung die Autorisierungs-URL (AuthUrl) so, dass sie auf den Authorize-Einstieg von XFA zeigt statt direkt auf den Identity Provider:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Ersetzen Sie <applicationId> durch die Application-ID Ihrer XFA-Anwendung.

Alles andere bleibt gleich. Die Redirect URI Ihrer Anwendung, Ihre Client-Registrierung beim Identity Provider und der Token Endpoint in XFA bleiben unverändert.

Was sich ändert

XFA: Setzen Sie Authorize Endpoint of Provider auf die Authorize-URL des Providers
Anwendung: Lassen Sie AuthUrl auf https://device-api.xfa.tech/<applicationId>/oauth2/authorize zeigen
Unverändert: die Redirect URI, die Client-Registrierung beim Provider und der Token Endpoint

Zurücksetzen

Um zum Standardverhalten zurückzukehren, lassen Sie die AuthUrl Ihrer Anwendung wieder auf den Autorisierungsendpunkt Ihres Identity Providers zeigen. Wenn Sie das Feld Authorize Endpoint of Provider in XFA leer lassen, gilt wieder der Ablauf mit dem Gerätecheck nach authorize.

1. Melden Sie sich am XFA-Dashboard an