Stop copying GitHub's user account model for your B2B. Here's how to get it right

Having worked at two B2B companies that adopted GitHub's global user model and later regretted it, I believe it's time to analyze why this model works for GitHub but may not be the optimal choice if you want to avoid the significant extra work it entails.

What is GitHub's user account model and why it works for GitHub

'Social coding' was GitHub's slogan in the beginning, and their user account model reflects that.

Users have one account that can be a member of numerous organizations. Alternatively, they might not be part of an organization at all and simply own their own resources (repositories).

GitHub's initial success as a social network means its initial focus is onboarding users, not organizations.

Organizations (and here I'm referring specifically to Enterprise Organizations) bring their user base with them. They typically require control over user account lifecycles, security posture (such as SSO and password rotations, which are often ineffective), and deprovisioning. This is where the issues begin when implementing authentication and authorization (authnz) within this model.

Authentication enforcement

If you've worked with GitHub, you've likely encountered the practice of users maintaining a second account specifically for their employer organization.

Separating a user's personal identity from their organizational identity within the system is not a simple task.. GitHub.com now supports organization SSO on top of your user login, meaning that when you access an organization's private resources (such as repositories), you are prompted with a two-factor authentication screen to log in via your employer's SSO.

One can almost hear product managers lamenting the added user friction. "Why can't we just do that at the first user login barrier?". While the user belongs to the organization, the organization does not 'own' or control the user's primary identity in GitHub's model. This means enforcing an organization SSO at the user level would mean potentially locking them out of other organizations or their private repositories. It could also potentially allow a rogue organization to lock out a user whose primary account they are not supposed to control. Not cool.

Lifecycle management

SCIM (System for Cross-domain Identity Management) has become a norm for user lifecycle management. It simplifies user provisioning by allowing organizations to create, update, and delete user accounts across multiple platforms efficiently.

GitHub has SCIM for Organizations. This is a clever way of adding and removing global users from the organization in question.

But what if the employer organization doesn't want their users' public contributions mixed with their work contributions? Or what if not every user joining the organization already has a GitHub account?

Well, GitHub has SCIM for Managed Enterprise Users. Global Users are created and added to the org. This means that a specific 'organization user' is created. These Managed User Accounts cannot create public content or collaborate outside your enterprise.

The cost of it all

GitHub needed global users for its social coding platform. However, it also ended up needing users scoped to specific organizations who would not be able to interact with the wider ecosystem. This complexity has come at the cost of implementing SCIM twice, maintaining at least two implementations of login portals/2FA checks, differentiating global users as managed or not, and dealing with all the frontend implications of differing default access levels for these users.

Achieving this level of Identity and Access Management integration typically requires a dedicated team, and their role is critical (admittedly, I'm biased here). This is because the complexity of such a user structure increases the likelihood of issues like escalation of privileges or users being able to affect actions outside their designated container boundary.

Do you need this?

Consider your specific market and product category to determine the most suitable account model.

In the SaaS VCS space, examples like GitHub, GitLab, and Atlassian BitBucket (which shares branding but is distinct from its on-premises counterpart) utilize Global users who can belong to multiple organizations.

• Do you require search capabilities across accounts, workspaces, or tenants (depending on your terminology)?
• Are your customers primarily individuals, or enterprises with compliance requirements?

Build it right

Let's consider a hypothetical company, Strategic Unified Solutions (SUS), whose SaaS product involves white-boarding.

• Users can create a personal account and make notes or 'scribbles' in projects they can choose to make public. They will likely share URLs to these whiteboards on social networks or platforms like Slack, so users accessing from their own personal accounts do not necessarily need to find them via a global search.
• Enterprises can have an account where their projects are private and just shared between users of that account.

With this information and some sneaky design decisions, like avoiding multi-tenant search, I can bypass the need for global users. Users are strictly confined to their workspaces. If the same email address is used for accounts in two different workspaces, these would represent two separate profiles.

Let's see some examples in action

Login

1. Initial Login Prompt: The user starts at a clean login page (/). Instead of asking for a password immediately, it prompts only for an email address. This is often the first step in passwordless or identifier-first login flows.

2. Email Entry: The user enters their email address, [email protected], and clicks "Continue".

3. Account Selection: Because this email address is linked to multiple distinct accounts or contexts within the system, the user isn't logged in directly. Instead, they are presented with an "Account selector" screen (/account-selector). This screen lists the different contexts associated with their email: "Personal", "Bizapps Corp", and "Freelancing Gig".

4. Exploring Login Methods: The user then explores the login process for each account type:

   • Personal Account: Clicking "Personal" navigates to a specific login page for that context (/login/personal). This flow triggers an email-based One-Time Password (OTP) or Magic Link.
   • Corporate Account (OIDC): "Bizapps Corp" has configured SSO for their account with OIDC
   • Freelancing Gig Account (SAML): "Freelancing Gig" has SSO configured with SAML

All of these account types could be accessed directly via tenant-designated login pages (/login/personal, /login/bizapps-corp, /login/freelancing-gig), bypassing the central account selector menu. Utilizing subdomains could offer an additional layer of clarity and user experience. If a central login hub is required, you can maintain a mapping of email addresses to associated accounts. This mapping can then be used if an account switcher option is needed.

• Be wary of using email as your primary user key: Email addresses associated with the same user can change (e.g., due to legal name changes), particularly in corporate environments.
• Identifier-First Flow: Initiate the login process by prompting only for the email address on the initial page (/login).
• Account Disambiguation: Implement a process to handle cases where a single email address is associated with multiple user contexts.

Create an account

Because Strategic Unified Solutions (SUS) aims to reduce friction and allow users to immediately experience their whiteboarding capabilities, social login is considered a requirement. We tried to argue that we could use a magic link flow and that would be enough and would save us maintenance in the future, but nope. The ability to leverage a user's profile picture and other pre-filled information from a social provider is a must-have feature.

1. Choosing Registration: Instead of clicking "Continue" to log in, the user opts to create a new account by clicking the "Create account" button.
2. Registration Options: This navigates the user to the registration page (/register). Here, they are presented with multiple ways to create an account:
   • One time email: Likely initiates a passwordless flow using an email One-Time Password (OTP) or magic link.
   • Login with GitHub: Offers social login/registration via GitHub.
   • Login with Google: Offers social login/registration via Google.
3. Directed to their automatically created workspace Upon clicking the social login button, the user performs the social login/registration flow and gets redirected to their application dashboard (/dashboard/oidc-google-bob-bizz....
   • We could provide the user an intermediate step to select their workspace name.

Key points:

• Limit to One SSO Method Per Account/Workspace: Allowing multiple SSO methods for a single account or workspace can lead to unexpected behavior, such as incorrect updates to a user's permissions or profile based on the login method used.
• Avoid Social Logins When Possible: If feasible, avoiding social logins will simplify auditing and tracing the origin of user accounts.
• Treat Each Social Login as a Distinct Account: If you offer social login options (including public OIDC), it's crucial to treat each separate social login instance as a distinct user account within your system, even if the email address is the same. A user logging in via one social provider, even with a shared email address, might not be the same person as a user logging in via another, because email validation can be complex when relying on third-party identity providers. While you could attempt to validate the email address obtained from the SSO provider with a subsequent OTP verification, this adds complexity that runs counter to the goal of simplicity.
  In this case, Bob's workspace might be internally identified using a scheme like github-oidc-bob-bizapps-com. Even if Bob later changes their email address within GitHub, the same mapping could be maintained using the stable global user ID provided by the Identity Provider.

Conclusion

While models like GitHub's global user account system have proven successful for platforms built around a social networking paradigm, they introduce significant complexity that is often unnecessary and detrimental for many B2B SaaS products. As we've seen with the hypothetical SUS company, tailoring your user model to your specific product category and customer needs, particularly by containing users within defined workspaces or accounts, can drastically simplify your user architecture.

Choosing a simpler model directly impacts implementation effort, ongoing maintenance, and crucially, auditing and security. Each layer of authentication complexity, every additional social login or cross-account interaction point, increases the surface area for potential issues and makes it harder to track user activity and enforce policy consistently.

Instead of defaulting to a global user model, carefully evaluate your product's requirements: Do your users truly need to interact across separate organizational boundaries? Or are their activities primarily confined within their company or team? By prioritizing simplicity and designing an authentication model that aligns with your core user interactions, you can build a more robust, maintainable, and secure system from the outset. Remember, the least authentication components you add, the better positioned you will be for future scalability and security audits. Getting authentication right for B2B often means not just implementing features, but intentionally not implementing those that introduce unnecessary complexity.