Add FusionAuth Login to an External Application

An external application is software you don't build, such as a SaaS product or an off-the-shelf tool. When the external application supports single sign-on, the external application can send users to FusionAuth to log in. FusionAuth acts as the identity provider, and users log in with their FusionAuth accounts. To add login to an application you build, see Add Login to Your App.

Before You Begin#

You need:

• Admin access to FusionAuth and to the single sign-on settings of the external application.
• A FusionAuth URL that the external application and your users' browsers can reach. Most SaaS products require an https URL on the public internet.
• A test user in the TenantA logical container for Users, Applications, and settings that is isolated from other Tenants. you plan to use.

Choose a Protocol#

Look in the external application's single sign-on settings for the supported protocols. The settings often appear under a name such as "SSO", "Identity Provider", or "Authentication". When the external application supports both OpenID Connect and SAML v2, use OpenID Connect. OpenID Connect needs fewer values and no certificate exchange.

For step-by-step guides for specific products, see the OpenID Connect integrations and the SAML v2 integrations.

Each external application needs its own ApplicationA software program that your users log in to through FusionAuth. in FusionAuth. Follow the section for your protocol to create the Application.

Configure OpenID Connect#

The external application acts as an OpenID Connect relying party. Most relying parties require the issuer in the tokens to match the FusionAuth URL. The setup wizard sets the issuer to the URL you used during setup, which might be localhost. Installs that skip the setup wizard, such as Kickstart installs, keep a placeholder such as https://example.com. New Tenants copy the issuer of the Default Tenant. To connect the external application to FusionAuth:

1. Navigate to Tenants and click next to your Tenant.
2. On the General tab, set Issuer to the FusionAuth URL, such as https://auth.example.com, and click .
3. In the external application, start adding an OpenID Connect identity provider. Copy the callback URL that the external application shows. The external application might call the URL the redirect URI or the sign-in redirect URL.
4. When the external application requires RS256 Id tokens and your Tenant signs tokens with an HMAC key, create an RSA key before you create the Application. See Sign Tokens with an RSA Key.
5. In FusionAuth, navigate to Applications and click .
6. Enter a Name and select the Tenant that holds the users who log in to the external application.
7. Select the OAuth tab and add the callback URL to Authorized redirect URLs.
8. When you created an RSA key, select the JWT tab and enable Enable application-level JWT override. Select the RSA key as the Access token signing key and the Id token signing key.
9. Click .
10. On the Applications page, open the action menu for your Application and select View .
11. Copy the Client Id, the Client secret, and the OpenID Connect Discovery URL from the dialog. For what each value means, see OAuth2 & OpenID Connect Integration Details.
12. In the external application, enter the client Id, the client secret, and the discovery URL. Request the openid, email, and profile scopes.
13. Save the identity provider in the external application.

When the external application asks for the issuer instead of the discovery URL, enter the Tenant Issuer. When the external application asks for each endpoint separately, copy the Token endpoint, Userinfo endpoint, and JSON Web Key (JWK) Set values from the View dialog. For the authorization endpoint, copy the Login URL and remove the query string, so that only the /oauth2/authorize URL remains.

Sign Tokens with an RSA Key#

Installs that skip the setup wizard sign tokens with HMAC keys. New Tenants copy the keys of the Default Tenant. With an HMAC key, FusionAuth signs the Id token with the client secret, and the JWKS endpoint doesn't publish the key. To check your Tenant, look at Id token signing key on the JWT tab of the Tenant. To create an RSA key for the Application:

1. Navigate to Settings -> Key Master .
2. Open the menu next to Generate EC key pair and select Generate RSA key pair .
3. Enter a name and save the key.

When you create the Application, select the RSA key on the JWT tab.

Configure SAML v2#

The external application acts as a SAML service provider. To connect the external application to FusionAuth:

1. In the external application, start adding a SAML identity provider. Copy the service provider entity Id and the Assertion Consumer Service (ACS) URL. Some external applications call the entity Id the audience or the issuer.
2. In FusionAuth, navigate to Applications and click .
3. Enter a Name and select the Tenant that holds the users who log in to the external application.
4. Select the SAML tab and enable Enable SAML v2.
5. Set Issuer to the entity Id from the external application.
6. Add the ACS URL to Authorized redirect URLs.
7. Click . FusionAuth generates a signing key for the Application.
8. On the Applications page, open the action menu for your Application and select View .
9. In the SAML v2 Integration details section, copy the Metadata URL. For the other values in the section, see SAML v2 Integration Details.
10. In the external application, import the metadata URL. When the external application can't import metadata, enter the Entity Id and Login URL instead. Then download the certificate: navigate to Settings -> Key Master , open the action menu for the key named SAML key generated for application followed by your Application name, and select Download .
11. Save the identity provider in the external application.

By default, the assertion identifies the user by email address and contains only the user's Id and email address. When the external application needs other attributes, such as names or roles, add a SAML v2 populate lambda and select the lambda as the Populate lambda on the SAML tab. For the NameID formats FusionAuth supports and the other SAML settings, see Host a SAML v2 Identity Provider.

Give Users Access#

Any user in the Tenant can log in to the external application by default. To limit login to users with a RegistrationThe association between a User and an Application. for the Application, enable Require registration to complete OAuth authorization on the OAuth tab of the Application. The setting applies to SAML v2 logins too.

To register a user, navigate to Users , click next to the user, and click Add registration. With OpenID Connect, FusionAuth adds the user's roles for the Application to the tokens as the roles claim. See Registrations.

Confirm the Login#

To confirm that login works:

1. Open the external application in a private browser window.
2. Start single sign-on from the external application's login page.
3. Confirm that the browser shows the FusionAuth login page.
4. Log in as the test user.
5. Confirm that the browser returns to the external application and that the test user is logged in.

When the login fails, enable Enable debug logging on the OAuth or SAML tab of the Application and try again. Read the details in System -> Event Log . Turn off debug logging when you finish.