FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Java Spring
      • Python Django
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • PagerDuty
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
      • Kickstart Custom Theme
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    SAML v2 IdP Initiated Identity Provider

    FusionAuth Reactor logo

    This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.

    Overview

    Available since 1.26.0

    Using IdP initiated SSO with this Identity Provider is not recommended and is inherently less secure than a service provider initiated login.

    In general FusionAuth does not recommend you utilize this type of login due to the inherent risks of accepting an unsolicited authentication response from a third-party identity provider.

    If you must enable this feature to support a legacy integration or because the user experience is of the highest concern, then proceed.

    Please note that starting in version 1.43.0 this configuration is only necessary if you only want support for IdP initiated configuration. The SAMLv2 Identity Provider now offers a unified option to support both IdP and SP initiated login.

    This FusionAuth Identity Provider allows you to configure FusionAuth to accept a SAML request initiated by a SAMLv2 identity provider. With this Identity Provider, FusionAuth is acting as the SAMLv2 service provider (SP).

    Typically, a SAML flow begins at a service provider such as FusionAuth. In a service provider initiated login, the SAML Authentication Response is returned to the service provider in response to an authentication request. FusionAuth can validate certain parameters and only accept a response for a request that FusionAuth initiated.

    In contrast, during an identity provider initiated login, the third-party identity provider sends FusionAuth a SAML Authentication Response indicating a user has been authenticated. FusionAuth did not initiate this request so it is unexpected and FusionAuth does not have the full context. This limits what can be verified and requires FusionAuth to allow a cross site request from this third party.

    • Create a SAML v2 IdP Initiated Identity Provider

    • Integration Details

    • CORS Configuration

    • Troubleshooting

    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 IdP Initiated SSO for Okta

    Once you have completed this configuration you will be able to log in to FusionAuth directly from a SAMLv2 IdP.

    Create a SAML v2 IdP Initiated Identity Provider

    To create an Identity Provider navigate to Settings → Identity Providers and click Add provider and select SAML v2 IdP Initiated.

    This will take you to the Add SAML v2 IdP Initiated panel. Here you will need to fill out the required fields.

    Add SAML v2 IdP Initiated

    Form Fields

    Enabled Required

    Determines if this provider is enabled. If it is false then it will be disabled globally.

    Id Optional

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

    Name Required

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

    Issuer Required

    The EntityId (unique identifier) of the SAML v2 identity provider. This value should be provided to you.

    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

    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.

    Options

    Add SAML v2 Options section

    Form Fields

    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.

    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, FusionAuth will display values likely required by your SAML v2 Identity Provider 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 necessary values to configure an integration with a SAMLv2 IdP.

    SAML v2 Integration Details

    View the SAMLv2 identity provider details

    Fields

    Callback URL (ACS)

    An Assertion Consumer Service (or ACS) is the location at a service provider that accepts messages to establish a session based on the assertion.

    By default the redirect URI will be the first Authorized redirect URI found in the FusionAuth Application OAuth configuration. To specify a redirect URI send the authorized URI in the RelayState parameter. Support for using the RelayState in this manner is supported in FusionAuth version greater than or equal to 1.41.0. In prior versions, append a query parameter named redirect_uri to the ACS in the IdP configuration.

    Note: For IdP initiated logins in order to receive a refresh token the query parameter ?scope=offline_access will need to be appended to the url. When logging into the FusionAuth Admin application this parameter is included by default and does not need to be supplied.

    Issuer

    The service provider EntityId. This is a URL.

    Metadata URL

    The URL where the service provider metadata resides.

    CORS Configuration

    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.

    Troubleshooting

    To troubleshoot, turn on the Debug option and then navigate to System → Event Log.

    Proceed through the SAML flow and review the Event log entries to see if there are any configuration issues.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Subscribe for developer updates