Eine OpenID Connect (OAuth 2.0)-Anwendung in XFA erstellen

Eine OpenID Connect (OIDC)-Anwendung in XFA fügt einer OpenID Connect-Anmeldung eine Geräteverifizierung hinzu. OpenID Connect ist die Identitätsschicht auf OAuth 2.0: In seinen Begriffen ist Ihre Anwendung die Relying Party und Ihr Identity Provider der OpenID Provider. XFA sitzt zwischen den beiden, 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 mit dem OpenID Connect Authorization Code Flow so ab:

Anwendung → OpenID Provider: Die Anwendung schickt den Benutzer an den Authorization Endpoint Ihres OpenID Providers (zum Beispiel Google Workspace oder Okta), damit er sich authentifiziert. Weil die redirect_uri auf den Endpunkt von XFA gesetzt ist (siehe Schritt 4 unten), schickt der OpenID Provider den Benutzer nach der Authentifizierung zurück an XFA.
OpenID Provider → XFA: Nach der Authentifizierung leitet der OpenID Provider den Benutzer zusammen mit dem Authorization Code an die Redirect URI von XFA weiter.
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 Request, Anwendung → XFA → OpenID Provider: Besteht das Gerät die Prüfung, leitet XFA den Benutzer mit dem Authorization Code zurück an die Anwendung. Die Anwendung sendet anschließend ihren Token Request an den Token Endpoint von XFA, und XFA reicht ihn transparent an den Token Endpoint Ihres OpenID Providers weiter. XFA liest den email-Claim aus dem ID Token in der Token Response, um den authentifizierten Benutzer mit seinem Gerät zu verknüpfen. Die Tokens, die die Anwendung zurückerhält, bleiben unverändert: XFA passt sie nicht an.

Was Sie wo einstellen

Wo	Was Sie einstellen
Anwendung (OpenID Connect-Einstellungen)	Ersetzen Sie die `redirect_uri` durch die XFA Redirect URI
XFA	Integration Name, die ursprüngliche Redirect URI Ihrer Anwendung und den Token Endpoint des OpenID 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 > OpenID Connect (OAuth 2.0)-Integration

Eine neue Anwendung erstellen

3. Tragen Sie die OpenID Connect-Einstellungen ein

Einstellungen in XFA

Integration Name: ein aussagekräftiger Name für diese Integration
Redirect URI: die ursprüngliche Redirect URI (redirect_uri) Ihrer Anwendung, an die XFA den Benutzer nach dem Gerätecheck weiterleitet
Token Endpoint: der Token Endpoint Ihres OpenID Providers, über den XFA den Authorization Code gegen das ID Token und das 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 OpenID Connect-Einstellungen eintragen

4. Passen Sie die OpenID Connect-Einstellungen Ihrer Anwendung an

Kopieren Sie nach dem Speichern die XFA Redirect URI aus den Details der Integration. Ersetzen Sie in der OpenID Connect-Konfiguration Ihrer Anwendung die bestehende redirect_uri durch diese XFA Redirect URI. So schickt der OpenID 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 OpenID 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 OpenID Provider den Authorization Code zurückgegeben hat, kurz vor dem Token Request an den Token Endpoint (siehe So funktioniert es oben). Manche OpenID 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 Request 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 ausführen, bevor es den Authentication Request an den OpenID Provider sendet. Der Authorization Code des Providers wird dann erst ausgestellt, 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 OpenID Connect-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 OpenID Connect-Integration im XFA-Dashboard das Feld Autorisierungs-Endpunkt des OpenID Providers auf den Authorization Endpoint Ihres OpenID Providers. Das ist dieselbe Autorisierungs-URL, auf die Ihre Anwendung heute zeigt, zum Beispiel https://<your-domain>/oauth2/v1/authorize.
Ändern Sie in der OpenID Connect-Konfiguration Ihrer Anwendung den Authorization Endpoint (AuthUrl) so, dass er auf den Authorize-Einstieg von XFA zeigt statt direkt auf den OpenID Provider:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Ersetzen Sie <applicationId> durch die Application-ID Ihrer XFA-Anwendung.
Setzen Sie in der OpenID Connect-Konfiguration Ihrer Anwendung die redirect_uri wieder auf die eigene Redirect URI Ihrer Anwendung. Sie muss exakt mit der Redirect URI übereinstimmen, die Sie in XFA eingetragen haben.
Lassen Sie bei Ihrem OpenID Provider die XFA Redirect URI in den zulässigen Redirect URIs Ihres Clients stehen. XFA sendet sie anstelle der eigenen Redirect URI Ihrer Anwendung an den OpenID Provider.

Ihre Client-ID und Ihr Client-Secret sowie der Token Endpoint in XFA bleiben unverändert.

Wenn Ihre Anwendung in diesem Ablauf bereits die XFA Redirect URI als redirect_uri sendet, funktioniert das weiterhin. Wir empfehlen, auf die eigene Redirect URI Ihrer Anwendung umzustellen.

Was sich ändert

XFA: Setzen Sie Autorisierungs-Endpunkt des OpenID Providers auf den Authorization Endpoint des Providers
Anwendung: Lassen Sie AuthUrl auf https://device-api.xfa.tech/<applicationId>/oauth2/authorize zeigen und senden Sie die eigene Redirect URI Ihrer Anwendung als redirect_uri
OpenID Provider: Lassen Sie die XFA Redirect URI als Redirect URI zu
Unverändert: die Client-ID, das Client-Secret und der Token Endpoint

Zurücksetzen

Um zum Standardverhalten zurückzukehren, lassen Sie die AuthUrl Ihrer Anwendung wieder auf den Authorization Endpoint des OpenID Providers zeigen. Setzen Sie außerdem die redirect_uri Ihrer Anwendung wieder auf die XFA Redirect URI, wie im Standardablauf. Wenn Sie das Feld Autorisierungs-Endpunkt des OpenID Providers in XFA leer lassen, gilt wieder der Ablauf mit dem Gerätecheck nach authorize.

1. Melden Sie sich am XFA-Dashboard an