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 also use the Login API to sign your users in 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 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.
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 not 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 all are possible via custom 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
-
Passwordless authentication
-
Password expired
-
Account lockout by administrative decision or failed attempts
-
Password validation failed
-
Breach password detection
-
Federated log in with IdPs such as Google and Microsoft Active Directory
-
Advanced self service registration forms
-
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.
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 is the | Who initiates SSO? | Replay protection? | More info |
|---|---|---|---|
SP |
SP |
Yes, using |
|
SP |
IdP, sends unsolicited |
Yes, using internal mechanism |
|
IdP |
SP |
The SP must prevent replay attacks using our signed response |
|
IdP |
IdP |
N/A |
Not currently supported. If of interest, please file an issue |
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 MultiFactor Authentication.
-
Identity Providers allow you to federate authentication decisions to social or standards based providers.
-
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.