Integration Points

Overview

You typically integrate FusionAuth into one or more applications. User data will live in FusionAuth (possibly synced with other data stores) and users will auth against it.

FusionAuth is a developer first platform and there are a large number of ways to integrate it into your new or existing applications.

Login Options

There are three main ways to have your users sign in: OAuth/OIDC/SAML, federated authentication, or the Login API.

OAuth/OIDC/SAML

The first option is to use OAuth/OIDC/SAML. These are standards and FusionAuth should work with any library or application which supports them. If you find a library which supports OAuth or OIDC and does not work with FusionAuth, please open a bug, as we want to know about it. You can also use a FusionAuth client library to help with the OAuth/OIDC flow.

Using OAuth/OIDC lets your users authenticate and authorize; they’ll receive the responses documented for each grant. If you choose SAML, configure FusionAuth as the IdP.

When you use this option, the data your client receives about the user is limited. You can put custom claims in your JWT using lambdas if what you need is in the user or the registration objects.

If this level of integration meets your needs, you’ll have more portability and less lock-in to FusionAuth.

The OAuth Authorization Code Grant

Federated Authentication

Federated authentication, where FusionAuth isn’t the system of record for users, is provided by Connectors and Identity Providers.

When this is used, FusionAuth will defer to the configured systems of record for authentication and authorization. Please consult the Connector or Identity Provider documentation for more information on these options.

Logging In With An Identity Provider

Login API

You can use the Login API to sign in your users directly. In this case, you will likely use one of the FusionAuth client libraries.

When a user signs in with this API, you receive the entire user object, as well as the JWT.

When you build on top of the Login API, you’re responsible for building the user interface for all login use cases. This gives you more control, as well. You can still use other FusionAuth provided user interfaces for use cases such as the forgot password flow.

Using the Login API means that since your application will see sensitive user credentials, you’ll need to ensure the application secures such data appropriately. This is in contrast with the OAuth grants, where only the identity provider has access to the credentials, and your application only sees tokens.

The Login API Flow

You can also use federation with the Login API. Create and configure an Identity Provider.

The Login API Flow When User Logs In With An Identity Provider Such As Google

Depending on the identity provider, you may be able to pass the token instead of the authorization code and redirect URI. In the case of a SAML provider, you’ll need to provide the SAML response. Please consult the provider specific API documentation for details.

JSON Web Tokens

FusionAuth can create signed JSON web tokens. Customize these using the JWT Populate Lambda. They can be signed with any of the supported key types.

When using OAuth/OIDC, there are multiple kinds of tokens: Access Tokens, Id Tokens and Refresh Tokens. The Login API can also generate a JWT.

These tokens can be consumed by APIs or other systems to verify that the holder of the token has been authorized by FusionAuth. Learn more about JWTs or decode a JWT.

Each JWT has a header, a payload and a signature. Here’s a diagram of a JWT:

JWT Storage

FusionAuth recommends the Authorization Code grant, where there is a server side component which exchanges the one-time use authorization code for an access token. This server side component offers a lot of flexibility when it comes to storing the JWT.

But what should you do with it? After all, an access token is a bearer token, and should be properly secured. What you do with the token depends on what you are using it for as well as your security requirements. If you are wondering about your options, here are a number of common login flows.

Recommended storage mechanisms include:

• sending the token down to the browser as a Secure, HttpOnly cookie. If you don’t require cross-site cookie sharing, set SameSite to Strict. Otherwise, set SameSite to Lax, which will share the cookies in certain situations. Learn more about SameSite settings.
• storing it server side, in a session. The session is typically managed by a framework, and ideally adheres to the same cookie storage recommendations. Learn more about server side sessions. Please consult your framework documentation around securing sessions and data in sessions.

Table 1. JWT Storage Options

The proper JWT storage choice should be based on your threat modeling. You can configure your JWTs to be short lived, which minimizes the amount of time a stolen JWT can be used.

If you need to lock down JWTs further, implement token sidejacking protection using cookies and a nonce. An alternative is DPoP, an open feature request for FusionAuth.

FusionAuth APIs

Whether you use the Login API, identity federation, or an OAuth grant, you can use additional FusionAuth APIs in your application.

These allow your application to access and modify data and entities beyond that available from OIDC/OAuth/SAML or a federated identity.

Common tasks such as registering a user to an application, removing them from a group, capturing a consent, or capturing custom data are accomplished with these APIs. APIs can also be used to manage entities other than users, such as applications, tenants or Identity Providers.

The upside of using these is the ability to leverage the FusionAuth data model and functionality. The downside is that your application is coupled to FusionAuth.

Hosted Login Pages

You’ll see the phrase “hosted login pages” used throughout the FusionAuth site. These are all the pages that your end user sees when you are hosting your login experience on FusionAuth, as opposed to within your application. These pages are themeable; you can make them look exactly like your website or application.

