Configuring OIDC For SSO

DataGrail supports generic OpenID Connect (OIDC) authentication for SSO providers that are not covered by our pre-configured integrations. This allows you to use any OIDC-compliant identity provider such as Frontegg, Auth0, Keycloak, or custom identity solutions.

Overview

OIDC (OpenID Connect) is an identity layer built on top of OAuth 2.0. DataGrail's generic OIDC integration supports:

• Standard OIDC Discovery - Automatic configuration via OpenID Discovery endpoints
• OAuth 2.1 with PKCE - Enhanced security using Proof Key for Code Exchange
• ID Token Validation - Full JWT signature and claims verification
• Flexible Provider Support - Works with any OIDC-compliant provider

Prerequisites

Before configuring OIDC authentication, you'll need:

1. Administrative access to your OIDC provider
2. OIDC application credentials from your identity provider
3. Provider configuration details (endpoints, issuer URL, JWKS URI)

Your OIDC provider must meet these security requirements:

• ✅ Support RS256 (RSA Signature with SHA-256) for ID token signing
• ✅ Return email_verified: true in ID token claims or userinfo response
• ✅ Provide a valid JWKS endpoint for public key retrieval
• ✅ Support PKCE (Proof Key for Code Exchange) - recommended for OAuth 2.1 compliance

Configuration Requirements

To configure DataGrail with your OIDC provider, you'll need to collect the following information from your identity provider:

Required Information

Configuration Item	Description	Example
Client ID	OAuth 2.0 client identifier	datagrail-prod-client
Client Secret	OAuth 2.0 client secret (will be encrypted)	secret_abc123...
Issuer	OIDC issuer identifier URL	https://auth.example.com
Authorization Endpoint	OAuth 2.0 authorization URL	https://auth.example.com/oauth/authorize
Token Endpoint	OAuth 2.0 token exchange URL	https://auth.example.com/oauth/token
Userinfo Endpoint	OIDC userinfo endpoint URL	https://auth.example.com/oauth/userinfo
JWKS URI	JSON Web Key Set URL for token validation	https://auth.example.com/.well-known/jwks.json

Optional Configuration

Configuration Item	Description	Default
Scopes	OAuth scopes to request	openid email profile
Redirect URI	Custom OAuth callback URL	https://login.datagrail.io/sso_callback

Finding Your Provider Configuration

Most OIDC providers expose their configuration through an OpenID Discovery endpoint. You can typically find all required endpoints at:

https://<your-provider-domain>/.well-known/openid-configuration

This JSON document will contain all the endpoint URLs you need (authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, and issuer).

Configuring Your OIDC Provider

The exact steps vary by provider, but generally you need to:

1. Create an OAuth 2.0 / OIDC Application in your identity provider's admin console

2. Configure the application settings:

   • Application Type: Web Application or Single Page Application
   • Grant Types: Authorization Code with PKCE
   • Scopes: At minimum openid, email, and profile

3. Set the Redirect URI to your DataGrail callback URL:

   • https://login.datagrail.io/sso_callback
   • If you have a custom domain, use your custom domain with /sso_callback path

4. Collect the required configuration details:

   • Copy your Client ID
   • Copy your Client Secret (keep this secure!)
   • Find your provider's OpenID Discovery endpoint (typically /.well-known/openid-configuration)
   • Extract the required endpoint URLs from the discovery document

5. Send the configuration to DataGrail:

   • Email support@datagrail.io with the subject "OIDC SSO Configuration"
   • Include all required configuration items listed above
   • Do not send the Client Secret via email - DataGrail support will provide a secure method to transmit this credential

Provider-Specific Examples

The following examples show how to configure popular OIDC providers with DataGrail. Select your provider below for detailed configuration steps.

Auth0

Auth0 Configuration Steps

1. Navigate to Applications → Applications in Auth0 Dashboard
2. Click Create Application → Choose Regular Web Application
3. In the application settings:
   • Copy the Client ID and Client Secret
   • Set Allowed Callback URLs to https://login.datagrail.io/sso_callback
   • Set Allowed Web Origins to https://login.datagrail.io
