Skip to main content

Overview

HostedScan supports SAML 2.0 Single Sign-On (SSO) integration, allowing organizations to authenticate users through their existing Identity Provider (IdP). This guide covers how to configure HostedScan as a Service Provider (SP) with your SAML IdP.

SAML SSO enables your organization to:

  • Centralize user authentication through your existing IdP
  • Enforce security policies defined in your IdP
  • Simplify user management by leveraging existing user directories
  • Maintain consistent access controls across all applications

SAML Authentication Flow​

1. User Access
   User → HostedScan

2. SAML Redirect
   HostedScan → IdP (with SAML AuthnRequest)

3. IdP Authentication
   User → IdP (login with credentials)

4. SAML Response
   IdP → HostedScan (signed SAML assertion)

5. User Session
   HostedScan → User (authenticated session)

Key Points:

  • All SAML assertions and requests must be digitally signed
  • User email address is used as the unique identifier
  • HostedScan automatically creates/updates user accounts

Prerequisites​

  • Premium Plan: SAML SSO is available on the Premium plan
  • SAML 2.0 IdP: Your organization must have a SAML 2.0 compatible Identity Provider
  • Administrative Access: You need admin access to both HostedScan and your IdP

Security Requirements​

Your IdP MUST be configured with the following security settings:

  1. Sign Assertions: ✅ Required

    • All SAML assertions must be digitally signed
    • Ensures assertion integrity and authenticity

  2. Sign Responses: ✅ Required

    • All SAML responses must be digitally signed
    • Prevents response tampering and replay attacks

Troubleshooting​

Common Issues​

Authentication Fails​

Symptoms: Users cannot log in via SAML Solutions:

  1. Verify IdP metadata is correctly configured
  2. Check that both assertions and requests are being signed
  3. Ensure X.509 certificate is valid and properly configured
  4. Verify attribute mapping is correct

Certificate Errors​

Symptoms: SAML authentication fails with certificate errors Solutions:

  1. Verify IdP certificate is not expired
  2. Check certificate format (should be X.509)
  3. Ensure certificate is properly imported in both systems
  4. Validate certificate chain if using intermediate certificates

Debug Tips​

To troubleshoot SAML issues:

  1. Enable Debug Logging: Check your IdP logs for detailed SAML transaction information
  2. Browser Developer Tools: Use network tab to inspect SAML requests/responses
  3. HostedScan Logs: Contact support for server-side SAML transaction logs

Technical Specifications​

Supported SAML Features​

  • SAML Version: 2.0
  • Bindings: HTTP-POST, HTTP-Redirect
  • Name ID Formats:
    • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (Primary)
    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  • Signature Algorithms: SHA-1

Endpoints​

  • ACS URL: https://app.hostedscan.com/auth/saml/{organization_id}/callback
  • SP Entity ID: https://app.hostedscan.com
  • Metadata URL: https://app.hostedscan.com/auth/saml/{organization_id}/metadata