Add foundation module for BSO seat check

Paulo Barrosrequested to merge
pb/513219/bso-for-external-protocols-foundation into master

This is part of #513219+.

What does this MR do and why?

This MR introduces a foundation module for handling Block Seat Overages (BSO) with external user provisioning protocols.

Problem: When BSO is enabled and seat limits are reached, external protocols (SCIM, LDAP, SAML) bypass BSO checks by calling Group#add_member directly, causing unexpected seat overages.

Solution: This module provides a adjust_access_level_for_seat_availability method that external protocols can use to check seat availability before provisioning users. When seats aren't available, it returns Gitlab::Access::MINIMAL_ACCESS instead of the requested access level, preventing billing overages while maintaining automated provisioning workflows.

Usage: External protocol services will call this method before adding members:

# Instead of:
group.add_member(user, Gitlab::Access::DEVELOPER)

# Services will do something like:
adjusted_level = adjust_access_level_for_seat_availability(group, user, Gitlab::Access::DEVELOPER)
group.add_member(user, adjusted_level)

This MR only adds the foundation module. Integration with SCIM, LDAP, and SAML services will follow in separate MRs.

References

Screenshots or screen recordings

N/A

How to set up and validate locally

The code introduced here is unused. Passing tests are enough validation.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Paulo Barros

Merge request reports