Skip to main content

SAML Single Sign-On (SSO) Integration

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.

Overview​

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

Integration Steps​

1. Configure HostedScan as Service Provider​

Step 1.1: Access SAML Settings​

  1. Log in to your HostedScan account
  2. Navigate to Settings → SAML SSO
  3. Ensure you're on the Premium plan (upgrade required if not)

Step 1.2: Access Service Provider Metadata​

  1. In the SAML settings, you'll find a link to your Service Provider Metadata
  2. This metadata contains:
    • Entity ID (SP Identifier)
    • Assertion Consumer Service (ACS) URL
    • X.509 Certificate for signature verification
    • Supported Name ID formats

2. Configure Your Identity Provider​

Step 2.1: Add HostedScan as Service Provider​

  1. Log in to your IdP administration console
  2. Navigate to Applications or Service Providers
  3. Add a new SAML application/service provider
  4. Upload the HostedScan SP metadata XML

Step 2.2: Configure IdP Settings​

Configure the following in your IdP:

  • Name ID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • Sign Assertions: ✅ Required - Must be enabled
  • Sign Requests: ✅ Required - Must be enabled

3. Complete HostedScan Configuration​

Step 3.1: Obtain IdP Metadata​

  1. From your IdP, download the Identity Provider metadata XML
  2. This must contain:
    • IdP Entity ID
    • Single Sign-On Service URL
    • X.509 Certificate for signature verification
    • Supported bindings and protocols

Step 3.2: Configure IdP Settings in HostedScan​

  1. Return to HostedScan SAML settings
  2. Paste the IdP metadata XML into the configuration field
  3. HostedScan will automatically extract:
    • IdP Entity ID
    • SSO URL
    • X.509 Certificate

Security Requirements​

Critical Security Settings​

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
  • Entity ID: https://app.hostedscan.com
  • Metadata URL: https://app.hostedscan.com/auth/saml/{organization_id}/metadata