Add sign-in with another identity provider

Let people sign in to your project with Google, Microsoft, Okta, GitHub, GitLab, or any OpenID Connect or SAML 2.0 identity provider.

A connection lets people sign in to your project with an account they already have at another identity provider. Your applications do not change: they still talk to your project, and receive the same tokens.

Use this guide to connect a provider that speaks OpenID Connect or OAuth 2.0, such as Google or GitHub, or one that speaks SAML 2.0.

Before you begin

You need:

• An AuthFI project and its issuer, the project's URL. This guide uses https://acme.authfi.io.
• Permission to add connections and applications in the AuthFI console.
• Administrator access to the identity provider, to register your project with it.
• The values in this table, from the provider.

For Microsoft, use the Microsoft Entra ID connection, with your directory ID. For GitHub, each person's GitHub account needs a public email, because every account in AuthFI has an email.

Connect an OpenID Connect or social provider

Follow this procedure for Google, Google Workspace, Microsoft Entra ID, Okta, GitHub, GitLab, or any OpenID Connect provider.

https://acme.authfi.io/v1/auth/{connection_id}/callback

Connect a SAML provider

With a SAML connection, your project is the service provider (SP) and the other side is the identity provider (IdP) that signs people in. In the console, a SAML identity provider is registered on Integrations > Applications, not on Connections.

Check that it works

Open the connection's sign-in URL in a browser.

For an OpenID Connect or social connection:

https://acme.authfi.io/v1/auth/{connection_id}/login?return_to=/

The browser goes to the provider and returns to your project, signed in. return_to is a path on your project's issuer. Any other URL is ignored.

For a SAML connection:

https://acme.authfi.io/saml/sp/{name}/login

This starts the sign-in from your project. A sign-in started from the provider's side is accepted too.

Send people to the right provider

When a connection lists email domains, your project's own sign-in page sends each person to the connection that matches their email.

To do the same from your own page, ask which connection an email address belongs to, then send the browser to the path in the response.

{ "login_path": "/v1/auth/7b1e.../login" }

A 404 means no connection claims that email domain. The person then signs in with their AuthFI password or passkey.

For SAML connections, the equivalent request is GET /saml/sp/resolve?email=.

What AuthFI reads from the provider

AuthFI needs an email for every person.

From an OpenID Connect or social provider

This mapping is fixed. Assign groups and roles in AuthFI: they are not read from the provider.

From a SAML provider

AuthFI looks for the person's email in this order:

1. A NameID in email format
2. An attribute named email or mail
3. The attribute http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
4. The attribute urn:oid:0.9.2342.19200300.100.1.3

If your provider uses another name, map it. A mapping takes one of the provider's attributes to email, display_name or picture_url. In the console, open the provider's row on the Identity arrives tab of Integrations > Applications. The mapping is under What their identity provider sends, in the fields Email, Display name and Picture.

What AuthFI checks

AuthFI validates every answer from the provider before it signs the person in.

For an OpenID Connect or social provider:

• The ID token's signature (RS256), issuer, audience, expiry and nonce are valid.
• The provider does not report email_verified as false.
• If the connection lists email domains, the person's email is in one of them. For Google Workspace, the token's hd claim matches too.

For a SAML provider:

• The assertion's signature verifies against the certificate you entered.
• An answer to a request that AuthFI sent matches that request, and arrives within 10 minutes.
• The assertion has not been used before.
• The assertion carries an email.

How accounts are linked

When a person signs in through a connection, AuthFI finds or creates their account in this order:

1. If the provider's account was linked before, the person is signed in to the same AuthFI account.
2. Otherwise, if an account with that verified email exists, the two are linked.
3. Otherwise, AuthFI creates a new, active account, with the email marked verified.

Tokens issued from the session carry fed in the amr claim. Your project's rule for multi-factor authentication (MFA) still applies after the provider has signed the person in.

Troubleshooting

Next steps