SSO Authentication Guide

​

Overview

​

When to Use SSO Authentication

• Organizations with existing identity providers
• Environments requiring centralized user management
• Compliance requirements mandating enterprise authentication
• Large user bases where manual user provisioning is impractical

​

How SSO Works with Fiddler

​

User Provisioning

​

Authentication Flow

1. User Access: User navigates to Fiddler login page
2. SSO Redirect: User clicks “Sign in with SSO” and is redirected to your identity provider
3. Identity Provider Authentication: User authenticates with their organizational credentials
4. Automatic Provisioning: If first login, Fiddler creates the user account automatically
5. Access Granted: User gains access to Fiddler as an Org Member and potentially additional privileges if Group Syncing is implemented

​

Supported Identity Providers

​

SSO Configuration Process

​

Prerequisites

• Administrative access to your identity provider
• Access to the Fiddler AuthN management console
• Access to the AuthN user acount having the “Org Owner” role
• Required information from your identity provider (client IDs, metadata URLs, certificates)

​

General Configuration Steps

1. Log into the AuthN authentication management console
2. Select your customer organization from the dropdown
3. Navigate to Settings > Login and Access > Identity Providers
4. Select your desired provider by selecting its icon in the Add Provider section

1. Provider Name: Enter a descriptive name for your SSO integration
2. Copy AuthN Settings: If required, copy AuthN settings to use in creating the application in your IdP
3. IdP Required Fields: Populate your IdP’s required fields
4. Connection Details: Copy required settings from your IdP:
   • Client ID or Application ID
   • Metadata URL or Issuer URL
   • Client Secret (if required)
   • Certificate information (for SAML)

• ✅ Enable “Automatic creation” - Creates new users on first successful login
• ✅ Enable “Automatic update” - Updates user information from identity provider
• ✅ Select “Check for existing username” - Links identities to existing accounts when appropriate

• First Name (firstName, given_name)
• Last Name (lastName, family_name)
• Email Address (email)

• Groups (groups) - For automated group-based access control see Mapping LDAP Groups guide

• Paste the Fiddler-provided script into the text area
• Paste the script name into the Name text box

• Set the Trigger Type option per the guide
• Set the Actions dropdown option per the guide

1. Save your SSO configuration
2. Test authentication with a sample user account
3. Verify user information is properly mapped
4. Confirm automatic provisioning works as expected

​

Group Synchronization

​

Supported Providers

• Okta (OIDC and SAML)
• Microsoft Entra ID (OIDC with proper configuration)
• Ping Identity (SAML)

​

User Management with SSO

​

Automatic User Provisioning

1. User authenticates successfully through SSO
2. Fiddler automatically creates user account with information from the IdP
3. User receives default organization member role (the very first user to login will be assigned the Org Admin role)
4. Additional permissions can be assigned through Fiddler teams or individual roles

• User information automatically updates from the IdP on each login
• Group memberships sync automatically (if configured)
• User status changes (deactivation/reactivation) can be managed through the IdP (note that Fiddler deactivates user accounts rather than deletes)

​

Mixed Authentication Environments

​

Combining SSO and Email Authentication

• SSO Users: Automatically provisioned from identity provider
• Email Users: Manually added through the AuthN management console
• Separate Login Paths: Users choose appropriate authentication method at login if more than one path has been enabled

​

User Account Constraints

• Single Authentication Method: Each user account uses either SSO or email authentication, not both
• Account Linking: Existing email-authenticated users can be linked to SSO identities under specific conditions

​

Troubleshooting Common Issues

​

External User Not Found

• Enable the Automatic creation toggle — creates a Fiddler user on first sign-in
• Enable the Automatic update toggle — syncs profile fields (name, email) on subsequent sign-ins
• Set the Determines whether an identity will be prompted to be linked to an existing account dropdown to Check for existing username — matches the incoming identity to an existing user before creating a duplicate

• Your identity provider is not configured to pass the attributes that the Fiddler action script expects (e.g., for SAML: firstName, lastName, email, groups; for OIDC: given_name, family_name, email, groups)
• The attribute names in your identity provider do not match the attribute names in the action script
• The action script was not copy-pasted correctly and has a syntax error — verify the script has no broken string literals or missing quotes

​

Debugging Identity Provider Attribute Responses

let logger = require("zitadel/log");
logger.log('****** Action debugging start ******');
logger.log('email present: ' + (email != undefined) + ', type: ' + typeof email);
logger.log('firstName present: ' + (firstName != undefined) + ', type: ' + typeof firstName);
logger.log('lastName present: ' + (lastName != undefined) + ', type: ' + typeof lastName);
logger.log('****** Action debugging end ******');

​

Verifying SAML Assertion Attributes

1. Open Chrome DevTools (F12 or Ctrl+Shift+I) and navigate to the Network tab
2. Enable Preserve log to retain network entries across redirects
3. Attempt an SSO sign-in through your SAML identity provider
4. In the Network tab, locate the POST request to https://authn-{base_url}/ui/login/login/externalidp/saml/acs
   
5. Open the Payload tab for that request and copy the SAMLResponse value
   
6. Decode the SAMLResponse locally using your terminal — this returns an XML document.
   The decoded SAML assertion contains email, names, group memberships, and signed identity claims. Decode it locally rather than pasting into an online Base64 decoder or SAML inspector.
   • macOS: pbpaste | base64 -d
   • Linux: xclip -selection clipboard -o | base64 -d (or xsel -b | base64 -d)
   • Cross-platform: echo "<value>" | base64 -d
   • Windows PowerShell: [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("<value>"))
7. In the decoded XML, verify that the attributes your action script expects (e.g., for SAML: firstName, lastName, email, groups; for OIDC: given_name, family_name, email, groups) are present and contain the correct values

​

Authentication Failures

• Verify redirect URI in identity provider matches: {fiddler_url}/api/sso/{provider}/callback
• Check for HTTP vs. HTTPS mismatches

• Monitor client secret expiration dates (typically 6-24 months)
• Update expired certificates or secrets in both identity provider and Fiddler configuration

• Verify required attributes (firstName, lastName, email) are included in authentication response
• Check attribute name consistency between identity provider and Fiddler configuration

​

User Provisioning Issues

• Confirm “Automatic creation” setting is enabled
• Verify user has appropriate permissions in identity provider
• Check authentication logs for error messages

• Validate attribute mappings in identity provider configuration
• Ensure identity provider includes required claims in authentication tokens

• Verify groups attribute is included in identity provider claims
• Check that corresponding teams exist in Fiddler
• Confirm group names match between identity provider and Fiddler teams

​

Next Steps

1. Choose Your Provider: Review the provider-specific integration guides
2. Plan Implementation: Coordinate with your identity provider administrator
3. Test Configuration: Set up a test environment before production deployment
4. Train Users: Provide documentation on the new authentication process