OpenID Connect Identity Provider

Overview

Adding a Login button for a third-party OpenID Connect provider to FusionAuth is simple, and this guide will walk you through the steps necessary to enable an OpenID Connect login provider.


Once you have completed this configuration you will be able to enable the OpenID Connect login button for one or more FusionAuth Applications. Below is an example login page with an OpenID Connect Identity Provider enabled for PiedPiper.

OpenID Connect Login

Create an OpenID Connect Identity Provider

To create an Identity Provider navigate to Settings Identity Providers and click Add provider and select OpenID Connect from the dialog.

This will take you to the Add OpenID Connect panel, and you’ll fill out the required fields. If you do not know the Client Id and Client secret for this provider you will need to contact the owner of the OpenID Connect provider.

If your OpenID Connect provider has implemented a well-known configuration endpoint, FusionAuth will be able to discover the necessary endpoints when you provide the URL to the provider in the Issuer field. For example, if you enter https://login.piedpiper.com in the Issuer field, FusionAuth will attempt to make a request to https://login.piedpiper.com/.well-known/openid-configuration to retrieve additional configuration. Alternatively you may provide fully qualified URLs for each of the required endpoints, to do this, toggle off the Discover endpoints switch and you will be shown three required fields.

To enable this identity provider for an application, find your application name in the Applications configuration section at the bottom of this panel. 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 following screenshot you will see that we have enabled this login provider for the Piped 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 Piped Piper using PiedPiper, 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 Piped 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.

That’s it, now the Login with PiedPiper button will show up on the login page.

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

Client Id Required

The client Id that will be used during the authentication workflow with this provider. This value will have been provided to you by the owner of the identity provider.

Client secret Required

The client secret that will be used during the authentication workflow with this provider. This value will have been provided to you by the owner of the identity provider.

Issuer Required

This is the public URL of the identity provider.

When the Discover endpoints is enabled, this field will be required.

Authorization endpoint Required

The public URL of the OpenID Connect authorization endpoint.

When the Discover endpoints is disabled, this field will be required.

Token endpoint Required

The public URL of the OpenID Connect token endpoint.

When the Discover endpoints is disabled, this field will be required.

Userinfo endpoint Required

The public URL of the OpenID Connect userinfo endpoint.

When the Discover endpoints is disabled, this field will be required.

Button text Required

The text to be displayed in the button on the login form. This value is defaulted to Login with OpenID Connect but it may be modified to your preference.

Button image Optional

The image to be displayed in the button on the login form. When this value is omitted a default OpenID Connect icon will be displayed on the login button.

Scope Optional

This optional field defines the scope you’re requesting from the user during login. This is an optional field, but it may be required depending upon the OpenID Connect provider you’re using. At a minimum, the provider must return an email address from the Userinfo endpoint.

Managed domains Optional

You may optionally scope this identity provider to one or more managed domains. For example, if you were to use an OpenID Connect identity provider for your employees, you may add your company domain piedpiper.com to this field.

Adding one or more managed domains for this configuration will cause this provider not to be displayed as a button on your login page. Instead of a button the login form will first ask the user for their email address. If the user’s email address matches one of the configured domains the user will then be redirected to this login provider to complete authentication. If the user’s email address does not match one of the configured domains, the user will be prompted for a password and they will be authenticated using FusionAuth.

These configured domains will be used by the Lookup API.