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, the Login API, or federated authentication.

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.

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.

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.

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.

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:

Table 1. JWT Storage Options

FeatureCookieServer Side Session
Allows for easy horizontal scalingYesNo
Revocation possibleYesYes
Revocation easyNoYes
Sticky sessions or session datastore requiredNoYes
Token transparently sent on requests (to APIs, etc)YesN/A
Token can be presented to APIs on domains other than that in which the cookie setting component residesNoYes (via server side requests)

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:

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.

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

FusionAuth is theLogin initiated byReplay protectionMore details
Service ProviderService ProviderYesSAML v2 Identity Provider
Service ProviderIdentity ProviderYesSAML v2 IdP Initiated Identity Provider, SAML v2 Identity Provider
Identity ProviderService ProviderNo. This is managed by the SP.SAML v2
Identity ProviderIdentity ProviderNo. This is managed by the SP.SAML v2

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:

Other Integration Points

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