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 on the Verification Keys section documented below.

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

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 prior to 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 Claim Mapping Dialog

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

==== 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

In order to successfully reconcile a JWT to FusionAuth using this identify provider, you will need to specify one more managed domains. A managed domain will indicate to FusionAuth that this identify provider is able to 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 will need to be configured as a managed domain.

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

Verification Keys

In order 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 Key Dialog

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

==== 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 will not have JWTs that do not contain the kid or other 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 identify provider.

Encoded key required

The PEM encoded key, this 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.