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

    External JWT Identity Provider

    Overview

    The External JWT Identity Provider is not intended to provide a login button in FusionAuth. Instead, this configuration is intended for use with the JWT Reconcile API.

    • External JWT API

    • Reconcile a JWT API

    Using this identity provider allows you to authenticate with a third party that can provide you a JSON Web Token (JWT). Then you may take this JWT and send it to FusionAuth to reconcile the user. The reconcile process is essentially logging that user into a particular FusionAuth application.

    The configuration for this identity provider allows you to configure some claim mapping from the third party JWT to the FusionAuth user, and it will require one or more keys that will allow FusionAuth to verify the signature of the third party JWT. These keys will be added to the Verification Keys section documented below.

    This external JWT Identity Provider flow is not compatible with the hosted login pages. This integration is accessible through our API only.

    Additionally, if you are integrating with any of the identity providers for which there is a provided Identity Provider integration (whether specific like Facebook or generic like OIDC), prefer those options over this provider.

    In general, you should use the /api/identity-provider/login endpoint of another Identity Provider rather than the External JWT provider if one is available.

    If you are looking to add a login button to FusionAuth for users to authenticate against a third party identity provider, this is not the configuration you’re looking for, move along.

    Create an External JWT Identity Provider

    To create an Identity Provider navigate to Settings → Identity Providers and click Add provider and select External JWT from the dialog. This will take you to the Add panel, and you will need to fill out the required fields.

    • Applications

    • JWT

    • Managed Domains

    • Verification Keys

    • OAuth

    Add External JWT

    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 identify the identity provider. This name is for display purposes only and it can be modified later if desired.

    Reconcile lambda Optional Available since 1.17.0

    A lambda may be utilized to map custom claims from the JWT. This may be used in addition to, or in place of the claim mapping on the JWT tab.

    To configure a lambda, navigate to Customizations → Lambdas.

    Debug enabled Optional default is false

    Enable debug to create an event log to assist you in debugging integration errors.

    Applications

    To enable this identity provider for an application, find your application name in the table. You will always see the FusionAuth application, this application represents the FusionAuth user interface. If you wish to be able to log into FusionAuth with this provider you may enable this application.

    In the above 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 before using this login provider.

    For example, when a new user attempts to log into Pied Piper using this identity provider, 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 PiedPiper, leave Create registration off and you will need to manually register a user for this application before they may complete login with this provider.

    JWT

    This configuration is necessary to allow FusionAuth to properly inspect the third-party JWT once the signature has been verified.

    Add External JWT

    Form Fields

    Unique claim Required

    This value is the name of the claim in the third-party JWT where FusionAuth can find the user’s email address. The email address will be used in FusionAuth to uniquely identify a user.

    This field defaults to email, this is likely the correct claim name.

    Header key identifier Required

    This value is the name of the claim in the third-party JWT header FusionAuth can find the identifier used to indicate which key pair was used to generate the JWT signature. This allows FusionAuth to use the correct key if more than one key is provided in the Verification Keys configuration.

    This field defaults to kid, this is a common identifier used in the JWT header to identify the key used to generate the signature.

    Add Claim Mapping Dialog

    If you click on the Add Claim button on this page you will be presented with the following dialog.

    Add Claim Mapping

    Form Fields

    Incoming claim Required

    The name of the claim in the third-party JWT that you would like to map to a FusionAuth user claim

    FusionAuth claim Required

    The FusionAuth user claim to receive the value of the specified claim in the third-party JWT. If you select the special values UserData or RegistrationData the value will be stored in either the user or registration data with the key being the claim name.

    For example, if you select company as the incoming claim, and specify RegistrationData, the claim will be stored in the registration data for the corresponding application.

    
    {
     "registration": {
       "data": {
        "company": "Acme. Corp"
       }
     }
    }

    Managed Domains

    To successfully reconcile a JWT to FusionAuth using this identity provider, you can optionally specify one more managed domains. A managed domain will indicate to FusionAuth this identity provider can reconcile a user based upon their email address.

    For example, if a user’s email address is jared@piedpiper.com, in order for a JWT owned by Jared to be reconciled to FusionAuth using this identity provider, piedpiper.com could be configured as a managed domain. You may leave this blank. If you do so, then any email can be used with this identity provider. This is helpful if you are not certain which email domains your users will have.

    A domain may only be managed by a single identity provider. More than one domain may be added per identity provider.

    Add External JWT

    Form Fields

    Managed domains Optional

    This identity provider may only be used to reconcile a user that has an email address that matches a configured domain. If you do not know which domains you would like to manage, you may leave this empty for now and return and add them later.

    If you would like to add more than one domain, use a separate line per domain.

    These configured domains will be used by the Lookup API and the Reconcile API.

    Verification Keys

    For FusionAuth to use this identity provider to reconcile third-party JWTs, you will need to provide one or more verification keys. This key will likely be an X.509 public certificate or other PEM encoded public key that may be used to verify the JWT signature.

    Add External JWT

    Add Key Dialog

    If you click on the Add Key button on this page you will be presented with the following dialog.

    Add Verification Key

    Form Fields

    Default key Defaults to false

    Optionally a single key may be designated as the default key. You may use this feature if the JWT you will be sending to FusionAuth to be reconciled will not have a key identifier kid value in the JWT header.

    In this scenario, there will be no kid to indicate which key was used to sign the JWT, so if a default key has been designated, the default key will be used to verify the signature.

    If you only have JWTs with the kid claim, or another key identifier, you will not use this feature. When this toggle is enabled, the Key identifier field will be disabled and no longer required.

    Key identifier required

    The string identifier for this key. If this is an X.509 certificate you may leave this field blank and the X.509 certificate thumbprint will be generated for you.

    If this is a normal PEM encoded RSA public key, for example, you will need to provide the key identifier. This identifier should be the value that will be written to the kid header of the JWT provided by the external identity provider.

    Encoded key required

    The PEM encoded key may be an X.509 certificate or other PEM encoded public key.

    OAuth

    The OAuth configuration is not a functional part of this identity provider. Instead, it is provided for convenience only.

    If you review the API response of the Lookup API you will notice it returns these two values. You may use these values then at runtime to identify where to redirect the user to complete authentication.

    Add External JWT

    Form Fields

    Authorization endpoint Optional

    The URL of the OAuth 2.0 Authorization endpoint in use by the third party identity provider that will be providing the third-party JWT.

    Token endpoint Optional

    The URL of the OAuth 2.0 Token endpoint in use by the third party identity provider that will be providing the third-party JWT.

    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