SAML Re-Authentication

Restore Zenhub access when your organization uses SAML single sign-on authentication

Understanding SAML and Zenhub

SAML single sign-on (SSO) gives GitHub organization owners control over access to organizational resources including repositories, issues, and pull requests. When your organization uses SAML authentication, you need to periodically re-authenticate your Zenhub access to maintain connection to organizational resources.

GitHub automatically authorizes your Zenhub access when you've recently authenticated with your organization's SAML identity provider in your browser. However, SAML sessions can expire or require re-authorization, which temporarily blocks Zenhub access even though you can still access GitHub normally. This authentication requirement ensures security while sometimes requiring a quick re-authentication to restore full Zenhub functionality.

Recognizing SAML Authentication Issues

SAML re-authentication needs typically show up as specific access problems rather than clear error messages. Watch for these common symptoms that indicate you need to re-authenticate:

Repository list loading indefinitely: When adding new repositories to a workspace, the repository list loads continuously without completing. This happens when SAML authentication has expired but GitHub access remains active.

License request prompts despite having access: You receive prompts to request a Zenhub license even though you already have one assigned. This particularly affects users joining teams with multiple GitHub organizations where each organization requires separate SAML authorization.

Workspace loading failures: Your workspace displays "Workspace cannot be loaded" errors despite having appropriate permissions and recent access. Other team members can access the same workspace successfully, indicating the issue is specific to your authentication state.

Selective repository access: Some repositories appear in your workspace while others from the same organization don't load, suggesting partial authorization rather than complete access denial.

These symptoms indicate your SAML session needs refresh rather than permission problems or Zenhub service issues.

Re-Authenticating Your Access

Follow these steps to restore Zenhub access when experiencing SAML authentication issues:

1. Verify organizational authorization - Confirm with your GitHub organization administrator that Zenhub remains an authorized third-party application for your organization. Skip this step if other team members currently have working Zenhub access, as this confirms organizational authorization is active.

2. Sign out of Zenhub completely - Click your profile menu in the bottom left corner and select "Sign out." This clears your current authentication state and prepares for fresh login.

3. Return to Zenhub login page - Navigate back to app.zenhub.com and click the "Log in with GitHub" button to begin the authentication flow.

4. Authorize organization access - GitHub displays a "Single sign-on to your organization" screen showing your organization name with an "Authorize" button. Click "Authorize" rather than the "Continue" button at the bottom. The Authorize button triggers SAML re-authentication through your SSO provider.

5. Complete SSO provider login - Your organization's SAML identity provider login screen appears. Enter your SSO credentials to authenticate. GitHub redirects you back to Zenhub automatically after successful authentication.

6. Verify workspace access - Confirm that your workspaces load correctly and repositories from the SAML-protected organization appear in your repository lists.

Multi-Device Authentication Requirements

SAML authentication operates per-device rather than per-account, requiring attention when you use Zenhub across multiple computers or browsers.

Device-specific authorization: Each device needs separate SAML authorization through the "Authorize" button during login. Your laptop might have working access while your desktop requires re-authorization, even though you're using the same Zenhub account.

Browser-specific sessions: Different browsers on the same computer maintain separate SAML sessions. Authorization in Chrome doesn't automatically authorize Firefox or Safari on that computer.

Resolving mixed-state access: If you can modify issues in some workspaces but not others, you likely clicked "Continue" instead of "Authorize" during login. Sign out of Zenhub, log back in, and specifically click "Authorize" for each organization requiring SAML access.

Troubleshooting Persistent Issues

If standard re-authentication doesn't restore access, try these additional approaches:

Multiple login cycles: If you've authenticated with GitHub SSO separately outside Zenhub's login flow, you may not see the authorization screen. Sign out and sign back in multiple times to ensure your SAML session is properly recognized. You only need to click "Authorize" during the first successful cycle.

Browser cache clearing: Clear your browser cache and cookies for both GitHub and Zenhub domains, then attempt the authentication process fresh. Cached authentication states sometimes conflict with current SAML requirements.

Incognito mode testing: Try accessing Zenhub in an incognito or private browsing window. This eliminates browser extension conflicts and cached data as potential causes of authentication problems.

Organization-specific authorization: For teams with multiple GitHub organizations, verify you've authorized Zenhub for each specific organization. You might have access to repositories from Organization A but need separate authorization for Organization B's repositories.

Direct GitHub verification: Navigate to your GitHub Settings > Applications > Authorized OAuth Apps and verify Zenhub appears with recent authorization dates for your organizations. Missing or outdated authorization indicates you need to complete the authorization flow from Zenhub's login screen.

Security Implications and Best Practices

Understanding SAML authentication helps you maintain secure access while avoiding unnecessary re-authentication cycles.

Why SAML sessions expire: Your organization's security policies determine SAML session duration. Some organizations require daily re-authentication, while others allow longer sessions. Session expiration protects organizational data by ensuring only currently authenticated users maintain access.

Proactive authentication: When you notice other team members discussing re-authentication, proactively sign out and sign back in using the "Authorize" button. This prevents workflow interruption during active work sessions.

Security trade-offs: More frequent SAML authentication requirements increase security but reduce convenience. If re-authentication happens too frequently for your workflow needs, discuss session duration policies with your IT team rather than attempting workarounds that might compromise security.

FAQ

Q: Why do I need to re-authenticate even though I'm already logged into GitHub?
A: SAML authentication for third-party applications like Zenhub operates independently from your GitHub session. GitHub access doesn't automatically maintain authorization for connected applications, requiring periodic re-authentication through the specific authorization flow.

Q: Does clicking "Continue" instead of "Authorize" cause access problems?
A: Yes, clicking "Continue" bypasses the SAML re-authentication step that Zenhub needs to access your organization's repositories. Always click "Authorize" for organizations using SAML SSO, even if "Continue" appears more prominent.

Q: How often will I need to re-authenticate with SAML?
A: Re-authentication frequency depends on your organization's SAML session duration policies. Some organizations require daily authentication, while others allow sessions lasting weeks or months. Check with your IT team for your specific policy.

Q: Can I avoid SAML re-authentication by staying logged in continuously?
A: No, SAML sessions expire based on time rather than activity. Keeping Zenhub open doesn't prevent session expiration. You'll need to re-authenticate when sessions expire regardless of continuous usage.

Q: What should I do if re-authentication doesn't restore access after multiple attempts?
A: Contact your GitHub organization administrator to verify Zenhub remains an authorized application. If authorization is correct but access problems persist, contact Zenhub support with specific error messages and your organization details for investigation.

Q: Do I need to re-authorize on every device I use?
A: Yes, SAML authorization is device and browser-specific. You must click "Authorize" during login on each computer and browser where you access Zenhub, even though you're using the same account.