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 only 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 Responses: ✅ Required

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

  2. Sign Assertions: ✅ Suggested

    • Ensures assertion integrity and authenticity

SAML Settings Toggles​

HostedScan provides a few top-level SAML settings that control how users authenticate and how new users are created.

Enable SAML SSO​

When enabled, HostedScan allows users to authenticate through your configured Identity Provider (IdP).

  • What it does: Turns on SAML login for your organization.
  • Impact: Users can sign in with SAML; local login can still be available unless enforcement is enabled.

Enforce SAML SSO​

When enforced, users in your organization must authenticate via SAML and cannot use passwordless/local login flows.

  • What it does: Requires SAML as the only authentication path for organization members.
  • When to use: After a successful rollout period where all active users can sign in via IdP.
  • Impact: Stronger identity control and centralized access management through your IdP.
  • Recommendation: Enable this only after validating break-glass/admin access and verifying domain ownership.

Automatic Provisioning​

When enabled, HostedScan creates user accounts automatically on first successful SAML login.

  • What it does: Creates a new HostedScan user record from the SAML assertion if one does not already exist, and adds the user to the Organization owning the SAML account.
  • When to use: Organizations that want onboarding fully managed by IdP group/user assignments.
  • Impact: Reduces manual user administration in HostedScan; access lifecycle is managed from your IdP.
  • Recommendation: Pair with domain verification and IdP-side assignment rules to avoid unintended account creation.

Domain Verification​

Domain verification confirms domain ownership. After it is complete, users signing in with a verified-domain email must use your configured SAML flow.

Why it matters​

  • Helps ensure SAML enforcement affects the intended set of users.
  • Adds a trust boundary for automatic provisioning.

How it works​

  1. Add a domain in Settings → Domain Verification (for example, example.com).
  2. HostedScan generates a TXT verification token.
  3. Add that TXT record in your DNS provider.
  4. Click Verify in HostedScan after DNS propagation.
  5. Once verified, the domain is treated as organization-owned for SAML workflows.

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