Create an OpenID Connect (OAuth 2.0) application in XFA

An OpenID Connect (OIDC) application in XFA adds device verification to an OpenID Connect sign-in. OpenID Connect is the identity layer on top of OAuth 2.0: in its terms, your application is the Relying Party and your identity provider is the OpenID Provider. XFA sits between the two, verifies the device during login, and forwards the user only when your policy decision allows access. Use this page to enter the right values and test the sign-in flow.

How it works

Once configured, when a user signs in to an application with the OpenID Connect Authorization Code Flow:

Application → OpenID Provider: The application sends the user to your OpenID Provider's Authorization Endpoint (e.g. Google Workspace, Okta) to authenticate. Because the redirect_uri has been set to XFA's endpoint (see step 4 below), the OpenID Provider returns the user to XFA after authentication.
OpenID Provider → XFA: After authentication, the OpenID Provider redirects the user to XFA's Redirect URI with the authorization code.
XFA verifies the device: XFA checks the security posture of the device against your policy. If the device does not meet your policy, access is denied.
Token Request, Application → XFA → OpenID Provider: If the device passes, XFA redirects the user back to the application with the authorization code. The application then sends its Token Request to XFA's Token Endpoint, and XFA transparently proxies it to your OpenID Provider's Token Endpoint. XFA reads the email claim from the ID Token in the Token Response to link the authenticated user to their device. The tokens returned to the application are unchanged: XFA does not modify them.

What to configure where

Where	What to configure
Application (OpenID Connect settings)	Replace the `redirect_uri` with the XFA Redirect URI
XFA	Integration Name, your application's original Redirect URI, and the OpenID Provider's Token Endpoint

Note: This article assumes that you have an account set up with XFA for your organization and you are an admin for that organization. If you do not have an account, you can create one at https://dashboard.xfa.tech/signup.

2. Create a new application under Enforcement > New > OpenID Connect (OAuth 2.0) Integration

Create new application

3. Fill in the OpenID Connect settings

Settings in XFA

Integration Name: A descriptive name for this integration
Redirect URI: The original Redirect URI (redirect_uri) of your application, where XFA will forward the user after device verification
Token Endpoint: The Token Endpoint of your OpenID Provider, which XFA uses to exchange the authorization code for the ID Token and access token (e.g. https://accounts.google.com/o/oauth2/token for Google Workspace, or https://<your-domain>/oauth2/v1/token for Okta)

Click Save to save your integration.

Fill in the OpenID Connect settings

4. Update your application's OpenID Connect settings

After saving, copy the XFA Redirect URI shown in the integration details. In your application's OpenID Connect configuration, replace the existing redirect_uri with this XFA Redirect URI. This ensures that after authentication, the OpenID Provider returns the user to XFA for device verification instead of directly to the application.

5. Test the connection

Test the login flow by signing in through the application. The browser should be redirected to your OpenID Provider to authenticate, then to XFA for device verification, before being forwarded back to the application.

Run the device check before authorize (for short-lived authorization codes)

By default, XFA runs its device check after the OpenID Provider returns the authorization code, just before the Token Request to the Token Endpoint (see How it works above). Some OpenID Providers issue authorization codes that expire very quickly. If the device check takes longer than the code stays valid, for example when the user still needs to install the XFA agent, the Token Request can fail with an invalid_grant error and the user sees an authentication failure. With Microsoft's OpenID Connect handler the same situation can surface as an IDX21106 "Failed to parse token response body as JSON" error.

For these providers, XFA can instead run the device check before it sends the Authentication Request to the OpenID Provider. The provider's authorization code is then only issued once the check has passed, so it is redeemed within seconds and stays well inside its lifetime.

This option is opt-in and applies only to the OpenID Connect proxy integration described on this page. If you leave the new field empty, XFA keeps the default behavior (device check after the code is returned).

Enable device check before authorize

In your OpenID Connect integration in the XFA dashboard, set the Authorization Endpoint of the OpenID Provider field to your OpenID Provider's Authorization Endpoint. This is the same authorization URL your application points at today, for example https://<your-domain>/oauth2/v1/authorize.
In your application's OpenID Connect configuration, change the Authorization Endpoint (AuthUrl) so that it points at XFA's authorize entry point instead of at the OpenID Provider directly:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Replace <applicationId> with your XFA application ID.
In your application's OpenID Connect configuration, set the redirect_uri back to your application's own Redirect URI. It has to match the Redirect URI you entered in XFA exactly.
At your OpenID Provider, keep the XFA Redirect URI in the allowed redirect URIs of your client. XFA sends it to the OpenID Provider in place of your application's own Redirect URI.

Your client ID and client secret, and the Token Endpoint in XFA are unchanged.

If your application already sends the XFA Redirect URI as its redirect_uri in this flow, it keeps working. We recommend switching to your application's own Redirect URI.

What changes

XFA: set Authorization Endpoint of the OpenID Provider to the provider's Authorization Endpoint
Application: point AuthUrl at https://device-api.xfa.tech/<applicationId>/oauth2/authorize, and send your application's own Redirect URI as redirect_uri
OpenID Provider: allow the XFA Redirect URI as a redirect URI
Unchanged: client ID, client secret, and Token Endpoint

Roll back

To return to the default behavior, point your application's AuthUrl back at the OpenID Provider's Authorization Endpoint. Also set your application's redirect_uri to the XFA Redirect URI again, as in the default flow. Leaving the Authorization Endpoint of the OpenID Provider field empty in XFA restores the device-check-after-authorize flow.

1. Login to the XFA dashboard