Concerned about Okta's acquisition of Auth0?   Learn how to migrate from Auth0 to FusionAuth

FusionAuth logo
FusionAuth logo
  • Features
    FusionAuth Reactor

    FusionAuth Reactor is a powerful suite of features developed to extend FusionAuth's core functionality.

    • Flexible Architecture   Flexible Architecture
    • Auth the Way You Want It   Auth the Way You Want It
    • Security & Compliance   Security & Compliance
    • Ultimate Password Control   Ultimate Password Control
    • Customizable User Experience   Customizable User Experience
    • Advanced Registration Forms   Advanced Registration Forms
    • Built for Devs   Built for Devs
    • User Management & Reporting   User Management & Reporting
    • Scalability   Scalability
    • Single Sign-on   Single Sign-on
    • Breached Password Detection   Breached Password Detection
    • Connectors   Connectors
    • FusionAuth Reactor   FusionAuth Reactor
  • Pricing
    Cloud Pricing

    Let us host, monitor, manage, and maintain your deployments in your own private cloud.

    SEE PRICING cloud pricing   See FusionAuth Cloud Pricing
    Editions Pricing

    A powerful set of features with available support that extends FusionAuth's core functionality.

    SEE PRICING edition pricing   See FusionAuth Edition Pricing
    Editions + Cloud

    FusionAuth will handle everything so you can get back to building something awesome.

    GET STARTED Get started
  • Docs
  • Downloads
  • Resources
    FusionAuth Resources
    • Upgrade from SaaS
    • Upgrade from Open Source
    • Upgrade from Home Grown
    • Blog   Blog
    • Forum   Forum
    • Community & Support   Community & Support
    • Customer & Partners   Customers & Partners
    • Video & Podcasts   Videos & Podcasts
    • Getting Started   Getting Started
    • Auth0 Migration   Migrate from Auth0
  • Expert Advice
    Expert Advice for Developers

    Learn everything you need to know about authentication, authorization, identity, and access management from our team of industry experts.

    • Authentication   Authentication
    • CIAM   CIAM
    • Identity Basics   Identity Basics
    • OAuth   OAuth
    • Security   Security
    • Tokens   Tokens
    • Dev Tools   Dev Tools
  • Account
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Reactor
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Entity Management
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Search
    • Authentication and Authorization
    • Integration Points
    • Localization and Internationalization
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Securing
    • Upgrading
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consent
    • Emails
    • Entity Types
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Apple
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Twitter
      • OpenID Connect
      • SAML v2
      • External JWT
    • Integrations
    • JWT
    • Keys
    • Lambdas
    • Login
    • Passwordless
    • Registrations
    • Reports
    • System
    • Tenants
    • Themes
    • Two Factor
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Localization
    • Examples
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
  • Events & Webhooks
    • Overview
    • Events
    • Writing a Webhook
    • Securing Webhooks
  • Example Apps
    • Overview
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • Twitter Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Twitter
    • OpenID Connect
      • Overview
      • Azure AD
      • Github
      • Discord
    • SAML v2
      • Overview
      • ADFS
    • External JWT
      • Overview
      • Example
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Writing a Plugin
    • Password Encryptors
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Migration
    • Migration From Auth0
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • Setup Wizard & First Login
    • Register/Login a User
    • Migrate Users
    • JSON Web Tokens
    • Authentication Tokens
    • Start and Stop FusionAuth
    • Switch Search Engines
    • User Account Lockout
    • Two Factor
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Encryptors
  • Release Notes
  • Troubleshooting

SAML v2 Identity Provider

Overview

Adding a Login button for a third-party SAML v2 Identity Provider to FusionAuth is simple. This guide will walk you through the steps necessary to enable a SAML v2 Identity Provider.

This document covers the configuration for FusionAuth’s SAML v2 Identity Provider, where FusionAuth is a relying party. This is useful if you want to allow users to log into either FusionAuth’s UI or your applications via a third party SAML v2 identity provider.

If you are looking for instructions to set up FusionAuth as a SAML v2 IdP (i.e. you want FusionAuth to be the system of record for your users, and other applications authenticate against FusionAuth), consult the SAML v2 IdP documentation.

In this example FusionAuth is the SAML service provider and we are configuring a connection to a SAML Identity Provider which will be the system of record for user data.

  • Create a SAML v2 Identity Provider

  • Integration Details

  • CORS Configuration


