We have helped dozens of organizations deploy Secureframe for SOC 2 compliance, and the same configuration issues come up again and again. Integration connection failures, evidence collection errors, policy deployment problems, and user onboarding complications are predictable friction points during initial setup that can delay audit readiness by weeks if the root causes are not identified and addressed. In our experience, most Secureframe setup issues have straightforward solutions that do not require Secureframe support intervention, but finding the right fix requires understanding why the issue occurred in the first place. This troubleshooting guide covers the most frequently encountered Secureframe setup and configuration issues we see across client engagements, organized by category, with step-by-step resolution procedures for each problem. Whether you are encountering OAuth authorization failures, integration data sync issues, missing evidence artifacts, or policy acknowledgment problems, this guide provides the diagnostic steps and fixes we use to get Secureframe deployments back on track.
This troubleshooting guide covers common Secureframe setup issues including integration connection failures, evidence collection errors, policy deployment problems, user onboarding issues, and step-by-step resolution procedures.
Integration Connection Issues
AWS Integration Problems
| Issue | Symptoms | Root Cause | Resolution |
|---|
| AWS connection fails during setup | OAuth error or CloudFormation stack creation failure | IAM permissions insufficient or CloudFormation stack region mismatch | Verify IAM role has required permissions; ensure CloudFormation stack is deployed in the correct region; check for organization-level SCPs blocking Secureframe access |
| AWS resources not appearing | Integration shows connected but resource inventory is empty or incomplete | Secureframe IAM role missing read permissions for specific services | Review Secureframe's required IAM policy document; add missing service permissions (common: EC2, RDS, S3, Lambda, ECS, EKS) |
| AWS multi-account issues | Only one account's resources appear despite connecting multiple accounts | Each AWS account requires separate integration connection | Connect each in-scope AWS account individually; verify each account's IAM role is properly configured |
| Stale AWS data | Resource inventory does not reflect recent infrastructure changes | Sync interval not yet reached; or integration health degraded | Wait for next sync cycle (typically 4-24 hours); check integration health status; reconnect if sync has stopped |
| AWS GovCloud not syncing | GovCloud resources not appearing despite connection | GovCloud requires separate partition authentication | Verify GovCloud-specific integration setup; ensure IAM role is created in GovCloud partition |
Identity Provider Integration Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Okta connection fails | OAuth authorization error or timeout during Okta connection | Admin consent not granted; or Okta API rate limits | Ensure Super Admin role is used for authorization; verify Okta API token has required scopes; check Okta admin console for rate limit warnings |
| Google Workspace users missing | Some users not appearing in Secureframe after Google Workspace connection | Users in specific organizational units may not be synced; suspended users excluded | Review organizational unit scope in integration settings; verify all in-scope OUs are included |
| Azure AD sync incomplete | Some users or groups missing from Secureframe | Application permissions not consented at admin level; or specific attributes not shared | Re-authorize with Global Admin; verify API permissions include User.Read.All, Group.Read.All, and Directory.Read.All |
| MFA status not reporting | Integration connected but MFA status shows as unknown | Identity provider API may not expose MFA status through standard sync | Check if additional API permissions are needed for MFA reporting; some providers require specific scopes for MFA data |
| User deactivation not syncing | Terminated users still showing as active in Secureframe | Sync delay; or user not fully deactivated in identity provider | Verify user is deactivated (not just suspended) in identity provider; wait for next sync cycle; manually update if urgent |
Version Control Integration Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| GitHub repositories not appearing | Integration connected but repository list is empty | GitHub App not installed on the correct organization; or insufficient permissions | Verify GitHub App is installed on the target organization (not personal account); check App permissions include repository read access |
| Branch protection not detected | Repositories appear but branch protection settings show as unconfigured | Branch protection rules not set on default branch; or API permissions insufficient | Verify branch protection is configured on the default branch (main/master); check GitHub App has administration read permission |
| GitLab connection timeout | Connection attempt times out during OAuth flow | GitLab instance version incompatibility; or network restrictions blocking Secureframe | Verify GitLab version is supported; check for firewall rules blocking Secureframe IP addresses; try reconnecting |
| Bitbucket workspace issues | Integration connects but wrong workspace data appears | Connected to personal workspace instead of organization workspace | Disconnect and reconnect, selecting the correct workspace during authorization |
HR Platform Integration Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| BambooHR employee list incomplete | Some employees missing from Secureframe sync | Employees in specific departments or locations may be filtered; custom fields not mapping | Review integration mapping settings; verify all employee statuses (active, contractor) are included in sync |
| Gusto data sync failure | Connection established but employee data not syncing | API token expired; or Gusto API changes | Regenerate API token in Gusto; reconnect integration; verify updated permissions |
| Employee status mismatch | Active employees showing as inactive or vice versa | Employment status field mapping differs between HR system and Secureframe | Review status field mapping; adjust mapping to align HR system status values with Secureframe expected values |
| Contractor classification | Contractors not appearing or classified incorrectly | HR system may not export contractor records by default | Verify contractor records are included in HR system export; check integration settings for contractor inclusion |
Evidence Collection Errors
Missing Evidence Artifacts
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Evidence not generating for connected integration | Integration shows healthy but evidence artifacts are missing | Control-to-evidence mapping not configured; or integration not collecting the specific data needed for that evidence type | Review control mapping; verify the integration is configured to collect data for the affected control areas |
| Manual evidence items showing as overdue | Evidence items requiring manual upload show overdue despite uploads | Uploaded evidence not mapped to the correct control; or file format not accepted | Re-upload evidence mapped to the specific control; verify file format is supported (PDF, PNG, CSV) |
| Evidence freshness warnings | Evidence items marked as stale despite active integrations | Sync interval exceeded freshness threshold; or specific evidence type requires more frequent collection | Check integration sync frequency; reduce freshness threshold if appropriate; investigate if specific evidence requires a supplemental manual upload |
| Screenshot evidence failing | Automated screenshot evidence not capturing | Browser-based screenshot capture blocked by CSP or authentication | Verify target systems allow Secureframe's evidence capture; provide updated credentials if login required |
| Evidence count discrepancy | Compliance dashboard shows fewer evidence items than expected | Some controls may not have evidence mapping configured; or evidence types require manual assignment | Review each control's evidence requirements; map automated evidence where available; create manual evidence tasks for remaining items |
Evidence Quality Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Evidence does not match control requirement | Auditor flags evidence as insufficient for the control | Automated evidence captures data but not the specific aspect the auditor needs | Review auditor's evidence requirements; supplement automated evidence with manual documentation addressing specific auditor needs |
| Duplicate evidence artifacts | Same evidence appearing multiple times | Multiple integrations generating overlapping evidence for the same control | Review evidence mapping; remove duplicate mappings; designate primary evidence source for each control |
| Evidence date range gaps | Evidence does not cover the full observation period | Integration connected mid-observation period; or sync gaps during the period | Upload manual evidence for pre-integration period; document any gaps with explanation for auditor |
| Evidence format incompatible with auditor | Auditor cannot review evidence in Secureframe's format | Auditor preference for specific file formats or external review | Export evidence in auditor's preferred format; provide auditor portal access; or share evidence packages via secure file transfer |
Policy Deployment Problems
Policy Configuration Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Policies not deploying to employees | Policies created but not visible to team members | Policy deployment not activated; or employee group not selected for distribution | Activate policy deployment in policy settings; select target employee groups; verify deployment configuration |
| Policy templates missing required sections | Template policies do not cover all auditor-expected topics | Default templates may not include organization-specific sections | Customize templates to include organization-specific details (security contacts, incident response procedures, specific tool configurations) |
| Policy acknowledgment workflow stuck | Employees not receiving acknowledgment requests | Email notification settings not configured; or employee email addresses not synced | Verify notification settings; check employee email addresses in Secureframe match current addresses; resend acknowledgment requests |
| Policy version conflicts | Multiple versions of the same policy creating confusion | Policy updated but old version still deployed; or version numbering inconsistent | Archive old versions; deploy only the current version; establish version numbering convention |
| Custom policy upload failing | Uploaded policy document not accepting | File format unsupported; or file size exceeds limit | Convert to supported format (PDF recommended); reduce file size; verify upload limits |
Policy Acknowledgment Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Low acknowledgment completion rate | Most employees have not acknowledged policies after deployment | Notification not received; employees unaware of requirement; or acknowledgment process unclear | Send reminder notifications; communicate policy acknowledgment requirement through team channels; simplify acknowledgment process |
| Acknowledgment timestamps missing | Acknowledgments recorded but no timestamp | System configuration issue; or acknowledgment recorded without timestamp metadata | Contact Secureframe support if timestamps are not generating; verify acknowledgment workflow captures timestamp data |
| Former employee acknowledgments counting | Terminated employees still showing in acknowledgment tracking | Employee status not updated; or terminated employees not removed from acknowledgment groups | Update employee status; remove terminated employees from active acknowledgment tracking |
| Bulk acknowledgment needed for policy update | Updated policy requires re-acknowledgment from all employees | Policy update invalidates previous acknowledgments | Deploy updated policy with new acknowledgment requirement; communicate to team that re-acknowledgment is needed due to policy update |
User Onboarding and Access Issues
Employee Onboarding Problems
| Issue | Symptoms | Root Cause | Resolution |
|---|
| New employees not appearing | Recently hired employees not synced to Secureframe | HR integration sync delay; or new employee not yet in HR system | Wait for next HR sync cycle; manually add employee if urgent; verify employee is in HR system |
| Employee missing compliance tasks | Employee in Secureframe but not assigned required tasks | Employee not assigned to correct groups or departments; onboarding workflow not triggered | Assign employee to appropriate compliance groups; trigger onboarding workflow manually; verify group-based task assignment |
| Employee cannot access Secureframe | Employee receives invitation but login fails | SSO configuration issue; or employee's identity provider account not provisioned | Verify SSO settings; confirm employee has active account in identity provider; check Secureframe invitation link validity |
| Security training not assigned | Employee onboarded but training module not triggered | Training assignment rules not configured for new employees; or training module not active | Configure automatic training assignment for new employees; activate training module; manually assign training if needed |
Admin and Role Configuration Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Admin cannot access all features | User with admin role missing access to certain features | Admin role does not include all permissions; or feature requires specific role assignment | Review role permissions; assign additional permissions as needed; check if feature requires elevated role |
| Auditor access not working | Auditor cannot access evidence or controls through auditor portal | Auditor invitation not sent; or auditor role not configured | Send auditor invitation; verify auditor role permissions include evidence view access; check auditor portal URL |
| Multiple admins causing conflicts | Different admins making conflicting configuration changes | No change management process for Secureframe configuration | Establish single compliance owner for Secureframe configuration; use audit log to track changes; implement change approval process |
Compliance Score and Dashboard Issues
Score Discrepancies
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Compliance score unexpectedly low | Score drops after connecting new integration | New integration reveals compliance gaps previously undetected | Review newly identified gaps; this is expected behavior — the integration is providing accurate data; address identified gaps |
| Score not improving after fixes | Compliance issues resolved but score unchanged | Fix not yet synced; or fix does not address the specific check criteria | Wait for next sync cycle; verify the fix addresses the exact criteria being checked (not a related but different issue) |
| Score different from auditor assessment | Internal compliance score does not match auditor's readiness assessment | Platform and auditor use different evaluation criteria and weighting | Understand that platform scores are directional, not definitive; auditor assessment is the authoritative evaluation |
| Controls showing as failing without clear reason | Control marked as failing but no obvious issue visible | Test criteria may evaluate specific configurations that are not immediately obvious | Click into the failing control for detailed test results; review specific checks and criteria; address each failing check individually |
Dashboard Configuration Issues
| Issue | Symptoms | Root Cause | Resolution |
|---|
| Dashboard not reflecting current state | Data appears outdated despite active integrations | Dashboard cache; or integration sync in progress | Refresh the dashboard; wait for current sync to complete; check integration health for sync issues |
| Missing controls on dashboard | Fewer controls displayed than expected for SOC 2 | Framework scope may not include all criteria; or controls not mapped to selected framework | Review framework configuration; ensure all selected Trust Service Criteria are included; verify control-to-criteria mapping |
| Alert notifications not working | No alerts despite compliance score changes | Notification preferences not configured; or alert thresholds not set | Configure notification preferences in account settings; set alert thresholds for compliance score changes |
Pre-Audit Readiness Issues
Common Pre-Audit Blockers
| Blocker | Impact | Resolution |
|---|
| Evidence gaps for observation period | Auditor cannot verify controls for full period | Identify gaps; provide manual evidence for uncovered periods; document reasons for gaps |
| Policy acknowledgments incomplete | Auditor flags incomplete policy deployment | Send final acknowledgment reminders; document any employees who cannot acknowledge (leave, terminated) |
| Integration disconnected during observation | Evidence collection interrupted mid-period | Reconnect integration; verify evidence coverage; provide manual evidence for disconnection period |
| Vendor assessments not completed | Vendor management control flagged as incomplete | Complete vendor risk assessments for all critical vendors; document assessment methodology |
| Access reviews not documented | Quarterly access review evidence missing | Conduct and document access reviews for remaining quarters; establish quarterly review calendar |
| Risk assessment not current | Annual risk assessment missing or outdated | Complete or update risk assessment; document risk assessment methodology and results |
Audit Preparation Checklist
- Verify all integrations are connected and syncing within the last twenty-four hours
- Confirm evidence coverage spans the full observation period for all automated evidence
- Complete all manual evidence uploads for items that cannot be automated
- Verify all policy acknowledgments are current (target one hundred percent completion)
- Complete quarterly access reviews for the observation period
- Finalize vendor risk assessments for all critical vendors
- Update risk assessment to current date
- Verify employee security training completion for all current employees
- Test auditor portal access to ensure the auditor can review evidence
- Review compliance score and resolve any remaining failing controls
Key Takeaways
- Integration connection failures are the most common Secureframe setup issue we see — the majority are caused by insufficient API permissions, incorrect account selection (personal vs organization), or OAuth authorization not completed with an admin-level account; resolving these typically requires re-authorizing with proper credentials and verifying API permission scopes
- Evidence collection errors usually stem from missing control-to-evidence mapping rather than integration failures — when an integration is connected and healthy but evidence is not generating, we advise clients to check that the integration's data collection is mapped to the specific controls requiring evidence; Secureframe may collect the data but not automatically associate it with every relevant control
- Policy deployment problems most commonly involve notification configuration and employee email synchronization — policies may be properly configured in Secureframe but employees do not receive acknowledgment requests because notification settings are not enabled or email addresses do not match between the HR system and Secureframe; we always recommend verifying notification settings and email synchronization as the first troubleshooting step
- Compliance score drops after connecting new integrations are expected behavior, not errors — new integrations provide accurate visibility into your environment, and a lower score means the platform is now correctly identifying gaps that were previously invisible; treat score drops as useful data rather than problems to fix
- Pre-audit readiness issues are preventable with a structured preparation timeline — we recommend beginning audit preparation eight weeks before fieldwork, verifying evidence coverage, completing pending manual evidence items, and testing auditor portal access; most pre-audit blockers are administrative (missing acknowledgments, incomplete vendor assessments) rather than technical
- We help organizations troubleshoot Secureframe setup issues and resolve configuration blockers at Agency — from integration configuration through evidence gap resolution and auditor preparation, ensuring your platform is properly configured and audit-ready
Frequently Asked Questions
How long should integration sync take after initial connection?
In our experience helping clients configure Secureframe, most integrations complete their initial data sync within one to four hours after connection. Cloud provider integrations (AWS, GCP, Azure) with large resource inventories may take up to twenty-four hours for a complete initial sync. If an integration has not synced within twenty-four hours, we recommend checking the integration health status in Secureframe for error messages, verifying API credentials are valid, and attempting to reconnect. For persistent sync failures, check that firewall rules or network policies are not blocking Secureframe's API access.
What should we do if our compliance score drops significantly after setup?
We see this frequently, and what we tell every client is that a significant compliance score drop after initial setup typically means the platform has identified real compliance gaps in your environment. We advise reviewing the specific failing controls and prioritizing remediation by severity. Start with high-severity items (missing encryption, disabled MFA, unreviewed access) before addressing lower-severity issues. A score of forty to sixty percent after initial setup is typical for organizations beginning their SOC 2 journey — the score improves as gaps are remediated. Do not panic about the initial score; focus on systematic remediation.
Can we switch auditors if our current auditor is not compatible with Secureframe?
Yes. What we advise clients is that auditor selection is independent of platform selection, and you can change auditors at any time. However, verify that your new auditor is comfortable reviewing evidence within Secureframe before engaging. Most auditors work with multiple compliance platforms and are familiar with Secureframe's auditor portal. If your auditor prefers a different evidence review format, Secureframe's evidence export capabilities can provide evidence packages in the auditor's preferred format.
How do we handle evidence for periods before Secureframe was connected?
This is one of the most common situations we help clients navigate. For the observation period before Secureframe integration, you need to provide manual evidence from your original systems. We recommend exporting relevant data (access logs, configuration screenshots, change management records) from each system for the pre-Secureframe period and uploading these as manual evidence in Secureframe, mapped to the appropriate controls. Document the transition date clearly for your auditor, explaining that automated evidence covers the post-integration period while manual evidence covers the pre-integration period.
