Skip to content
Veraproof Veraproof Docs

OIDC Integration

OIDC Integration

Challenge supports OpenID Connect (OIDC) for identity provider (IdP) authentication during verification challenges.

Overview

OIDC integration allows users to verify their identity using your existing OIDC-compatible identity provider (e.g., Okta, Azure AD, Google Workspace). When a user clicks a challenge verification link, they authenticate through your IdP before the challenge is marked as verified.

Setup

1. Create an OIDC Application in Your IdP

  1. Log in to your identity provider’s admin console
  2. Create a new OIDC application or client
  3. Configure the following settings:

Application Details:

  • Application Type: Web Application
  • Name: Challenge by Veraproof (or your preferred name)
  • Grant Types: Authorization Code
  • Redirect URI: https://challenge.veraproof.io/auth/callback/oidc

Scopes:

  • openid (required)
  • email (required)
  • profile (optional, for additional user information)
  1. Note the following values:
    • Client ID
    • Client Secret
    • Issuer URL (e.g., https://your-idp.okta.com/oauth2/default)

2. Configure OIDC in Challenge

  1. Log in to the Challenge admin console at challenge.veraproof.io
  2. Navigate to IdP Settings → OIDC Configuration
  3. Enter the following:
    • Provider Name: A friendly name (e.g., “Okta SSO”)
    • Issuer URL: Your IdP’s issuer URL (e.g., https://your-idp.okta.com/oauth2/default)
    • Client ID: The client ID from your OIDC application
    • Client Secret: The client secret from your OIDC application
    • Scopes: openid email profile (default, can be customized)
  4. Click Save Configuration
  5. Test the configuration using the Test Configuration button
  6. Enable OIDC authentication by checking Enable OIDC authentication

3. Assign Users (IdP-Specific)

Depending on your IdP, you may need to assign users or groups to the OIDC application:

  • Okta: Assign users or groups to the application
  • Azure AD: Configure user assignment in Enterprise Applications
  • Google Workspace: Users are automatically included based on domain

4. Configure Authentication Policies (Critical)

To ensure robust step-up authentication challenges, you must configure your IdP to force full authentication for the Challenge application. This prevents existing IdP sessions from automatically performing an SSO dance, which would bypass the authentication challenge.

Configure Force Authentication:

  1. In your IdP’s admin console, navigate to the Challenge OIDC application settings
  2. Configure authentication policies to force re-authentication or require step-up authentication
  3. Set the application to require full authentication, not just SSO session validation
  4. This ensures users must actively authenticate each time they access a challenge link

Recommended MFA Configuration:

For maximum security, configure phishing-resistant MFA for the Challenge application:

  • FIDO2/WebAuthn: Hardware security keys or platform authenticators (passkeys)
  • Passkeys: Platform-native biometric authentication (Face ID, Touch ID, Windows Hello)
  • Avoid: SMS-based MFA or email-based MFA (these are vulnerable to phishing)

Important: Without forcing full authentication, users with existing IdP sessions may automatically authenticate without providing credentials, which defeats the purpose of identity verification challenges. Always configure your IdP to require fresh authentication for Challenge.

How It Works

  1. A challenge is created (via Slack, webhook API, etc.)
  2. The target user receives a verification link
  3. When the user clicks the link, they are redirected to your IdP’s authorization endpoint
  4. The user authenticates with your IdP
  5. After successful authentication, the IdP redirects back to Challenge with an authorization code
  6. Challenge cryptographically verfies the SSO token and marks as verified if the user matches
  7. The user sees a success page, and the requester receives a notification

Supported Features

  • Authorization Code Flow: Standard OIDC authorization code flow
  • PKCE Support: Proof Key for Code Exchange for enhanced security
  • Email-based Identification: Uses email address from ID token for user matching
  • Automatic Discovery: Uses OIDC discovery endpoint to configure endpoints automatically

Security Considerations

  • All ID tokens are validated for signature, expiration, and issuer
  • Challenge validates the IdP’s signing keys using JWKS (JSON Web Key Set)
  • Authorization codes are single-use and expire quickly
  • Tokens must be received within the challenge expiration window (15 minutes)
  • Force Authentication Required: Your IdP must be configured to force full authentication (not just SSO session validation) to ensure robust step-up authentication challenges
  • MFA Recommended: Phishing-resistant MFA factors (FIDO2/WebAuthn, passkeys) are highly recommended for the Challenge application to prevent account takeover attacks

Troubleshooting

Authentication Fails

  • Verify the Issuer URL is correct and accessible
  • Check that the Client ID and Client Secret match your IdP application
  • Ensure the redirect URI matches exactly: https://challenge.veraproof.io/auth/callback/oidc
  • Verify the scopes include openid and email

User Not Found

  • Verify the email address in the ID token matches the challenge target user email
  • Check that the user is assigned to the OIDC application in your IdP
  • Ensure the email claim is included in the ID token

Configuration Test Fails

  • Check that the Issuer URL is accessible and returns valid OIDC discovery metadata
  • Verify the Client ID and Client Secret are correct
  • Ensure your IdP allows the redirect URI

Support

For issues or questions, contact support@veraproof.io.