Allow User Uniqueness at the Organization Level

[hifabienne]

As an organization administrator, I want to configure ZITADEL to allow users to be unique within my organization instead of the entire instance, so that I can manage users independently from other organizations and avoid conflicts due to shared user identifiers.

This feature will only be implemented for the session API, and hosted login v2, as at this point login v1 will be removed.

Acceptance Criteria

• Configuration Option
  • I am able to configure if a user should be unique on instance level or organization
  • The default is instance to maintain backward compatibility
• User Creation
  • When "user Uniqueness Scope " is set to "organization:
    • Users with the same username or linked identity provider (IdP) ID can be created in different organizations.
    • The system should prevent the creation of users with duplicate usernames or linked IdP IDs within the same organization.
  • When "user Uniqueness Scope " is set to "instance:
    • Users with the same username or linked identity provider (IdP) ID can't be created in different organizations.
• User Linking (Idp)
  • When "User Uniqueness Scope" is set to "Organization":
    • Users can link the same IdP account (e.g., Google account) to their accounts in different organizations.
    • The system should prevent linking the same IdP account to multiple users within the same organization.
  • When "user Uniqueness Scope " is set to "instance:
    • Users can't link the same IdP account (e.g., Google account) to their accounts in different organizations.
• Login Process (Organization Preselection)
  • When "User Uniqueness Scope" is set to "Organization" and a user attempts to log in with a username or IdP ID that exists in multiple organizations and an orgnaization id is provided:
    • The login process should proceed based on the selected organization.
    • The user should be able to login without an error
• Error Handling
  • When "User Uniqueness Scope" is set to "Organization":
    • Attempting to create a duplicate user within the same organization should result in a clear error message indicating the conflict.
    • When a user is logging in, and the user cannot be found in the selected organization, a user not found error should be displayed

Technical Considerations

• Implementation for hosted login v2 only
• Hosted Login v1 will be removed

Future Improvements

• Do we want to provide an organization dropdown? If so can I choose if it is before or after loginname?
  In a initial implementation i would start with organization scope only, and have a look if we can provide an organization dropdown later on
  --> related issue: Organization name/domain prompt page #7887

[livio-a]

The setting should replace the existing toggle UserLoginMustBeDomain of the DomainPolicy (in the future).
UserLoginMustBeDomain is used to decide if the username will be automatically suffixed with the organization's domain, e.g. username@domain.com or username@email.com@domain.com.

Implemenation

• Add a new setting UserSetting in the API v2
• Setting should be available on different contexts (system, instance, organization)
• Setting has an attribute userUniquenessScope which can be set to either instance or organization

Some implementation considerations / informations:

• User creation:

  • Domain check: Similar to the check we do based on UserLoginMustBeDomain, we need check if the domain is used / reserved by another organization, resp. can skip that check if the uniqueness is set to organization:
    

    zitadel/internal/domain/human.go

    Lines 80 to 88 in f9742a5

    	func (u *Human) CheckDomainPolicy(policy *DomainPolicy) error {
    	if policy == nil {
    	return zerrors.ThrowPreconditionFailed(nil, "DOMAIN-zSH7j", "Errors.Users.DomainPolicyNil")
    	}
    	if !policy.UserLoginMustBeDomain && u.Profile != nil && u.Username == "" && u.Email != nil {
    	u.Username = string(u.EmailAddress)
    	}
    	return nil
    	}

  • IdP links: The current uniqueness is enforced on an instance level based on the externalUserID and ID of the IdP. This would need to be changed and include the organizationID in case the uniqueness is set to organization.
    

    zitadel/internal/repository/user/human_external_idp.go

    Lines 24 to 35 in aa3c352

    	func NewAddUserIDPLinkUniqueConstraint(idpConfigID, externalUserID string) *eventstore.UniqueConstraint {
    	return eventstore.NewAddEventUniqueConstraint(
    	UniqueUserIDPLinkType,
    	idpConfigID+externalUserID,
    	"Errors.User.ExternalIDP.AlreadyExists")
    	}
    	func NewRemoveUserIDPLinkUniqueConstraint(idpConfigID, externalUserID string) *eventstore.UniqueConstraint {
    	return eventstore.NewRemoveUniqueConstraint(
    	UniqueUserIDPLinkType,
    	idpConfigID+externalUserID)
    	}

• Login (by username):

  • Hosted login:
    The login can already be preselected for a specific organization (by id or primary domain). In both cases, the username will be checked in the organization context. This can be reused for the new setting as well:
    

    zitadel/internal/auth/repository/eventsourcing/eventstore/auth_request.go

    Lines 772 to 782 in 8f88c4c

    	if request.RequestedOrgID != "" {
    	if request.RequestedOrgDomain {
    	domainPolicy, err := repo.getDomainPolicy(ctx, request.RequestedOrgID)
    	if err != nil {
    	return err
    	}
    	if domainPolicy.UserLoginMustBeDomain {
    	preferredLoginName += "@" + request.RequestedPrimaryDomain
    	}
    	}
    	user, err = repo.checkLoginNameInputForResourceOwner(ctx, request, loginNameInput, preferredLoginName)

  • Session API: Can only handle global loginnames. In case of organization specific logins, the login UI will search for the user using the User API and can filter the organization. Afaik this is also already implemented to handle the OIDC organization scope.

• IdP (authentication):

  • Checking the existing idp link for a user (hosted login) already respects the organization context:

    zitadel/internal/auth/repository/eventsourcing/eventstore/auth_request.go

    Lines 1010 to 1017 in 8f88c4c

    	if request.RequestedOrgID != "" {
    	orgIDQuery, err := query.NewIDPUserLinksResourceOwnerSearchQuery(request.RequestedOrgID)
    	if err != nil {
    	return err
    	}
    	queries = append(queries, orgIDQuery)
    	}
    	links, err := repo.Query.IDPUserLinks(ctx, &query.IDPUserLinksSearchQuery{Queries: queries}, nil)

  • IdP intents would need to have an additional option to be limited to a single organization and then can handle the check on callback according to the hosted login UI.

[muhlemmer]

Question. Currently we do not enforce uniqueness of emails because we allow users with the same email to be created in multiple orgs. Once a users become unique within an org, should we also make sure the email is unique within that org?

Related support ticket (Zitadel staff only)

[hifabienne]

Question. Currently we do not enforce uniqueness of emails because we allow users with the same email to be created in multiple orgs. Once a users become unique within an org, should we also make sure the email is unique within that org?

Related support ticket (Zitadel staff only)

In an initial version I wouldn't as the email is still just a contact information to us, and we don't care if you use them multiple times.
If we want to allow customer to restrict that, i think they would also need to be able to configure that. (basically what was the idea of the userschema atttributes)