SSO Overview

Probo supports SAML 2.0 Single Sign-On (SSO) integration with popular identity providers. This allows your organization to centralize user authentication and streamline access to Probo.

Supported Identity Providers

Probo works with any SAML 2.0 compliant identity provider. We provide detailed setup guides for the most popular providers:

Google Workspace Configure SSO with Google Workspace (G Suite)

Okta Set up SAML authentication with Okta

Other supported providers:

• Azure Active Directory
• OneLogin
• Auth0
• ADFS (Active Directory Federation Services)
• PingIdentity
• JumpCloud
• Any SAML 2.0 compliant identity provider

Before You Start

1. Get Probo Service Provider Information

Before configuring your identity provider, you’ll need these Probo service provider details:

Field	Value
Entity ID	https://your-domain.com/auth/saml/metadata
ACS URL	https://your-domain.com/auth/saml/acs
Metadata URL	https://your-domain.com/auth/saml/metadata

Replace your-domain.com with your actual Probo domain.

2. Global SAML Settings

You can configure global SAML settings via environment variables:

# Optional: Session duration (default: 7 days)
SAML_SESSION_DURATION=604800

# Optional: Cleanup interval for expired sessions (default: disabled)
SAML_CLEANUP_INTERVAL_SECONDS=3600

# Optional: Custom SP certificate (default: auto-generated)
SAML_CERTIFICATE="-----BEGIN CERTIFICATE-----..."
SAML_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."

Configuration Process

The SSO setup process involves:

1. Configure your Identity Provider

   Set up Probo as a SAML application in your IdP (Okta, Google Workspace, etc.)

2. Configure Probo

   Add your IdP settings in Probo’s SAML configuration

3. Update RelayState

   Set IdP RelayState to SAML config ID for IdP-initiated login support

4. Domain Verification

   Verify ownership of your email domain using DNS TXT records

5. Testing

   Test both SP-initiated and IdP-initiated login flows

6. Enforcement

   Choose enforcement policy (optional/required) and enable SSO

IdP-Initiated vs SP-Initiated Flows

• SP-Initiated: User starts login from Probo (clicks “Sign in with SSO”)
• IdP-Initiated: User starts login from identity provider (clicks app in dashboard)

For IdP-initiated flows to work properly, the RelayState must be set to your SAML configuration ID from Probo.

Enforcement Policies

Probo supports three SAML enforcement policies:

Policy	SSO Available	Password Login	Description	Use Case
OFF	❌	✅	SSO is disabled, only password login	SSO not configured
OPTIONAL	✅	✅	Users can choose SSO or password	Gradual SSO rollout
REQUIRED	✅	❌	SSO mandatory for domain users	Full SSO enforcement

Security Requirements

Certificate Management

• Use strong certificates (2048-bit RSA minimum)
• Rotate certificates regularly
• Store private keys securely

Domain Verification

• Always verify domain ownership before enabling SSO
• Use DNS TXT records for verification
• Monitor domain verification status

Cookie Security

The auth.cookie.secure setting must be set to true for SAML authentication to work properly:

probod:
  auth:
    cookie:
      secure: true  # Required for SAML

This is required because SAML uses SameSite=None cookies for cross-site POST requests from identity providers, and modern browsers require the Secure flag when using SameSite=None.

Troubleshooting

Invalid SAML Response Error

• Cause: Clock skew between Identity Provider and Probo servers
• Solution: Ensure time synchronization (NTP) on both systems. Clock differences greater than 5 minutes can cause SAML failures.

Signature Verification Failed Error

• Cause: Incorrect certificate or certificate mismatch between IdP and Probo
• Solution: Verify the IdP certificate is correctly copied without line breaks or formatting issues

Unknown User Error

• Cause: User doesn’t exist in Probo and auto-signup is disabled
• Solution: Either enable auto-signup in SAML configuration or create user accounts manually before SSO setup

Domain Not Verified Error

• Cause: Email domain hasn’t been verified in Probo
• Solution: Complete the domain verification process before enabling SSO - this is always the first required step

RelayState/Start URL Issues

• Cause: Incorrect RelayState configuration for IdP-initiated login
• Solution: Ensure RelayState/Start URL is either empty or set to the exact SAML configuration ID from Probo

Next Steps

Choose your identity provider to get started:

Google Workspace Setup Step-by-step guide for G Suite integration

Okta Setup Complete Okta SAML configuration

Migration Guide

From Password to SSO

When transitioning from password-based authentication to SSO, follow this phased approach:

1. Phase 1: Set enforcement to OPTIONAL

   • Communicate SSO availability to users
   • Provide training and support documentation
   • Monitor adoption rates

2. Phase 2: User testing and feedback

   • Help users resolve SSO issues
   • Ensure all users can successfully authenticate
   • Address any attribute mapping issues

3. Phase 3: Full enforcement

   • Change enforcement to REQUIRED
   • Communicate the change to users
   • Monitor for any access issues

Rollback Plan

If issues arise, follow this rollback procedure:

1. Change enforcement back to OPTIONAL or OFF

   Immediately restore user access using password authentication

2. Communicate alternative login methods to users

   Notify users about the temporary change and available login options

3. Investigate and resolve issues

   Debug configuration problems, test thoroughly, and prepare fixes

4. Re-enable when ready

   Return to SSO once all issues are resolved and tested

This ensures minimal disruption to user access while implementing SSO.