4. Find your Auth0 domain in the application settings (e.g., your-tenant.auth0.com)
5. Your configuration values:
   • Issuer: https://your-tenant.auth0.com/
   • Authorization Endpoint: https://your-tenant.auth0.com/authorize
   • Token Endpoint: https://your-tenant.auth0.com/oauth/token
   • Userinfo Endpoint: https://your-tenant.auth0.com/userinfo
   • JWKS URI: https://your-tenant.auth0.com/.well-known/jwks.json

Frontegg

Frontegg Configuration Steps

1. Navigate to Environments → [Your Environment] → Authentication in Frontegg Portal
2. Under OAuth Settings:
   • Copy the Client ID and Client Secret
   • Add https://login.datagrail.io/sso_callback to Redirect URIs
3. Find your Frontegg domain (e.g., your-app.frontegg.com)
4. Your configuration values:
   • Issuer: https://your-app.frontegg.com
   • Authorization Endpoint: https://your-app.frontegg.com/oauth/authorize
   • Token Endpoint: https://your-app.frontegg.com/oauth/token
   • Userinfo Endpoint: https://your-app.frontegg.com/oauth/userinfo
   • JWKS URI: https://your-app.frontegg.com/.well-known/jwks.json

Keycloak

Keycloak Configuration Steps

1. Navigate to Clients in your Keycloak realm
2. Click Create client:
   • Client type: OpenID Connect
   • Client ID: datagrail (or your preferred identifier)
3. Configure client settings:
   • Client authentication: On
   • Valid redirect URIs: https://login.datagrail.io/sso_callback
   • Access Type: confidential
4. In the Credentials tab, copy the Client Secret
5. Your configuration values (replace your-keycloak-domain and your-realm):
   • Issuer: https://your-keycloak-domain/realms/your-realm
   • Authorization Endpoint: https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/auth
   • Token Endpoint: https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/token
   • Userinfo Endpoint: https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/userinfo
   • JWKS URI: https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/certs

Testing Your OIDC Integration

After DataGrail support confirms the configuration is complete:

1. Navigate to your DataGrail login page (e.g., https://your-subdomain.datagrail.io)
2. You should be automatically redirected to your OIDC provider's login page
3. Log in with a test user account that has a verified email address
4. After successful authentication, you should be redirected back to DataGrail
5. If this is your first login, you may need to be invited as a user first - see Inviting New Users

Inviting New Users

With OIDC authentication configured, you can invite users to your DataGrail account. Please visit Inviting New Users for instructions on adding users and managing roles.

Troubleshooting

If you encounter issues with your OIDC integration, review the common problems below. If you need additional assistance, contact support@datagrail.io.

Common Issues

"Email not verified" error

• Ensure users have verified their email addresses in your identity provider
• Check that your provider returns email_verified: true in the ID token

"Invalid issuer" or "Invalid audience" error

• Verify the issuer URL exactly matches your provider's configuration
• Confirm the client ID matches between your provider and DataGrail configuration

Redirect URI mismatch

• Ensure the redirect URI in your provider matches exactly: https://login.datagrail.io/sso_callback
• Check for trailing slashes or protocol mismatches (http vs https)

User not found after successful authentication

• The user must first be invited to DataGrail - see Inviting New Users
• Verify the email address in the OIDC response matches the invited user's email

Security Considerations

DataGrail's OIDC integration implements the following security measures:

• Encrypted Credentials - Client secrets are encrypted at rest using AWS Secrets Manager
• PKCE (Proof Key for Code Exchange) - Protects against authorization code interception attacks
• ID Token Validation - Full JWT signature verification using your provider's JWKS
• Email Verification - Requires verified email addresses to prevent account takeover
• Issuer & Audience Validation - Prevents token substitution attacks
• Token Expiration - Enforces short-lived access tokens

Comparison with SAML

If you're deciding between OIDC and SAML:

Feature	OIDC	SAML
Setup Complexity	Simpler	More complex
Token Format	JSON Web Tokens (JWT)	XML
Mobile Support	Excellent	Limited
Modern Standard	Yes (OAuth 2.0 based)	Older standard
DataGrail Support	Generic provider support	Provider-specific configurations

Recommendation: Use OIDC if your provider supports it, especially for modern identity platforms. Use SAML if you have existing SAML infrastructure or if your provider is listed in our SAML provider documentation.