Available

Connect a SAML application

Set up single sign-on to a SAML 2.0 application, with your AuthFI project as the identity provider.

Your project is a SAML 2.0 identity provider. Connect an application to it, and people sign in to that application with their AuthFI account instead of a separate password. This is single sign-on (SSO).

Use this guide for any application that supports SAML 2.0. For an application that supports OpenID Connect, see Add sign-in to an app.

Before you begin

You need:

A plan that includes SAML single sign-on. Without it, the endpoints on this page return 403.
Permission to add applications in the AuthFI console.
Administrator access to the application's SAML or SSO settings.

In SAML terms, your project is the identity provider (IdP) and the application is the service provider (SP).

Collect the application's SAML details

In the application's SSO settings, find these values. Applications name them differently, so common alternatives are listed.

You need	Also called	Required
Entity ID	SP entity ID, audience URI, identifier	Yes
ACS URL	Assertion consumer service URL, reply URL	Yes
Signing certificate	SP certificate, request signing certificate	No

You need the signing certificate only if the application signs its sign-in requests. You add it after registering.

Register the application in AuthFI

In the console, open Integrations > Applications and select Register.
Under What are you connecting?, choose SAML.
Under Which direction does trust flow?, choose We sign them in. AuthFI is the identity provider, and your people sign in to the application. This choice cannot be changed later.
Enter the values you collected.

Field	Enter
Handle	A short name in lower-case letters, digits and hyphens, for example `salesforce`. It is used in URLs and cannot be changed.
Their entity ID	The application's entity ID
Their ACS URL	The application's ACS URL. It must be `https`.
Their metadata URL	Optional. Lets AuthFI read the application's certificate and endpoints.

Review the summary and select Register.

The last step shows the Metadata, SSO and IdP-initiated URLs for this application.

Configure the application

Open the application's page in the console and go to the Connect section. It shows everything the application needs from your project. These values are the same for every SAML application in the project.

If the application accepts a metadata URL, select Copy beside the metadata URL and paste it into the application. The application then reads the other values from the metadata, and picks up a new certificate when your signing key rotates. The metadata lists the current certificate and, during a rotation, the previous one. To upload a file instead, select Download .xml.

If the application needs each value separately, the same section lists them:

In the console	Applications also call it	Value
Sign-in URL	SSO URL, sign-in page URL	`https://acme.authfi.io/saml/sso`
Entity ID	Issuer, IdP entity ID	`https://acme.authfi.io/saml/metadata`
Signing certificate	Verification certificate	Download .pem or .cer

The sign-on endpoint accepts the HTTP-Redirect and HTTP-POST bindings.

In the application, require a signed assertion. AuthFI signs the assertion with RSA-SHA256.

Assign the application

An application that no group is assigned to is open to everyone in the project. To restrict it, select Assign a group on the application's page and choose a group. The first assignment closes the application to everyone else, and the console warns you before it does.

Check that it works

Start a sign-in from AuthFI. Open the IdP-initiated URL the console showed you. It has this form, with your handle in place of salesforce:

https://acme.authfi.io/saml/idp-initiated/salesforce

Then test the other direction. Open the application's own sign-in page and choose SSO. The application sends you to AuthFI and back.

A SAML sign-in can start from either side.

Started by	What happens
The application	It sends the browser to `/saml/sso` with a SAML request. A person with no session signs in, then continues.
AuthFI	The browser opens `/saml/idp-initiated/{name}`. An optional `RelayState` parameter is passed to the application.

What the application receives

AuthFI posts a SAML response to the ACS URL through the person's browser. The response contains one signed assertion.

Part	Value
Signature	On the assertion, RSA-SHA256
Audience	The application's entity ID
Valid for	5 minutes
NameID	The person's email, in `emailAddress` format
Attributes	`roles` and `groups`
Authentication class	How the person signed in: password, MFA, or another identity provider

The groups attribute lists only the groups shared with this application, not every group the person belongs to.

Change the NameID and attributes

Each application can have its own NameID and attributes. On the application's page, open the What it receives section.

To start from what a common application expects, choose a template under Start from what the app documents: AuthFI default, Google Workspace, Salesforce, AWS IAM Identity Center, Microsoft claim names or Empty.
Under Who they are (NameID), choose Their email address or Their user ID, which never changes. The console shows the format that will be sent: emailAddress or persistent.
Under Attributes, select + Add an attribute. Enter the name the application expects and choose its value.
Select Save.

Attribute value in the console	Sends
Email address	`email`
First name	`first_name`
Last name	`last_name`
Full name	`full_name`
User ID, which never changes	`user_id`
Every role they hold	`roles`
Groups shared with this app	`groups`

You can define up to 50 attributes. An attribute with no value for a person is left out of that person's assertion.

If the application signs its requests, give AuthFI its certificate so the signature can be verified.

On the application's page, open the Requests it sends section.
Select Add the application's certificate, paste the certificate or select Upload a file, and select Register it.
To reject any request that is not signed, turn on Refuse unsigned requests.

When the application starts the sign-in, AuthFI validates its request before it shows the sign-in page. A request that fails a check gets a 403.

The request names an application registered in the project.
Destination, when present, is your project's sign-on URL.
The request is no more than 5 minutes old.
An ACS URL in the request equals the registered ACS URL.
The signature verifies, when the application has a signing certificate or signed requests are required.

AuthFI honours two options in a request:

ForceAuthn. The person signs in again, even with a session.
A requested authentication class. If it cannot be met, the application receives a signed response with the status NoAuthnContext.

Troubleshooting

What you see	Cause	Fix
`403` on every SAML URL	The plan does not include SAML single sign-on	Change the plan
`403` when the application starts a sign-in	The entity ID or ACS URL in the request is not the one registered	Compare both values, character for character, with the application's settings
`403` only when requests are signed	The certificate in AuthFI is not the one the application signs with	Add the application's current certificate under Requests it sends
`403` on a request that used to work	The request is more than 5 minutes old	Check the clock on the application's server
A page saying the person is not assigned	The application is assigned to groups, and the person is in none	Select Assign a group and choose one of the person's groups
The application reports `NoAuthnContext`	It asked for a way of signing in that the person could not use	Enrol the person in MFA, or relax the application's requirement

Next steps

Roles, groups and grants

How assigning an application to a group decides who can sign in.

Provision people with SCIM

Create and suspend accounts from your directory.

Keys and secrets

What happens to the signing certificate when a key rotates.