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:
- Cookie: send the token down to the browser as a
Secure,HttpOnlycookie. If you don’t require cross-site cookie sharing, setSameSitetoStrict. Otherwise, setSameSitetoLax, which will share the cookies in certain situations. Learn more aboutSameSitesettings. - BFF/Server-side Session: store the token server side, in a session. This is also known as the “backend for frontend” or BFF pattern. 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.
- Native Secure Storage: when the client is a native mobile app, store the token in a secure storage area such as iOS Keychain or Android Keystore.
Here is a table of characteristics of recommended JWT storage options.
| Feature | Cookie | BFF/Server-side Session | Native Secure Storage |
|---|---|---|---|
| Scalable client API requests | Yes | No | Yes |
| Revocation possible | Yes | Yes | Yes |
| Revocation straightforward | No | Yes | No |
| Sticky sessions or session datastore required | No | Yes | No |
| Token sent on HTTP API requests automatically | Yes (you may need to tweak the credentials option) | No | No |
| Token can be presented to APIs on other domains | No | Yes (via server-side requests) | Yes |
| Works in a web browser | No | Yes | No |
The proper JWT storage choice is based on your threat modeling and how much risk a particular service can tolerate. You can also 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.
Here is a more full featured list of token storage options and security considerations.
| Option | Strengths | Weaknesses | Security Considerations | Recommended |
|---|---|---|---|---|
Secure, HTTPOnly cookies | Tokens sent automatically when credentials option sent, widely supported | Won’t work if clients are not on same domain as the APIs, requires a browser, APIs must look for access token in cookie header, not in other places | Reduces attack surface by preventing JavaScript from accessing tokens, XSS resistant, but requires correct cookie configuration and same-domain policies. | |
| Backend for frontend (BFF)/Sessions | Easy to revoke tokens, works with any client, can be combined with cookie approach to provide cross domain access if some APIs live on different domains | Additional server side component, less scalable because you are routing all API requests through the BFF, single point of failure for all API access | Minimizes token exposure by never sharing tokens with the client, but introduces a new critical infrastructure component that must be secured | |
| Native secure storage | OS-provided secure storage options like iOS Keychain or Android Keystore prevent token exfiltration | Platform-specific implementation | Prevents exfiltration by malicious apps, use TLS to prevent attacker-in-the-middle attacks | |
| Mutual-TLS (MTLS) | Tokens are bound to client, IETF standard | Not widely supported, requires every client to have an X.509 certificate | Offers strong token-binding security, but operational complexity and certificate management introduce significant overhead | (when available) |
| Distributed Proof of Possession (DPoP) | Tokens are bound to client, IETF standard | Not widely supported, requires APIs to do extra work to verify the token, client must do extra work to send the token, still must take care to avoid exfiltration of key | Enhances token security by binding it to a client, but susceptible to implementation flaws and requires stringent key management | (when available) |
| Local Storage, IndexedDB | JavaScript can access token and send requests using Authorization or other expected header, supported by some frameworks (Amplify) | Tokens vulnerable to exfiltration by any JavaScript running on the page | Highly vulnerable to XSS attacks | |
| In Memory | Your code can access tokens but other code cannot | Tokens lost when the client reloads | Reduces persistence of tokens, limiting exposure | |
| Web workers | Browser APIs provide a layer of isolation between the web worker and the access token | All fetch calls must pass through web worker, have to use a library or write web worker integration code, malicious code may still be able to get data via the web worker, access token is removed when page is reloaded | Provides isolation for tokens, but risks persist with malicious code targeting the web worker or intercepting network traffic |
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
| FusionAuth is the | Login initiated by | Replay protection | More details |
|---|---|---|---|
| Service Provider | Service Provider | Yes | SAML v2 Identity Provider |
| Service Provider | Identity Provider | Yes | SAML v2 IdP Initiated Identity Provider, SAML v2 Identity Provider |
| Identity Provider | Service Provider | No. This is managed by the SP. | SAML v2 |
| Identity Provider | Identity Provider | No. 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:
- 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.