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
  • 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
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • 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
      • 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
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • 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 with Azure AD

    FusionAuth Reactor logo

    This feature is only available in paid plans. Please visit our pricing page to learn more.

    Configure SAML v2 for Azure AD

    This documentation will guide you in configuring SAML v2 IdP for Azure AD. In this case, FusionAuth will act as Service Provider (SP) to Azure AD (IdP). Functionally, the result will allow you to display a "Login with Azure AD" button on your FusionAuth login page and connect via SAML to Azure AD users/applications.

    New Login With Azure-Button

    Create an Application in Azure

    This guide uses SAML and Azure Single Sign-on functionality.

    If you have already configured an Azure AD Enterprise application, skip this section. If you have not, please follow the brief steps outlined below:

    1. From the Azure account portal navigate to Enterprise Applications.

    2. At the top of the screen click on New application

    3. Click on Create your own application

    4. Name the application

    5. Select the third option - Integrate any other application you don’t find in the gallery (Non-gallery).

    6. Click Create

    Create Azure AD Application

    Configure Your Azure Application

    From your application home screen, click on Single sign-on. Select the SAML option.

    Configure Single-sign on saml

    There are five steps to configure Azure AD. However, there is a bit of a procedural dilemma. Before you can move forward, you need an Entity ID (in this case, this will be obtained from our FusionAuth IdP once created) so that Azure AD can generate a X.509 certificate. However, before you can create an IdP in FusionAuth to get the Entity ID, you need an X.509 certificate. The below steps will solve this problem by:

    1. Creating a "placeholder" X.509 certificate and importing this into Key Master.

    2. Making a SAML IdP in FusionAuth (Entity Id) with a placeholder certificate selected.

    3. Updating your Azure AD Enterprise application with values from your newly created IdP, thereby getting a valid X.509 certificate.

    4. Revisiting your SAML IdP in FusionAuth and updating with the correct X.509 certificate from the above step.

    5. Completing your integration.

    If you already have a valid X.509 certificate, you can complete step two above using this valid certificate and skip a few of the steps below.

    With that discussed, let us begin!

    Import a "placeholder" X.509 Certificate

    The first step is to import a "placeholder" certificate into Key Master.

    
    -----BEGIN CERTIFICATE-----
    MIIC1DCCAj2gAwIBAgIBADANBgkqhkiG9w0BAQ0FADCBhjELMAkGA1UEBhMCdXMx
    DzANBgNVBAgMBkRlbnZlcjETMBEGA1UECgwKRnVzaW9uQXV0aDEWMBQGA1UEAwwN
    RnVzaW9uQXV0aC5pbzETMBEGA1UECwwKRnVzaW9uQXV0aDEkMCIGCSqGSIb3DQEJ
    ARYVcmljaGFyZEBwaWVkcGlwZXIuY29tMB4XDTIyMDcxNjA1MDc1N1oXDTIzMDcx
    NjA1MDc1N1owgYYxCzAJBgNVBAYTAnVzMQ8wDQYDVQQIDAZEZW52ZXIxEzARBgNV
    BAoMCkZ1c2lvbkF1dGgxFjAUBgNVBAMMDUZ1c2lvbkF1dGguaW8xEzARBgNVBAsM
    CkZ1c2lvbkF1dGgxJDAiBgkqhkiG9w0BCQEWFXJpY2hhcmRAcGllZHBpcGVyLmNv
    bTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2FmZJHJFVEM9JwFd6Za87T0Z
    MtIL5djSFC/TBVqhCx15eauNGAV/RoulESA6qsI4LNrbJ8uEYDQa9UXAZCc9yRMa
    e/+E5XAApV4K06duo+vKon5L21YZ7HxzjUfL3bhLqKvpFWCQkNrH0rxgPCGwzh7N
    T24sFcKwaVvBdknm9i8CAwEAAaNQME4wHQYDVR0OBBYEFLdhYvqAwTBCEQsSZdKj
    UVR57CwDMB8GA1UdIwQYMBaAFLdhYvqAwTBCEQsSZdKjUVR57CwDMAwGA1UdEwQF
    MAMBAf8wDQYJKoZIhvcNAQENBQADgYEAIpQags/uHj0dyFcCtRcPeVEDUqBPZaGO
    M9kbFiGATlMNX4OiDvMUKs7Ag9109o0iLWPvLBQrMDn87fSy6+MUXZRS4asjzJCp
    5aVWSevI85H6xS8WXxFr21etaqfiE88Lw86gK5O4iKtMBtCnWA5iUc2EJ0citQ0G
    Pk8ybmMP1r8=
    -----END CERTIFICATE-----

    Using the above "placeholder" certificate, navigate to Settings → Key Master and click Import Certificate.

    Import Certificate

    After you configure Azure AD, you’ll get another X.509 certificate which will be the one actually used during a SAML login.

    Create a SAML v2 Identity Provider

    In the FusionAuth administrative user interface, navigate to Settings → Identity Providers → Add.

    The identity provider you will be adding is a SAML V2 identity provider.

    IdP SAML configuration

    The following fields will need to be completed.

    • Name. This is user-defined, so pick something that describes this connection such as "Pied Piper Azure AD".

    • IdP endpoint. This value can be obtained from your Azure AD Application as demonstrated below. You will want to copy the Login URL value from Azure AD into this field.

    Get Login URL values From Step Four

    • Verification key. For this value, use the placeholder certificate imported above. You will change this later.

    Be sure to check Debug Enabled. This will ensure debug information is written to the Event Log, which you can see by navigating to System → Event Log.

    Remember to disable this option when running in production.

    More information regarding the Event Log can be found below

    • API for Event Log

    • Admin UI and Troubleshooting

    Lastly, navigate to the Applications tab in your SAML V2 Idp.

    Enable this IdP for the appropriate Application.

    Enable IdP On Application

    Once saved, you may receive a CORS warning. Be sure to follow the onscreen instructions and this documentation.

    Linking Options

    If you are linking to a user on email, please configure the SAML IdP to find the email claim. This can be done by navigating to

    Settings → Identity Providers → Your SAML IdP → Edit

    and then click on the Options tab. The mapping can be referenced in the Email Claim field as below

    Setup custom email claim

    If you are using an existing Azure AD Application this email claim location may vary. Below is a demonstration of the email claim found in a default Azure AD Application.

    
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    If you are unsure of the best mapping in this step, the Event Log will provide valuable guidance indicating how FusionAuth and Azure are connecting.

    This claim can be found in the event log of a SAML auth handshake. In the case of a default Azure AD application, the email claim is nested under

    
    <AttributeStatement>
    // ...
        <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
            <AttributeValue>*your*email*</AttributeValue>
        </Attribute>
    // ...
    </AttributeStatement>

    Finish Setup of Azure AD Application

    With the FusionAuth Identity Provider set up, the next step is to input the newly created values into your Azure AD Application.

    Navigate to your Azure AD application. Under step one, click on the pencil to edit.

    SAML 5 steps overview

    On this screen add the Entity ID and Reply URL. The Entity ID can be obtained by going to Setting → Identity Providers and clicking on the magnifying glass in the row of your Identity Provider. This value is synonymous with the Issuer value in FusionAuth. Input the Entity and ACS value from FusionAuth into Azure AD.

    Integration Details

    Download and Import X.509 Certificate

    Previously, you created and used a "placeholder" X.509 certificate. At this point, you can change this. From the overview of your SAML application in Azure AD, under step three, you should find a Certificate (Base64) to download.

    Generated Certificate

    Next, import this certificate into Key Master (Settings → Key Master → Import Certificate). Leave the Key identifier property blank, as this will be autogenerated from the thumbprint in the existing certificate.

    Update the certificate used on your IdP configuration (Settings → Identity Providers → your SAML IdP → Verification Key) with this new X.509 certificate. You can also remove the "placeholder" certificate from Key Master once complete.

    Leave the Key identifier property blank, as this will be autogenerated from the thumbprint of the existing certificate. Otherwise, FusionAuth will not be able to validate the signature of the AuthN response from Azure AD when using this integration.

    Configure the FusionAuth Application Redirect URL

    You also need to configure where you will redirect users once they are complete with their Azure AD login.

    This URL is where a user will end up after authentication and may be any value URL.

    Navigate to Applications → Your Application → OAuth. Update the Authorized redirect URLs field as appropriate.

    Ensure the Authorization Code grant is enabled.

    Configure a redirect URL within FusionAuth

    Assign Users

    If you are using an existing Azure AD application with assigned users, you may skip this step.

    Before you can complete your integration, assign Azure AD users to your Azure AD application. Add a user by navigating to Users and groups and clicking on the Add user/group button. Follow the instructions to select and add a user.

    Add a User to Azure

    Complete the Login

    At this point, what remains is to attempt a login. To test quickly, log into the FusionAuth administrative user interface. Navigate to Applications → Your Application Click the View link (the magnify icon), then scroll to the OAuth2 & OpenID Connect Integration details section and look for the Login URL. Copy this.

    Get OAuth2 Login URL

    Open a new tab, paste in the login URL, and you should see your new SAML Azure AD IdP login button.

    New Login With Azure-Button

    Click on that button, log in with one of the Azure AD users you configured above, and you should arrive back at your redirect URL.

    If your integration fails, remember to review the Event Logs (System > Event Log)

    More information regarding the Event Log can be found below:

    • API for Event Log

    • Admin UI and Troubleshooting

    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
    Subscribe for developer updates