[Feature request]: Fleet filtering feature for multi-tenant deployments

[asrafhamid]

Before proceeding, is there an existing issue or discussion for this?

• I have done a search for similar issues and discussions.

Description

Hi team,

Following up on our conversation in the community forum. We are developing a fleet filtering feature for deployments where a single RMF instance serves multiple departments, each with their own robot fleet. I wanted to open this issue so @aaronchongth on can follow up as discussed.

What we are building

We are making changes across three areas:

• Keycloak : group and role configuration to carry fleet and permission identity in the JWT, including a fleet claim via a Group Attribute Mapper
• Backend (api-server) : fleet-aware filtering on existing endpoints and new fleet-specific endpoints, enforced using claims from the JWT. A role-to-permission mapping is also added to translates a user's role claim into a set of allowed actions, which is then checked at the route level before any data is returned.
• Frontend (dashboard) : UI changes to reflect the filtered data and allow fleet selection where applicable

How fleet identity is carried

Fleet membership is communicated via a fleet claim in the JWT. On each request, the backend reads this claim to determine what data gets returned to the user.

For role-based permission separation within a department (e.g. regular user vs supervisor), we are currently using a role claim approach via existing Keycloak realm roles. Would a permissions claim embedded directly in the JWT be a better fit with the existing RMF auth model? Would appreciate some opinion on this :)

Concerns about pushing upstream

1. Keycloak dependency : the current approach assumes the fleet claim is present in the JWT. Deployments not configured with fleet claims would receive empty results or 403 errors on affected endpoints. This needs to be made opt-in so existing deployments are unaffected.
2. Modifications to existing endpoints : the fleet filtering touches existing endpoints, not only new ones. Without an opt-in guard, upgrading deployments would be affected.

Implementation Considerations

No response

Alternatives

No response

Additional information

No response

[aaronchongth]

Hey @asrafhamid , thanks for highlighting this feature and its details. The simplest option I can think of now, would be to set it up as a feature flag that can be toggled in the API server config, https://github.com/open-rmf/rmf-web/blob/main/packages%2Fapi-server%2Fapi_server%2Fdefault_config.py

Depending on how widely used this method of authorization will be, how extensible it will be, we can consider abstracting the authorization mechanism to be added to all endpoints, with proper base classes that help people implement their own authorization logic. This base class can then be used for implement this fleet based autorization as a first-class example of how it can be done. What do you think?

[aaronchongth]

It would be great if we can add this feature with more extensions in mind, for example #395

[asrafhamid]

Hey @aaronchongth, thanks for the feedback!

The feature flag is done (on our end), there's a fleet_filtering toggle in the server config that defaults to false, so existing deployments are unaffected.

On the base class abstraction, I think this is the right direction, especially with #395 in mind. Before proposing the interface, I want to be upfront about one design choice: our implementation bypasses the ResourcePermission DB table entirely and reads fleet membership directly from the JWT claims. The reason is a deployment constraint, if a staff member's role changes from nurse to supervisor, updating Keycloak alone should be sufficient for their permissions in RMF to reflect that immediately without an admin also having to update rows in the RMF DB.

That said, I don't think this should replace the existing DB-backed approach, just sit alongside it. So the interface I'm proposing keeps authz_grp to stay backward compatible with existing callers of Enforcer:

class BaseAuthorizer(ABC):
    @abstractmethod
    async def is_authorized(self, user: User, authz_grp: str, action: str) -> bool:
        """Can this user perform this action on this resource group?"""
        ...

    @abstractmethod
    def get_accessible_groups(self, user: User) -> list[str] | None:
        """Which resource groups can this user see?
        None = no restriction (default for non-fleet deployments)
        []   = no access
        ["linen_fleet", "cssd_fleet"] = scoped access
        """
        ...

Two concrete implementations would ship with it:

• DbRoleAuthorizer: wraps the existing Enforcer, uses ResourcePermission table, default for simple deployments, no behaviour change

• JwtFleetAuthorizer: reads fleet membership from JWT claims, maps roles to actions via server config, no DB writes needed

The get_accessible_groups() method is what I think closes #395, it's the missing "which resources should this user see?" API that authz_grp alone can't answer, since authz_grp goes from resource to user while visibility filtering needs to go from user to resource.

What do you think of this direction?

[aaronchongth]

Thanks for explaining the approach, this looks good to me so far, I don't see any other architectural blockers for this proposed feature.

We have so far not had time to properly carve out authorization and permissions throughout the entire dashboard to fully utilize ResourcePermission as planned, therefore this approach via JWT is very much a welcome stopgap for existing deployments.