Using the hosted login pages has a number of advantages. By doing so, FusionAuth handles the complexity of a number of different auth related use cases. These use cases include, but are not limited to, the following:

• Log in
• Log out
• Registration
• Forgot password
• Email verification
• Changing a password
• Two factor authentication
• Magic link passwordless authentication
• WebAuthn/passkey passwordless authentication
• Password expired
• Account lockout by administrative decision or failed attempts
• Password validation failed
• Breach password detection
• Federated login with IdPs such as Google and Microsoft Active Directory
• Advanced self service registration forms
• Prompting for consent to requested OAuth scopes
• Linking between IdP accounts and FusionAuth accounts
• Multi application logout (OAuth front channel logout)

Additionally, when you use the hosted login pages, FusionAuth provides transparent single sign on (SSO) between applications as well as support for localization of the user interface.

The alternative to using the hosted login pages is building your own login experience. You can then use the APIs or an OAuth grant to authenticate your user against FusionAuth. This alternative gives you more control at the cost of more development effort.

For an example of how the hosted login pages help with common workflows, please review this video which walks through the forgot password workflow.

Hosted Backend

The Authorization Code grant requires the use of a server side application to do the token exchange. This is often called the “backend”. This server side code can securely hold secrets, which a client such as a single-page application (SPA) cannot. It also can send the access token to a SPA as a secure, HttpOnly cookie.

Running your own backend offers you a lot of flexibility. However, it is not the correct solution for all situations.

As of version 1.45, FusionAuth provides a hosted backend. This is included with every FusionAuth installation and can be used to quickly integrate OAuth into a front-end only application.

Please consult the Hosted Backend API documentation for more details. You can also work through a React quickstart which uses the hosted backend.

SAML Integration Options

You can use SAML to integrate with FusionAuth in a few different ways, depending on the role that FusionAuth is playing and your other needs.

FusionAuth supports both Service Provider initiated login, as well as Identity Provider initiated login in both the Service Provider and Identity Provider roles.

In other words, FusionAuth can act as a SAML v2 Identity Provider or a SAML v2 Service provider, and in either configuration both SP and IdP initiated login flows are supported.

SP (Service Provider) Initiated Login

This is a traditional integration and the Service Provider will initiate the login request to the Identity Provider by building an AuthN request and sending it to the Identity Provider.

To configure FusionAuth as the Service Provider, see SAML v2 Identity Provider. To configure FusionAuth as the Identity Provider, see SAML v2.

IdP (Identity Provider) Initiated Login

In this configuration, the login request is not solicited by the Service Provider, and instead the Identity Provider builds an AuthN response and sends it to the Service Provider.

To configure FusionAuth as the Service Provider, see SAML v2 Identity Provider and SAML v2 IdP Initiated Identity Provider. To configure FusionAuth as the Identity Provider, see SAML v2.

Table 2. Summary of SAML v2 integration options

Note: SP refers to the Service Provider, and IdP refers to the Identity Provider.

Client Side API Usage

When interacting with FusionAuth from a client side application, such as a React or Angular front end, you have a few options.

If you are authenticating the user, use the standard OAuth Authorization Code grant. You can either forward the browser or webview to FusionAuth or use an iframe.

If you are using one of the APIs which does not require an API key, such as the change password API, you can interact directly with the API. These APIs tend to be more limited in functionality when no API key is presented, but may suit your needs.

If you need to use an API requiring authentication from client code, such as the registration API, you have two options:

• Use a server side component which can securely hold the API key and monitor access for abuse. This can be in any server side language or framework. The client code then sends requests to the server side component, and the server side code makes requests of FusionAuth. This is the recommended option.
• Create an API key with extremely limited permissions and distribute it. Since stealing the key when used on the client side is trivial—all an attacker has to do is ‘view source’—make sure you have carefully considered the risk and result of someone stealing and using the key outside of your application. You can also monitor FusionAuth usage with webhooks, use IP ACLs to limit where the API key can be used from, or place an HTTP proxy in front of FusionAuth to further limit access. Plan to rotate the key regularly to limit the impact.

Other Integration Points

There are a number of other integration points in FusionAuth beyond the APIs.

• Connectors allow you to authenticate against external user data sources, and optionally migrate users into FusionAuth.
• Account Management Allows admins and users to dynamically edit user data, user passwords, and enable multi-factor authentication.
• Identity Providers allow you to federate authentication decisions to social or standards based providers. You can also specify a linking strategy which allows you to flexibly map between accounts with different identifiers.
• Lambdas allow you to run business logic at certain points in the authentication lifecycle.
• Plugins allow you to extend FusionAuth with custom Java code. Currently the main use is to allow you to use custom password hashing. This allows you to import user data from existing systems without requiring user password changes.
• Webhooks allow you to send data to external systems when events occur in FusionAuth.
• Monitoring provides insight into a FusionAuth instance’s debug messages, performance metrics and other data.