Configuring a custom OAuth provider

Follow the steps described here to configure Astralis with a custom OAuth or OIDC provider. Use the custom provider option when your identity provider isn't natively supported by Astralis (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 Astralis, ensure the following:

• Your identity provider supports OAuth 2.0 or OIDC.
• Your provider exposes an authorization endpoint, a token endpoint, and a userinfo endpoint.
• You have a Client ID and Client Secret from your provider.
• You know the redirect URI format for Astralis: https://<yourfidesdomain.com>/login/<identifier>, where <identifier> is the unique value you'll set in Astralis.

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 Astralis (e.g., "custom-sso").
3. Note the following values from your provider — you'll need them when configuring Astralis:
   • 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 Astralis

1. Return to Astralis 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 Astralis 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. Astralis 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), Astralis checks that the identity provider has verified the user's email address before allowing login. See Require Verified Email below for details.
   • User Info Verify Email Field — the field name your provider uses to indicate whether the user's email is verified. Defaults to email_verified and verified_email. Only relevant when Require Verified Email is enabled. Only change this if your provider uses a different name (e.g., verified or is_email_verified).
   • Scopes — the scopes sent on the authorization request. Defaults to openid email. Only change this if your provider requires different scopes. See Scopes below for details.
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.

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, Astralis retrieves their profile from the User Info URL and reads the email address from the response. By default, Astralis 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, Astralis 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, Astralis checks the userinfo response for a field that indicates whether the user's email address has been verified. By default, Astralis 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

• The redirect URI must follow the format https://<yourfidesdomain.com>/login/<identifier>, where <identifier> matches the Identifier field you configured in Astralis exactly.
• If your provider requires specific scopes, make sure they are configured in the Scopes field. Without the correct scopes, the authorization request may fail or return incomplete user information.
• If you're unsure which JSON keys your provider uses for email and verification status, check your provider's documentation or inspect the userinfo endpoint response directly.