Setting up SAML authentication in FastComments requires both configuration in your admin dashboard and setup in your identity provider.

Prerequisites

Before configuring SAML, ensure you have:

• A FastComments Flex or Pro plan (SAML is not available on the Creators plan)
• Administrative access to your FastComments account
• Administrative access to your identity provider
• Your IdP's SAML metadata or certificate information

Accessing SAML Configuration

1. Log into your FastComments admin dashboard
2. Navigate to API/SSO Settings in the left sidebar
3. Click the SAML Config button

If you don't see the SAML Config button, verify that:

• Your account has the required package (Flex or Pro)
• You have administrative permissions
• Your user has API Admin or Admin Admin roles

Basic SAML Configuration

Enable SAML Authentication

1. Check the Enable SAML Authentication checkbox
2. This activates SAML for your tenant and makes the configuration fields available

Required Fields

IdP Single Sign-On URL (Required)

• The URL where users will be redirected for authentication
• Usually provided by your identity provider
• Example: https://your-company.okta.com/app/fastcomments/sso/saml

IdP X.509 Certificate (Required)

• The public certificate from your identity provider
• Used to verify the authenticity of SAML responses
• Must include the full certificate with BEGIN/END markers
• Example format: ```
• ----BEGIN CERTIFICATE----- MIICXjCCAcegAwIBAgIBADANBgkqhkiG9w0BAQsFADA...
• ----END CERTIFICATE-----

Optional Fields

IdP Entity ID / Issuer

• Identifies your identity provider
• If left blank, defaults to your FastComments URL
• Should match the issuer configured in your IdP

Advanced Configuration

Security Settings

Signature Algorithm

• Defaults to SHA-256 (recommended)
• Options: SHA-1, SHA-256, SHA-512
• Should match your IdP's configuration

Digest Algorithm

• Defaults to SHA-256 (recommended)
• Used for digest computation in SAML responses
• Should match your IdP's configuration

Name ID Format

• Defaults to Email Address format
• Determines how user identifiers are formatted
• Common options: Email Address, Persistent, Transient

Encryption (Optional)

Private Key for Decryption

• Only needed if your IdP encrypts SAML assertions
• Paste your private key used for decryption
• Most deployments don't require assertion encryption

Saving Configuration

1. Review all settings for accuracy
2. Click Save SAML Configuration
3. The system will validate your configuration
4. If successful, you'll see a confirmation message

Next Steps

After saving your FastComments SAML configuration:

1. Configure your identity provider using the Service Provider information
2. Test the authentication flow
3. Set up user roles and permissions as needed

The Service Provider information needed for your IdP configuration will be displayed once SAML is enabled.

After configuring SAML in FastComments, you need to set up FastComments as a Service Provider in your identity provider.

General IdP Configuration

Most identity providers require the following information to add FastComments as a SAML application:

Required Service Provider Information

These values are automatically generated and displayed in your FastComments SAML configuration page:

SP Entity ID / Audience

• Format: https://fastcomments.com/saml/{your-tenant-id}
• This uniquely identifies your FastComments instance

Assertion Consumer Service (ACS) URL

• Format: https://fastcomments.com/saml/callback/{your-tenant-id}
• Where your IdP sends SAML responses after authentication

SP Metadata URL (if supported by your IdP)

• Format: https://fastcomments.com/saml/metadata/{your-tenant-id}
• Provides complete SAML configuration in XML format

SAML Login URL

• Format: https://fastcomments.com/saml/login/{your-tenant-id}
• Direct link to initiate SAML authentication

Required SAML Attributes

Configure your identity provider to send these attributes with SAML responses:

Essential Attributes

Email Address (Required)

• Attribute Name: email, emailAddress, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• Purpose: Unique user identification and notifications
• Format: Valid email address

Optional Attributes

First Name

• Attribute Names: firstName, givenName, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
• Purpose: User display name

Last Name

• Attribute Names: lastName, surname, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
• Purpose: User display name

Roles (Important for access control)

• Attribute Names: roles, groups, memberOf, or custom attribute names
• Purpose: FastComments role assignment and permissions
• Format: Array of role strings or comma-separated values

Common Identity Provider Configurations

Microsoft Azure AD

1. Add Enterprise Application

   • Search for "FastComments" or create a custom SAML application
   • Use the SP information provided by FastComments

2. Configure Attributes

   • Email: user.mail or user.userprincipalname
   • First Name: user.givenname
   • Last Name: user.surname
   • Roles: user.assignedroles or directory groups

Okta

1. Create SAML Application

   • Use "Create New App" and select SAML 2.0
   • Configure with FastComments SP information

2. Attribute Statements

   • Email: user.email
   • FirstName: user.firstName
   • LastName: user.lastName
   • Roles: user.groups or custom attributes

Google Workspace

1. Add SAML Application

   • Go to Apps > Web and mobile apps > Add App > Add custom SAML app
   • Configure with FastComments SP information

2. Attribute Mapping

   • Email: Primary email
   • First Name: First name
   • Last Name: Last name
   • Roles: Groups or custom attributes

Active Directory Federation Services (ADFS)

1. Add Relying Party Trust

   • Use the FastComments metadata URL or manual configuration
   • Configure SP information as provided

2. Claim Rules

   • Email: Email Address claim
   • Name: Name ID claim
   • Roles: Group membership or custom claims

Attribute Name Flexibility

FastComments accepts role information from multiple attribute names to accommodate different IdP configurations:

• roles
• groups
• memberOf
• role
• group
• http://schemas.microsoft.com/ws/2008/06/identity/claims/role
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role

This flexibility ensures compatibility with various identity providers without requiring specific attribute naming conventions.

Testing Your Configuration

After configuring your identity provider:

1. Save the IdP configuration
2. Test with a dedicated test user account
3. Verify that attributes are being sent correctly
4. Check that roles are properly mapped
5. Ensure the authentication flow completes successfully

Most identity providers offer SAML testing tools to validate the configuration before deploying to production users.

When SAML is enabled in FastComments, the system automatically generates Service Provider (SP) information that you need to configure in your identity provider.

Accessing Service Provider Information

The SP information is displayed in your SAML configuration page after enabling SAML authentication. This information includes all the details your identity provider needs to establish the SAML trust relationship.

Service Provider Endpoints

SP Entity ID / Audience

Purpose: Uniquely identifies your FastComments instance as a service provider Format: https://fastcomments.com/saml/{your-tenant-id} Usage: Configure this as the Entity ID or Audience in your IdP

This identifier ensures that SAML responses are intended for your specific FastComments tenant and prevents SAML responses from being accepted by other instances.

Assertion Consumer Service (ACS) URL

Purpose: The endpoint where your IdP sends SAML responses after user authentication Format: https://fastcomments.com/saml/callback/{your-tenant-id} Usage: Configure this as the ACS URL or Reply URL in your IdP

This is where users are redirected after successful authentication with your identity provider, along with the SAML assertion containing user information.

SP Metadata URL

Purpose: Provides complete SAML configuration in standard XML format Format: https://fastcomments.com/saml/metadata/{your-tenant-id} Usage: Some IdPs can automatically import configuration using this URL

The metadata URL contains all necessary SP information in XML format, making it easy to configure compatible identity providers automatically.

SAML Login URL

Purpose: Direct link to initiate SAML authentication for your tenant Format: https://fastcomments.com/saml/login/{your-tenant-id} Usage: Link users directly to SAML authentication or test the flow

You can use this URL to test SAML authentication or provide users with a direct link to sign in via SAML.

SAML Binding Support

FastComments supports the following SAML bindings:

HTTP-POST Binding

• Primary Method: Most common binding for SAML responses
• Security: SAML response is sent via HTTP POST to the ACS URL
• Usage: Recommended for production deployments

HTTP-Redirect Binding

• Alternative Method: SAML response sent via HTTP redirect
• Limitations: Limited payload size due to URL length restrictions
• Usage: Supported but HTTP-POST is preferred

Name ID Policy

FastComments configures the following Name ID policy in SAML requests:

• Default Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• Alternative Formats: Persistent, Transient, Unspecified (configurable)
• Requirement: The email address is used as the primary user identifier

SAML Request Attributes

When initiating SAML authentication, FastComments sends requests with these characteristics:

Request Signing

• Status: Optional (configurable)
• Algorithm: Matches configured signature algorithm
• Certificate: Uses tenant-specific certificate if request signing is enabled

Requested Attributes

FastComments requests the following attributes in SAML AuthnRequests:

• Email: Required for user identification
• First Name: Optional for display purposes
• Last Name: Optional for display purposes
• Roles/Groups: Optional for access control and permissions

Copying SP Information

The SAML configuration page provides clickable fields that automatically copy SP information to your clipboard:

1. Click any SP information field (Entity ID, ACS URL, etc.)
2. The value is automatically copied to your clipboard
3. Paste the value into your identity provider configuration
4. A brief highlight indicates successful copying

This makes it easy to accurately transfer the SP information to your IdP without typing errors.

SP Certificate Information

Certificate Usage

• Purpose: Encrypts communications and verifies SP identity
• Rotation: Certificates are automatically managed by FastComments
• Access: Public certificates are available via the metadata URL

Certificate Details

• Algorithm: RSA-2048 or higher
• Validity: Certificates are automatically renewed before expiration
• Distribution: Available through standard SAML metadata

Troubleshooting SP Configuration

If your identity provider reports issues with SP information:

1. Verify URLs: Ensure all URLs use HTTPS and include the correct tenant ID
2. Check Metadata: Use the metadata URL to verify configuration
3. Test Connectivity: Ensure your IdP can reach FastComments endpoints
4. Validate Format: Confirm your IdP supports the SP information format

Common issues include:

• Incorrect tenant ID in URLs
• Network connectivity problems between IdP and FastComments
• IdP expecting different URL formats or additional configuration options

Testing your SAML configuration ensures that authentication works correctly before deploying to production users.

Pre-Testing Checklist

Before testing SAML authentication, verify:

• ✅ SAML is enabled in FastComments
• ✅ All required fields are completed (IdP URL, Certificate)
• ✅ Identity provider is configured with FastComments SP information
• ✅ Test user account exists in your IdP
• ✅ Test user has appropriate roles assigned

Testing Methods

Method 1: Direct SAML Login URL

1. Get SAML Login URL:

   • Copy from your SAML configuration page
   • Format: https://fastcomments.com/saml/login/{your-tenant-id}

2. Test Authentication:

   • Open SAML login URL in an incognito/private browser window
   • You should be redirected to your identity provider
   • Log in with test credentials
   • Verify successful redirect back to FastComments

Method 2: Admin Dashboard Access

1. Navigate to FastComments:

   • Go to FastComments admin dashboard
   • Look for SAML login option or use the SAML login URL

2. Complete Authentication Flow:

   • Authenticate via your identity provider
   • Verify access to appropriate admin features based on assigned roles

Method 3: Widget Integration Testing

For testing SAML with comment widgets:

1. Embed Widget: Use the FastComments widget on a test page
2. Authentication: Click login and select SAML option (if available)
3. Verification: Confirm user appears as authenticated in the widget

What to Verify During Testing

Authentication Flow

Successful Redirect:

• User is redirected to IdP login page
• IdP login page loads correctly
• No certificate or SSL errors occur

IdP Authentication:

• User can log in with their IdP credentials
• Multi-factor authentication works (if configured)
• No authentication errors from IdP

Return to FastComments:

• User is redirected back to FastComments after successful IdP login
• No SAML assertion validation errors
• User gains access to appropriate FastComments features

User Information

Basic Profile Data:

• Email address is correctly captured
• First and last names appear if provided
• User profile is created or updated

Role Assignment:

• Administrative roles are properly assigned
• User has access to expected admin features
• Permissions match the assigned roles

SAML Response Validation

Certificate Verification:

• SAML response signature is validated successfully
• No certificate validation errors in logs
• Response is accepted as authentic

Attribute Processing:

• Required attributes (email) are present
• Optional attributes are processed correctly
• Role attributes are properly parsed and applied

Testing Different Scenarios

Standard User Flow

1. New User:

   • First-time SAML login
   • Account creation
   • Basic permissions assignment

2. Existing User:

   • Returning user login
   • Profile updates
   • Role changes

Administrative Access Testing

1. Admin Roles:

   • Test users with fc-admin-admin role
   • Verify access to admin dashboard
   • Confirm administrative capabilities

2. Specialized Roles:

   • Test fc-moderator access to moderation features
   • Test fc-analytics-admin access to analytics
   • Test fc-billing-admin access to billing features

Error Scenarios

1. Invalid Certificates:

   • Test with expired or incorrect certificates
   • Verify proper error handling

2. Missing Attributes:

   • Test SAML responses without required email attribute
   • Verify graceful error handling

3. Network Issues:

   • Test with connectivity problems
   • Verify timeout handling

Troubleshooting Test Issues

Common Authentication Problems

Redirect Loop:

• Check SP Entity ID matches IdP configuration
• Verify ACS URL is correctly configured
• Confirm SAML binding settings match

Certificate Errors:

• Ensure certificate includes BEGIN/END markers
• Verify certificate hasn't expired
• Check for extra whitespace or formatting issues

Attribute Issues:

• Confirm email attribute is being sent
• Verify role attributes use correct naming
• Check attribute format (array vs. comma-separated)

Debugging Tools

Browser Developer Tools:

• Monitor network requests during SAML flow
• Check for HTTP errors or redirects
• Examine SAML POST data (if visible)

IdP Testing Tools:

• Most IdPs provide SAML testing interfaces
• Use IdP tools to validate SAML response format
• Test attribute configuration before sending to FastComments

FastComments Support:

• Enable debug logging during testing
• Save error messages and timestamps
• Contact support with specific error details

Testing Best Practices

Test Environment Setup

1. Dedicated Test Users:

   • Create specific test accounts in your IdP
   • Assign various role combinations
   • Use easily identifiable test email addresses

2. Isolated Testing:

   • Use incognito/private browser windows
   • Clear cookies between tests
   • Test with different user accounts

3. Documentation:

   • Record test scenarios and results
   • Document any configuration changes needed
   • Note successful configuration details

Pre-Production Validation

1. Comprehensive Testing:

   • Test all role combinations
   • Verify edge cases and error conditions
   • Confirm performance is acceptable

2. User Acceptance:

   • Have end users test the authentication flow
   • Gather feedback on user experience
   • Verify workflow meets requirements

3. Security Review:

   • Confirm certificate validation works
   • Verify role assignments are secure
   • Test access control enforcement

Production Deployment

After successful testing:

1. Gradual Rollout: Consider rolling out SAML to a subset of users first
2. Monitoring: Monitor authentication success rates and error logs
3. Support Preparation: Prepare support team for SAML-related questions
4. Documentation: Provide user documentation for SAML login process

This guide covers common SAML authentication issues and their solutions.

Certificate and Security Issues

Invalid Certificate Error

Symptoms:

• "Certificate validation failed" error
• Users cannot complete SAML authentication
• SAML responses are rejected

Common Causes:

• Certificate format is incorrect
• Certificate has expired
• Wrong certificate was provided
• Extra characters or whitespace in certificate

Solutions:

1. Verify Certificate Format:

   • Ensure certificate includes -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers
   • Remove any extra whitespace or line breaks
   • Copy certificate directly from IdP metadata or configuration

2. Check Certificate Validity:

   • Verify certificate hasn't expired
   • Confirm certificate is for the correct IdP
   • Use online certificate validators to check format

3. Re-download Certificate:

   • Download fresh certificate from IdP
   • Use IdP metadata URL if available
   • Confirm certificate matches current IdP configuration

Signature Verification Failed

Symptoms:

• SAML assertion signature validation errors
• Authentication fails after IdP login
• "Invalid signature" error messages

Solutions:

1. Algorithm Mismatch:

   • Check signature algorithm in FastComments matches IdP
   • Try different signature algorithms (SHA-256, SHA-1, SHA-512)
   • Verify digest algorithm matches IdP configuration

2. Certificate Issues:

   • Ensure correct signing certificate is configured
   • Verify certificate corresponds to private key used by IdP
   • Check for certificate rotation in IdP

Configuration Issues

Wrong Entity ID or ACS URL

Symptoms:

• IdP reports "Unknown Service Provider"
• SAML responses go to wrong endpoint
• Authentication doesn't complete

Solutions:

1. Verify SP Information:

   • Copy exact Entity ID from FastComments configuration
   • Ensure ACS URL matches format: https://fastcomments.com/saml/callback/{tenant-id}
   • Check for typos in tenant ID

2. IdP Configuration:

   • Update IdP with correct SP Entity ID
   • Configure proper ACS/Reply URL
   • Verify IdP binding settings (HTTP-POST preferred)

Missing or Incorrect Attributes

Symptoms:

• Users created without proper roles
• Missing user profile information
• "Email required" errors

Solutions:

1. Email Attribute:

   • Ensure IdP sends email attribute
   • Check attribute name mapping (email, emailAddress, etc.)
   • Verify email value is valid email address

2. Role Attributes:

   • Confirm IdP sends role/group information
   • Check role attribute names match FastComments expectations
   • Verify role values match FastComments role names exactly

3. Attribute Format:

   • Test both array and comma-separated role formats
   • Ensure attribute values don't have extra whitespace
   • Check for case sensitivity in role names

Authentication Flow Issues

Redirect Loop

Symptoms:

• Browser redirects endlessly between FastComments and IdP
• Authentication never completes
• Multiple redirects shown in browser developer tools

Solutions:

1. Check SP Configuration:

   • Verify Entity ID matches IdP configuration exactly
   • Ensure ACS URL is correctly configured in IdP
   • Check for trailing slashes in URLs

2. Session Issues:

   • Clear browser cookies and try again
   • Test in incognito/private browser window
   • Check for session timeout settings

Access Denied After Authentication

Symptoms:

• SAML authentication succeeds
• User is redirected to FastComments
• "Access denied" or permissions error displayed

Solutions:

1. Role Assignment:

   • Verify user has appropriate roles in IdP
   • Check role attribute is being sent in SAML response
   • Confirm role names match FastComments requirements exactly

2. Package Limitations:

   • Verify account has Flex or Pro plan
   • Check SAML feature is enabled for the package
   • Contact support if package includes SAML but feature unavailable

Identity Provider Specific Issues

Microsoft Azure AD

Common Issues:

• App role assignments not reflecting in tokens
• Claims not being sent properly
• User assignment requirements

Solutions:

• Check user assignment to FastComments application
• Verify app roles are properly configured
• Ensure claims mapping includes required attributes

Okta

Common Issues:

• Group filters not working correctly
• Attribute statements misconfigured
• Application assignment problems

Solutions:

• Review attribute statement configuration
• Check group assignment and filtering rules
• Verify application is assigned to appropriate users/groups

Google Workspace

Common Issues:

• Custom attributes not mapping correctly
• Group membership not being sent
• SAML application configuration errors

Solutions:

• Configure custom schema for role attributes
• Check group membership propagation
• Verify SAML application attribute mapping

Network and Connectivity Issues

Timeout Errors

Symptoms:

• Authentication process times out
• "Request timeout" or similar errors
• Slow authentication flow

Solutions:

1. Network Connectivity:

   • Check firewall rules allow FastComments communication
   • Verify DNS resolution for fastcomments.com
   • Test network connectivity from IdP to FastComments

2. Performance Issues:

   • Check IdP response times
   • Verify certificate chain validation isn't slow
   • Consider network latency between IdP and users

SSL/TLS Issues

Symptoms:

• Certificate warnings during authentication
• SSL handshake failures
• "Secure connection failed" errors

Solutions:

• Ensure all SAML endpoints use HTTPS
• Check certificate validity for all involved domains
• Verify TLS version compatibility

Debugging and Logging

Enabling Debug Information

1. Browser Developer Tools:

   • Monitor Network tab during SAML flow
   • Check Console for JavaScript errors
   • Examine SAML POST requests (if visible)

2. IdP Logging:

   • Enable SAML debugging in your IdP
   • Review IdP logs for SAML request/response details
   • Check for attribute mapping issues

Common Log Messages

FastComments Logs:

• "SAML config not found" - SAML not enabled or misconfigured
• "Invalid certificate" - Certificate validation failed
• "Missing email attribute" - Required email not provided in SAML response

IdP Logs:

• "Unknown service provider" - Entity ID mismatch
• "Invalid ACS URL" - Assertion Consumer Service URL incorrect
• "User not assigned" - User lacks access to SAML application

Getting Help

Information to Gather

When contacting support, provide:

• Exact error messages and timestamps
• SAML configuration details (without sensitive data)
• IdP type and version
• Steps to reproduce the issue
• Browser and network information

FastComments Support

For SAML-related issues:

1. Use the support portal
2. Include tenant ID and affected user emails
3. Provide error messages and configuration details
4. Specify IdP type and configuration approach

IdP Support

For IdP-specific issues:

• Consult IdP documentation for SAML troubleshooting
• Use IdP support channels for configuration problems
• Leverage IdP community forums for common issues

Prevention Tips

Best Practices

1. Test Thoroughly:

   • Test configuration changes in non-production environment
   • Verify with multiple test users
   • Document working configurations

2. Monitor Regularly:

   • Set up monitoring for SAML authentication failures
   • Review certificate expiration dates
   • Monitor for IdP configuration changes

3. Documentation:

   • Maintain documentation of SAML configuration
   • Document any custom configurations or workarounds
   • Keep contact information for IdP administrators

Proactive Maintenance

1. Certificate Management:

   • Monitor certificate expiration dates
   • Plan certificate rotation procedures
   • Test certificate updates before expiration

2. Configuration Reviews:

   • Regularly review SAML configuration
   • Verify IdP configuration remains current
   • Update documentation as changes are made