We also provide specific examples for configuring SAML with some providers whose implementation requires unique configuration. If you’d like us to provide additional examples, please open a request on GitHub.

  • Configure SAML v2 for Active Directory Federation Services (ADFS)


Once you have completed this configuration you will be able to enable the SAML v2 login button for one or more FusionAuth Applications. Below is an example login page with a SAML v2 Identity Provider enabled for PiedPiper.

SAML v2 Login

Create a SAML v2 Identity Provider

To create an Identity Provider navigate to Settings → Identity Providers and click Add provider and select SAML v2 from the dialog.

This will take you to the Add SAML v2 panel. Here you will need to fill out the required fields. If you do not know the IdP endpoint of your SAML v2 provider, you will need to contact the identity provider owner to get the URL.

To enable this identity provider for an application, find your application name in the Applications configuration section at the bottom of this panel. You will always see the FusionAuth application, this application represents the FusionAuth administrative user interface. If you wish to be able to log into FusionAuth with this provider, you may enable this application.

In the following screenshot you will see that we have enabled this login provider for the Pied Piper application and enabled Create registration. Enabling create registration means that a user does not need to be manually registered for the application prior to using this login provider.

For example, when a new user attempts to log into Pied Piper using SAMLv2, if their user does not exist in FusionAuth it will be created dynamically, and if the Create registration toggle has been enabled, the user will also be registered for Pied Piper and assigned any default roles assigned by the application.

If you do not wish to automatically provision a user for this Application when logging in with SAMLv2, leave Create registration off. You will need to manually register a user for this application before they may Sign in with SAMLv2.

That’s it, now the Login with PiedPiper button will show up on the login page.

Add SAML v2

Form Fields

Id Optional

An optional UUID. When this value is omitted a unique Id will be generated automatically.

Name Required

A unique name to identity the identity provider. This name is for display purposes only and it can be modified later if desired.

IdP endpoint Required

The URL of the SAML identity providers login page.

Issuer Required

The name of your FusionAuth deployment that is configured in the SAML identity provider.

Use NameId for email Optional

If this is enabled, FusionAuth will assume that the NameID in the SAML response contains the email address of the user.

Email claim required Required

The name of the email claim returned in the SAML response.

When Use NameId for email is enabled this field will not be displayed and will not be required.

Verification key Required

The public key or certificate that you must import into FusionAuth’s KeyMaster. This is the public key provided to you by the identity provider.

Use POST method Optional

When enabled the authentication request will use the HTTP POST binding with the identity provider instead of the default Redirect binding which uses the HTTP GET method.

Sign requests Optional

When enabled authentication requests sent to the Identity Provider will be signed.

Request signing key Optional

The key used to sign the SAML request. Required when Sign request is enabled. To create, manage or import a key, navigate to Settings → Key Master.

Canonicalization method Optional

The XML signature canonicalization method used when digesting and signing the SAML request. Required when Use POST method and Sign request are enabled.

Options

Add SAML v2 Options section

Form Fields

Button text Required

The text to be displayed in the button on the login form. This value defaults to Login with SAML but it may be modified to your preference.

Button image Optional

The image to be displayed in the button on the login form. When this value is omitted a default SAML icon will be displayed on the login button.

Reconcile lambda Optional

A lambda maps custom claims returned from the SAML response into the FusionAuth User and Registration. To learn more about creating a lambda, view the SAML v2 Reconcile lambda documentation.

To configure a lambda, navigate to Settings → Lambdas.

Managed domains Optional

You may optionally scope this identity provider to one or more managed domains. For example, if you were to use a SAML v2 identity provider for your employees, you may add your company domain piedpiper.com to this field.

Adding one or more managed domains for this configuration will cause this provider not to be displayed as a button on your login page. Instead of a button the login form will first ask the user for their email address. If the user’s email address matches one of the configured domains the user will then be redirected to this login provider to complete authentication. If the user’s email address does not match one of the configured domains, the user will be prompted for a password and they will be authenticated using FusionAuth.

These configured domains will be used by the Lookup API.

Debug Optional

Some identity providers are not compliant with the SAML and XML signing specifications. This makes it challenging to get them working with FusionAuth.

If you are running into integration issues, toggle this setting on and FusionAuth will output debugging information into the Event Log during a SAML login. You can find the event log in System → Event Log.

