Configure XFA as the Identity Provider for a SAML service provider Beta

XFA is the identity provider here: the service provider hands sign-in to XFA, which signs users in with a passkey and checks their device. For Google Workspace, follow the Google Workspace guide instead.

Note: This guide assumes that you have an account set up with XFA for your organization, that you're an admin for that organization in XFA, and that you can configure single sign-on in the service provider. If you do not have an XFA account, you can create one at https://dashboard.xfa.tech/signup.

Create a SAML connection in XFA Dashboard

After logging in to the XFA Dashboard, open Identity provider in the sidebar, click Add connection and pick SAML app. XFA creates the connection and opens its guided setup: Basics, then four steps you work through between XFA and the service provider, in any order.

Under Basics, set:

a Name for the connection and the policy whose device checks apply during sign-in;
Allowed email domains: the domain(s) of the people who will sign in (for example example.com). XFA only signs in people with an email address in these domains or in your organization's email domains (under Settings). With no domains here or in your organization's email domains, no one can sign in.

Step 1, Add XFA as the identity provider, shows the values the service provider needs to trust XFA: the IdP metadata URL, the Entity ID, the SSO URL and a Certificate you can download. Enter them in the service provider's single sign-on settings; most service providers can import the IdP metadata URL in one go.

Each person signs in with a passkey on a device enrolled with XFA. Provision them before you turn single sign-on on, as described in Provision users for their first device.

Enter the service provider's details

In step 2, Paste the service provider's details, XFA needs to know which service provider sends the sign-in requests and where to send the signed SAML response:

Service provider entity ID: the service provider's entity ID (sometimes called the Issuer or Audience).
Assertion Consumer Service (ACS) URL: where XFA posts the SAML response.
Service provider signing certificate: only if the service provider signs its requests (see Signed requests). Leave it empty otherwise.

XFA always signs its SAML assertions, so a service provider setting such as "sign the response and assertion" needs no counterpart in XFA. XFA sends the email address as the NameID.

Import from metadata URL

If the service provider publishes SAML metadata at a URL, you don't have to copy the values one by one:

In step 2, paste the service provider's metadata URL (it starts with https://) under Import from metadata URL and click Import.
XFA fetches the metadata and fills in Service provider entity ID and Assertion Consumer Service (ACS) URL. When the metadata says the service provider signs its sign-in requests, XFA also fills in Service provider signing certificate.
Check the values, then click Finish setup (or Save and continue later).

If the import fails, open the metadata URL in a browser: it must return the service provider's SAML metadata XML. You can always paste the values by hand instead.

In step 3, turn on single sign-on in the service provider for the users or groups XFA should check; start with a small group. Step 4 is an optional test sign-in.

Signed requests

Some service providers sign every sign-in request they send to XFA; most don't. With a Service provider signing certificate saved, XFA only accepts requests signed with that certificate, and Require signed requests is on under Settings on the connection's page. Without one, XFA accepts unsigned requests, and the user still proves their identity with their passkey.

When the service provider rotates its signing certificate

Service providers that sign their requests rotate their signing certificate from time to time and publish the new one in their metadata. XFA doesn't fetch the metadata again by itself yet. After a rotation, sign-in fails with the reason invalid_signature until you open Change connection, click Import in step 2 again (or paste the new certificate) and save the connection.

Troubleshooting

When XFA rejects a sign-in request from the service provider, the error page shows a line Reason: followed by a code. The same list, with a button that takes you to the field to fix, is under If the error page shows one of these reasons in step 4 of the setup.

Reason	What to do
`missing_sp_entity_id`	Fill in Service provider entity ID in step 2, or import the metadata.
`issuer_mismatch`	The request comes from a different entity ID. Copy the service provider's entity ID exactly into Service provider entity ID in step 2.
`missing_signature`	The service provider sent an unsigned request. Turn on request signing in the service provider, or turn off Require signed requests under Settings.
`invalid_signature`	The signature doesn't match the certificate, usually after a certificate rotation. Import the metadata again in step 2 and save.
`unsupported_sigalg`	XFA accepts RSA-SHA256 and RSA-SHA1 signatures. Set the service provider to sign with RSA-SHA256.
`invalid_sp_certificate`	XFA can't read the saved certificate. Paste the whole certificate, including its `BEGIN` and `END` lines, or import the metadata.
`malformed_request`	The request names no issuer. Check that the service provider sends its entity ID as the Issuer of its SAML requests, and contact XFA support if it remains.