OpenID Connect Identity Provider

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.

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 authentication method Optional Available since 1.15.3

The client authentication method to use with the OpenID Connect identity provider.

See the OIDC spec concerning Client Authentication for more information.

Client secret Optional

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. This value is required when Client authentication method is not HTTP basic authentication (client_secret_basic) or Request body (client_secret_post).

Redirect URL Read-only Available since 1.6.0

This is the redirect URI you will need to provide to your identity provider.

Discover endpoints

When enabled FusionAuth will attempt to discover the endpoint configuration using the Issuer URL.

For example, if https://login.piedpiper.com is specified as the issuer, the well-known OpenID Connect URL https://piedpiper.com/.well-known/openid-configuration will be queried to discover the well-known endpoints.

When disabled, you may manually enter the required endpoints. This option is helpful if your OpenID Connect provider does not implement the well-known discovery endpoint.

Issuer Required

This is the public URL of the identity provider.

When Discover endpoints is enabled, this field is required.

Authorization endpoint Required

The public URL of the OpenID Connect authorization endpoint.

When Discover endpoints is disabled, this field is required.

Token endpoint Required

The public URL of the OpenID Connect token endpoint.

When Discover endpoints is disabled, this field is required.

Userinfo endpoint Required

The public URL of the OpenID Connect userinfo endpoint.

When 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.

Linking strategy Optional defaults to Link on email. Create the user if they do not exist Available since 1.28.0

The linking strategy for the OpenID Connect provider. See Linking Strategies for more.

Reconcile lambda Optional

A lambda maps custom claims returned from the OpenID Connect provider to the FusionAuth User or Registration.

To create or configure a lambda, navigate to Settings → Lambdas. See the lambda documentation for more.

Debug enabled Optional defaults to false

Enable debug to create event log entries during the user login process. This will assist you in debugging integration issues.

Managed Domains

Options

User info as JWT

The OIDC specification allows a client to request the userinfo response in various formats:

• JSON

• Signed JWT

• Encrypted/nested JWT

FusionAuth supports the JSON format only. If you are trying to set up an OIDC integration and see an error message like:

Request to the [https://example.com/userinfo] endpoint failed. Status code [200].
Exception encountered.com.inversoft.rest.JSONException : Message: Failed to parse the HTTP response as JSON. Actual HTTP response body:
eyJoa...

This means that the OIDC endpoint is sending back the userinfo data as a JWT. Please review your client registration with the OIDC endpoint administrators to ensure userinfo data is sent back as JSON.

Unable to login

A common pattern is to set up OIDC as the login method for the FusionAuth application. This lets you keep all your users in the OIDC system, and have FusionAuth delegate auth decisions to it. However, if your Identity Provider isn’t configured correctly, you can end up in a dead end, unable to log in. This might happen if the following occurs:

• You set up OIDC as the authentication method for your FusionAuth admin application.

• You set the Managed domains to your domain. For example, example.com.

• All added users have the same example.com domain.

• You accidentally misconfigure OIDC and break authentication.

• Then you log out of the FusionAuth administrative user interface.

You won’t be able to log in to the FusionAuth admin application to correct the misconfiguration. You’ve locked down the FusionAuth admin application so that only users with example.com email domains can access it, but because of the misconfiguration, there is no account with a valid OIDC login.

This is a problem, but not an insurmountable one. Your options depend on when you discover the issue. If you are beginning your OIDC configuration, you can avoid this scenario. Follow these steps:

• Don’t set any value of Managed domains before you have tested the OIDC configuration.

• Test authentication in a different or incognito browser window, ensuring that an admin user account is always accessible to modify configuration.

• Add an admin user account with a domain not in the Managed domains setting. Ensure this user is registered with the FusionAuth admin application and has the admin role.

• Set up an API key. Navigate to Settings → API Keys to do so and make sure it has privileges to create users and registrations. This will open up options in the future to reset settings without using the administrative user interface.

If you are currently locked out of your FusionAuth application, you have fewer options:

• If you have a known username and password that are not delegated to OIDC (perhaps the initial account created when you set up FusionAuth) proceed to the FusionAuth admin login page. Append &showPasswordField=true to the end of the login URL. This will force the UI to show the password field.

• If you have an API key with appropriate privileges, you can modify the configuration without using the administrative user interface. Add an admin user with a different email domain and sign into the admin interface to correct your OIDC configuration. Here’s how you might do so (3c219e58-ed0e-4b18-ad48-f4f92793ae32 is the FusionAuth application Id):

curl -XPOST -H "Authorization: $API_KEY" -H "Content-Type: application/json" \
-d '{
	"user": {
		"email": "user@differentdomain.com",
		"password": "password"
	},
	"registration": {
		"applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
		"roles": ["admin"]
	}
}' \
https://login.piedpiper.com/api/user/registration

If you have neither an API key nor a known user, you can restore from a database backup, modify the database directly if you have access, or re-install FusionAuth.