Integration Details

After configuring the Identity Provider, you can view the details to see values that will likely be required by your SAML v2 Identity Provider in order to trust FusionAuth as a relying party. Do so by navigating to Settings → Identity Providers and click the green magnifying glass on your SAML provider.

View the identity provider list

When viewing the details, scroll to the SAML v2 Integration details section. There you will find the needed values to configure an integration with a SAMLv2 IdP.

View the SAMLv2 identity provider details

CORS Configuration

In order to complete the login request, the SAML v2 Identity Provider will make an HTTP POST request to the callback URL in FusionAuth. In order for this request to be allowed through the CORS filter you will need to navigate to Settings → System → CORS and add the SAML IdP origin as an Allowed Origin the CORS configuration.

Once you complete your SAML v2 Identity Provider configuration, if your CORS configuration is not yet configured to allow the login request to complete you wil be shown the following warning prompting you to complete the CORS configuration. See CORS Filter reference for additional details on modifying the CORS configuration.

SAMLv2 CORS Warning

Troubleshooting

A common pattern is to set up SAML as the login method for the FusionAuth application. This lets you keep all your users in the SAML system, and have FusionAuth delegate auth decisions to it. However, if your Identity Provider isn’t configured correctly, you can end up in a dead end, unable to log in. This might happen if you:

  • Set up SAML as the authentication method for your FusionAuth admin application.

  • Set the Managed domains to your domain. For example, example.com.

  • Don’t have any users with a domain that is different than example.com.

  • Accidentally misconfigure SAML and break authentication.

  • Log out of the FusionAuth admin application.

You won’t be able to log in to the FusionAuth admin application to correct the misconfiguration. You’ve locked down the FusionAuth admin application so that only valid logins can access it, but because of the misconfiguration, there is no account with a valid SAML login.

Unable to login with a managed domain and misconfigured Identity Provider.

This is a problem, but not an insurmountable one. Your options depend on when you discover the issue. If you are beginning your SAML configuration, you can avoid this scenario. Follow these steps:

  • Don’t set any value of Managed domains before you have tested the SAML configuration.

  • Test authentication in a different or incognito browser window, ensuring that an admin user account is always accessible to modify configuration.

  • Add an admin user account with a domain not in the Managed domains setting. Ensure this user is registered with the FusionAuth admin application and has the admin role.

  • Set up an API key. Navigate to Settings → API Keys to do so and make sure it has privileges to create users and registrations. This will open up options in the future to reset settings without using the administrative user interface.

If you are currently locked out of your FusionAuth application, you have fewer options:

  • If you have a known username and password that are not delegated to SAML (perhaps the initial account created when you set up FusionAuth) proceed to the FusionAuth admin login page. Append &showPasswordField=true to the end of the login URL. This will force the UI to show the password field.

  • If you have an API key with appropriate privileges, you can modify the configuration without using the administrative user interface. Add an admin user with a different email domain and sign into the admin interface to correct your SAML configuration. Here’s how you might do so (3c219e58-ed0e-4b18-ad48-f4f92793ae32 is the FusionAuth application Id):

Adding a New Admin User With a Different Domain
curl -XPOST -H "Authorization: $API_KEY" -H "Content-Type: application/json" \
-d '{"user": {"email": "user@differentdomain.com","password":"password"}, "registration": {"applicationId" : "3c219e58-ed0e-4b18-ad48-f4f92793ae32","roles":["admin"]}}' \
https://local.fusionauth.io/api/user/registration

If you have neither an API key nor a known user, you can restore from a database backup, modify the database directly if you have access, or re-install FusionAuth.

Feedback

How helpful was this page?

See a problem?

File an issue in our docs repo

Quick Links

  • Download
  • Cloud Pricing
  • Editions Pricing
  • Contact Us
  • Jobs (come work with us)
  • My Account

Resources

  • Docs
  • Blog
  • Community & Support
  • Upgrade from SaaS
  • Upgrade from Homegrown
  • Upgrade from Open Source

Everything Else

  • Privacy Policy
  • Product Privacy Policy
  • License
  • License FAQ
  • Security (contact, bug bounty, etc)
  • Technical Support

Connect with Us

logo
Subscribe for Updates
We only send dev friendly newsletters. No marketing fluff!
© 2021 FusionAuth