lifecycle / authenticate users / identity providers / External JWT

External JWT Example Usage

Example Usage

An Identity Provider in FusionAuth is a configuration that represents an external identity provider.

The Identity Providers APIs allow you to configure and manage how these external identity providers are utilized by FusionAuth to perform federated authentication.

A typical use case for federated login is when you have users that wish to log into your application but their password is stored and managed in another identity provider.

Overview

A concrete example of this scenario is when you have implemented FusionAuth as your primary identity provider and you have a subset of users that may exist in Active Directory that you need to authenticate to your application.

In the described example, Active Directory Federated Services, more generally referred to as ADFS provides an implementation of OAuth 2.0 which can be utilized by FusionAuth to federate login to ADFS and then reconcile the user to FusionAuth.

For example, during Login, collect the User’s email address and utilize the Lookup API to identify if this User is managed by an external Identity Provider. The result of this lookup may be cached in your application to limit additional requests during login. You may optionally not use the Lookup API at all, and manage this logic in your own application.

GET /api/identity-provider/lookup?domain=playtronics.com

The Lookup API will return a 200 indicating the users in the domain playtronics.com are managed, or a 404 indicating the domain is not managed by any configured identity provider.

If the email domain is not managed by an external identity provider, then you may continue to collect the password and authenticate the User against FusionAuth.

A managed domain means you should delegate authentication to the configured external identity provider. The JSON response body from the Lookup API will indicate which configured Identity Provider is managing the domain and is intended to give you enough information to redirect the browser to the external identity provider. The following is an example response body from the Lookup API when a 200 status code was returned.

Example Response JSON

{
  "identityProvider": {
    "applicationIds": [
      "0d5244df-053c-4ff6-b2db-1e04c388dae3"
    ],
    "id": "a4e78daa-33a6-4844-b081-7779af1f09a4",
    "name": "Acme Corp. ADFS OpenID Connect",
    "oauth2": {
      "authorization_endpoint": "https://acme.com/adfs/oauth2/authorize?client_id=cf3b00da-9551-460a-ad18-33232e6cbff0&response_type=code&redirect_uri=https://acme.com/oauth2/redirect",
      "token_endpoint": "https://acme.com/adfs/oauth2/token"
    }
  }
}

The authorization_endpoint value configured as part of the Identity Provider and returned in this response is intended to be used to redirect the browser to start the OAuth workflow with the external identity provider.

Your application will need to handle the redirect from the Authorize endpoint and complete the OAuth workflow by making a request to the Token endpoint to obtain the access token. This access token is assumed be a JSON Web Token which you’ll then send to FusionAuth to reconcile this token and complete the login process.

To complete the login process by reconciling the User represented by the JWT issued by the external identity provider send this JWT to FusionAuth using the Reconcile API.

The Reconcile API will consume the JWT, validate it was issued by the configured Identity Provider and then using the identity claims included in the token payload the User will be created if they do not yet exist in FusionAuth, and then registered for the requested FusionAuth Application.

A successful response from the Reconcile API should look identical to a Login API response.

Results