Troubleshooting Common SSO Errors
This guide explains common single sign-on (SSO) issues in Coalesce and how to fix them. It covers configuration errors, network restrictions, OAuth integration problems, and user management issues.
Before You Begin
Before troubleshooting, ensure you have:
- Administrative access to your identity provider.
- Coalesce admin privileges.
- Access to Snowflake console.
- Network configuration details from your IT team.
Common SSO Configuration Issues
SSO Button Not Appearing
What You'll See:
- No SSO button visible on login page.
- Users see only standard login form.
Why This Happens:
- Incomplete or incorrect SSO configuration.
- Using wrong login URL.
- Missing required configuration fields.
Solutions:
-
Correct the Subdomain Field
Incorrect: https://yourorg.app.coalescesoftware.io/
Correct: yourorg -
Use the Correct SSO URL
- Access format:
https://mySubdomain.<app_domain>
- Example:
https://hello.app.coalescesoftware.io/login
- Test in incognito or private browser tab
- Access format:
-
Check that these fields are properly configured
- Authority
- Subdomain
- Authorization Server
- OIDC Client ID
- Server-Side Authorization
-
Clear Browser Cache
- Use incognito or private browsing mode
- Clear browser cache and cookies
- Ensure correct regional URL (US vs APAC environments)
SSO Button Appears Greyed Out
What You'll See:
- SSO button is visible but disabled/greyed out.
Solution:
Access Coalesce through your organization's subdomain URL rather than the generic login page:
Use: https://yourorg.app.coalescesoftware.io
Not: https://app.coalescesoftware.io
Missing Identity Provider Settings
Common Issues:
- Missing Microsoft Graph API permissions in Azure app registrations.
- Incorrect authorization server URLs or redirect URIs.
- Extra spaces or characters in configuration fields.
Solutions:
- Ensure these permissions are granted
- Profile
- OpenID
- Check Redirect URIs
- Ensure exact match for example:
https://yoursubdomain.app.coalescesoftware.io/login/callback
,https://yoursubdomain.app.eu.coalescesoftware.io
- Ensure exact match for example:
- Validate Configuration Fields
- Remove extra spaces or characters
- Confirm admin consent is granted for API permissions
Network and Authentication Problems
Snowflake Network Policies Blocking OAuth Redirects
What You'll See:
- SSO login fails during Snowflake OAuth process.
- Network policy errors in Snowflake logs.
You can either:
-
Associate Network Policy with OAuth Security Integration
ALTER SECURITY INTEGRATION <oauth_integration>
SET NETWORK_POLICY = <oauth_network_policy>; -
Create Integration-Specific Network Policy
CREATE SECURITY INTEGRATION oauth_kp_int
TYPE = oauth
ENABLED = true
OAUTH_CLIENT = custom
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://example.com'
NETWORK_POLICY = mypolicy;
Additional Steps:
- Add Coalesce IP addresses to network policy (region-specific).
- Check if policy is applied at user, account, or integration level.
- Recreate security integration if policies were applied after creation.
Network Security Tools Interfering
What You'll See:
- SSO flow interrupted or fails
- Network security tool blocks OAuth requests
Solutions:
- Add Coalesce domains and IP addresses to security tool's allowlist.
- Configure tool to allow OAuth redirect flows for Coalesce domains.
- Test using incognito/private browsing mode.
- Work with your IT team to whitelist OAuth endpoints and callback URLs.
Private Link Configuration Issues
What You'll See:
- Authentication fails when using private link.
- SSL/TLS certificate errors.
Solutions:
- Verify correct private link URL in SSO configuration.
- Update OAuth security integration redirect URIs for private link endpoints.
- Ensure private link DNS resolution works correctly.
- Check SSO provider configuration matches private link subdomain.
- Test with public endpoint first, then migrate to private link.
OAuth Token and Integration Issues
Expired OAuth Refresh Tokens
What You'll See:
- Users must re-authenticate frequently.
- "Token expired" errors.
Solutions:
-
Check Token Validity Settings
-- Check current setting in Snowflake (default is 90 days)
SHOW PARAMETERS LIKE 'OAUTH_REFRESH_TOKEN_VALIDITY'; -
Implement Retry Mechanisms
- Add retry logic in job schedulers
- Consider switching to key pair authentication for environments
-
Re-authenticate Users
- Disconnect and reconnect OAuth credentials in Coalesce
- Guide users through fresh authentication flow
Invalid OAuth Security Integrations
What You'll See:
- OAuth integration errors in Snowflake.
- Authentication failures using the integration.
Solutions:
-
Verify Integration Configuration
DESCRIBE SECURITY INTEGRATION <integration_name>;
-
Recreate Integration
- Create new OAuth security integration with correct parameters.
- Verify client ID and secret match between Snowflake and Coalesce.
- Ensure redirect URI matches Coalesce callback URL exactly.
- Confirm integration is enabled.
User Management Problems
Multiple Accounts for Same Person
What You'll See:
- User has both SSO and non-SSO accounts.
- Permission conflicts between accounts.
Recommended Approach:
- Disable non-SSO account for daily operations.
- Transfer project memberships and permissions to SSO account.
- Document account usage purposes.
Users Created Outside SSO Protocols
What You'll See:
- Users bypass SSO during account creation.
- Inconsistent user attributes.
Solutions:
- Verify SSO configuration before creating users.
- Ensure users access correct SSO-enabled subdomain.
- Check identity provider configuration for user attributes.
- Delete incorrectly created users and redirect through proper SSO flow.
General Troubleshooting Steps
Initial Diagnostics
- Browser Testing
- Clear browser cache and cookies for both Coalesce and identity provider.
- Test in incognito/private browser window.
- Try different browsers.
- Network Verification
- Check with your IT team about network policies blocking OAuth flows.
- Verify user has correct permissions in identity provider and Coalesce.
- Test from different network locations if possible.
- Configuration Validation
- Verify all configuration fields are correctly entered.
- Check for extra spaces or special characters.
- Confirm redirect URIs match exactly.
Best Practices
- Account Management
- Maintain at least one non-SSO admin account as backup.
- Use service accounts for API integrations.
- Document account purposes and usage.
- Regional Considerations
- Use correct regional IP addresses based on Coalesce instance location.
- Testing Protocol
- Always test SSO configuration in staging environment first.
- Use incognito/private browsing for testing.
- Test with multiple user accounts and roles.
When To Contact Support
- Configuration appears correct but SSO still fails.
- Deleted SSO users need manual re-enablement.
- Network policy changes don't resolve OAuth issues.
- Multiple troubleshooting attempts haven't resolved the problem.
Information to Include:
- Specific error messages
- Organization details and subdomain
- Identity provider type and configuration
- Network environment details
- Steps already attempted
Contacting Coalesce support.
Quick Reference Checklist
Before Opening Support Ticket:
- Verified subdomain configuration is correct.
- Tested with incognito/private browser.
- Checked all required SSO configuration fields.
- Confirmed network policies allow Coalesce IP addresses.
- Validated identity provider permissions and settings.
- Tested with correct regional URL.
- Attempted browser cache clearing.
- Verified redirect URIs match exactly.