Fides Documentation – Ethyca

Configuring a custom OAuth provider

Follow the steps described here to configure Fides with a custom OAuth or OIDC provider. Use the custom provider option when your identity provider isn't natively supported by Fides (e.g. Auth0, Keycloak, PingIdentity, or an internal identity provider). This will need to be completed in collaboration with the team that manages your identity provider.

Prerequisites

Before configuring Fides, ensure the following:

Step by step instructions for configuring a custom provider

1. Configure your identity provider

  1. Register a new OAuth or OIDC application in your identity provider.
  2. Set the redirect URI to https://<yourfidesdomain.com>/login/<identifier>, where <identifier> is a unique, case-sensitive value you'll also enter in Fides (e.g., "custom-sso").
  3. Note the following values from your provider — you'll need them when configuring Fides:
    • Client ID
    • Client Secret
    • Authorization URL (the OAuth authorization endpoint)
    • Token URL (the OAuth token endpoint)
    • User Info URL (the userinfo endpoint)
  4. Confirm which scopes your provider requires. Common scopes include openid, email, and profile.
  5. Identify the JSON keys your provider uses in its userinfo response for the user's email address and email verification status. Many providers use email and email_verified, but yours may differ.

2. Configure Fides

  1. Return to Fides and navigate to the "Settings > Organization" screen.
  2. Click "Add SSO Provider" and select "Custom" from the Provider list.
  3. Fill in the required fields using the information from your identity provider:
    • Identifier — a unique, case-sensitive value that becomes part of the redirect URI (e.g., "custom-sso"). Double check this matches what you configured in your identity provider.
    • Name — a display name shown on the Fides login screen to your users.
    • Client ID — the client ID from your identity provider.
    • Client Secret — the client secret from your identity provider.
    • Authorization URL — your provider's OAuth authorization endpoint.
    • Token URL — your provider's OAuth token endpoint.
    • User Info URL — your provider's userinfo endpoint. Fides calls this endpoint to retrieve the authenticated user's email address.
  4. Configure the optional fields below as needed. These have sensible defaults and most providers won't require changes:
    • User Info Email Field — the field name your provider uses for the user's email address in its userinfo response. Defaults to email. Only change this if your provider uses a different name (e.g., mail, preferred_email, or upn).
    • Require Verified Email — when enabled (the default), Fides checks that the identity provider has verified the user's email address before allowing login.
    • User Info Verify Email Field — the field name your provider uses to indicate whether the user's email is verified. Defaults to email_verified. Only relevant when Require Verified Email is enabled.
    • Scopes — the scopes sent on the authorization request. Defaults to openid email. Only change this if your provider requires different scopes.
  5. Click "Save".

You now have a custom OAuth provider configured! Add users and assign them roles so that you can test the integration. When adding a user who will sign in via your custom provider, set both their username and email to the email address provided by your identity provider.

To test the integration without losing access to your current session, open a private or incognito browser window and log in as one of the users you created. This way you can troubleshoot any issues without locking yourself out of Fides.

Understanding the custom fields

Scopes

Built-in providers (Okta, Google, Microsoft Entra ID) use hard-coded scopes on the authorization request. The custom provider lets you specify exactly which scopes are sent. Set this value to match what your identity provider requires — common values include openid, email, and profile.

User Info Email Field

When a user logs in, Fides retrieves their profile from the User Info URL and reads the email address from the response. By default, Fides looks for a field called email. If your identity provider uses a different key in its userinfo response, set User Info Email Field to match. For example, some providers return the email under mail, preferred_email, or upn.

Require Verified Email

By default, Fides requires that the identity provider has verified the user's email address. This ensures that users can only authenticate with email addresses they actually own.

Disable Require Verified Email when your provider doesn't return a verification flag in its userinfo response, or when email verification is handled outside of your identity provider.

User Info Verify Email Field

When Require Verified Email is enabled, Fides checks the userinfo response for a field that indicates whether the user's email address has been verified. By default, Fides looks for email_verified. If your provider uses a different key (e.g., verified or is_email_verified), set User Info Verify Email Field to match.

Important notes