Skip to content
Veraproof Veraproof Docs

SAML Integration

SAML Integration

Challenge supports SAML 2.0 for identity provider (IdP) authentication during verification challenges.

Overview

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

Setup

1. Configure SAML in Your IdP

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

Service Provider (SP) Details:

  • Entity ID: https://challenge.veraproof.io/saml/metadata
  • ACS URL (Assertion Consumer Service): https://challenge.veraproof.io/saml/acs
  • Name ID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress or urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress
  • Response Binding: HTTP POST (required)
  • Request Binding: HTTP Redirect (optional, for SP-initiated)

Attribute Mapping:

  • Map the user’s email address to the Name ID or a SAML attribute
  • Optionally map additional attributes (name, etc.)
  1. Download the IdP metadata XML file or note the metadata URL

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.

  1. In your IdP’s SAML application settings, configure authentication policies to force re-authentication or require step-up authentication
  2. Set the application to require full authentication, not just SSO session validation
  3. 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.

2. Configure SAML in Challenge

  1. Log in to the Challenge admin console at challenge.veraproof.io
  2. Navigate to IdP Settings → SAML Configuration
  3. Enter the following:
    • Provider Name: A friendly name (e.g., “Okta SSO”)
    • SAML Metadata URL: The URL to your IdP’s metadata XML file, OR
    • SAML Metadata XML: Paste the metadata XML directly
  4. Click Save Configuration
  5. Test the configuration using the Test Configuration button
  6. Enable SAML authentication by checking Enable SAML authentication

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 for authentication
  4. After successful authentication, the IdP sends a SAML assertion to Challenge
  5. Challenge validates the assertion and marks the challenge as verified
  6. The user sees a success page, and the requester receives a notification

Supported Features

  • SP-Initiated SSO: Users start from Challenge and are redirected to IdP
  • HTTP POST Binding: For SAML responses (required)
  • HTTP Redirect Binding: For SAML requests (optional)
  • Email-based Name ID: Uses email address for user identification
  • Metadata URL Support: Can fetch IdP metadata from a URL (with URL validation for security)

Security Considerations

  • All SAML assertions are validated for signature and expiration
  • Challenge validates the IdP certificate from metadata
  • Assertions 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 SAML metadata URL is accessible and returns valid XML
  • Check that the ACS URL matches exactly: https://challenge.veraproof.io/saml/acs
  • Ensure the Name ID format is email-based
  • Verify the IdP certificate is valid and not expired

Metadata URL Not Loading

  • Check that the URL is publicly accessible (not behind a firewall)
  • Verify the URL returns valid SAML metadata XML
  • Ensure the URL uses HTTPS (required for security)

User Not Found

  • Verify the email address in the SAML assertion matches the challenge target user email
  • Check attribute mapping in your IdP configuration

Support

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