[Beta Support]: Support multiple role matches (permission merging) for Proxy Auth

[miguelangel-nubla]

Describe the problem you are having

First off, thanks for implementing the role_map! It has made integrating with OIDC providers much smoother.

However, I've encountered a friction point during testing: Frigate currently seems to handle only a single role match.

In real-world Identity Provider (IdP) setups, users often belong to multiple groups that might map to different roles within Frigate. A common scenario is an Administrator who is also part of a general "Users" or "Staff" group.

The Scenario:
Imagine the following config:

proxy:
  header_map:
    user: x-forwarded-user
    groups: x-forwarded-groups
    role_map:
      admin:
        - sysadmins          # Grants Admin role
      viewer: 
        - staff              # Grants Viewer role

If a user logs in with the groups ['sysadmins', 'staff'], they match both the admin and viewer mapping rules.

Current Behavior:
It appears Frigate picks one role (likely the first match or last match depending on iteration order) and ignores the others. If it happens to match viewer first, the Admin user is downgraded to a Viewer, despite having the credentials for Admin.

Desired Behavior:
Permissions should be additive (merged).
If a user matches multiple roles via the role_map, Frigate should grant the superset of all permissions associated with those roles.

In the example above:

• User matches admin -> Grants admin privileges.
• User matches viewer -> Grants viewer privileges.
• Result: User has Admin + Viewer (which effectively resolves to Admin).

Why this matters (Standard RBAC Pattern):
In most organization directories (LDAP/AD/Keycloak), group structures are often hierarchical or overlapping.

• It is difficult and brittle to force an IdP to ensure a user is in only one group at a time (e.g., removing a user from "Staff" just because they were promoted to "Sysadmin").
• Standard RBAC implementations (like Kubernetes, AWS IAM, or OAuth2 scopes) always calculate the "Effective Permissions" by taking the union of all policies attached to the user.

Suggested Solution
Modify the role_map logic to:

1. Iterate through all configured roles in the map.
2. Collect all roles where the user has a matching group.
3. Apply the merged permissions of those roles to the session.

If merging complex permissions is currently too difficult in the codebase, a simpler heuristic for now would be to prioritize the highest privilege role found (e.g., if admin is found among the matches, force admin).

Beta Version

0.17.0-rc1

Issue Category

Configuration / Setup

Frigate config file

NA

Relevant Frigate log output

NA

Relevant go2rtc log output (if applicable)

No response

Install method

Docker Compose

docker-compose file or Docker CLI command

NA

Operating system

Other

CPU / GPU / Hardware

No response

Screenshots

No response

Steps to reproduce

No response

Any other information that may be helpful

No response

[hawkeye217]

Glad you're able to use the new feature, and thanks for the discussion.

I understand what you’re getting at, but this doesn’t really align with how authorization is structured in Frigate today.

Frigate doesn’t implement a general RBAC system with composable or additive permissions. There are only two effective roles in Frigate today: admin and viewer, and they are coarse-grained gates around broad UI/API access. Outside of optionally limiting camera access when defining a custom viewer role, there isn’t any fine-grained permission model to merge or compose.

Because of that, the idea of calculating “effective permissions” from multiple matched roles doesn’t have much meaning here - there’s nothing granular to union together. A session ultimately resolves to a single role, not a set of capabilities.

The role_map exists purely as a convenience for mapping IdP group membership to one of those two roles. It’s expected that upstream identity configuration determines which group should grant elevated access. In practice that means:

• Ensure only the group intended to confer admin access maps to admin, or
• Adjust IdP group mappings/claims so role precedence is handled there

Frigate isn’t attempting to mirror Kubernetes/AWS-style RBAC semantics. Perhaps if more fine-grained permissions are implemented in the future, your request may have more relevance. At this point, if someone needs more complex policy handling, the recommended approach is to enforce it at the proxy/IdP layer and pass a single resolved role through to Frigate.

[miguelangel-nubla]

Thanks for the response. I want to clarify a few points to ensure we are aligned on the practical application of this feature.

1. Context on "K8s/AWS" References
To be clear, I am not asking for Frigate to implement a full-blown RBAC permission engine. I only referenced those projects because, in previous discussions, the maintainers specifically requested reference implementations for how other projects handle group mapping. I provided those as examples of mapping patterns, not as a request to copy their entire permission complexity.

2. The Goal of role_map
The suggestion to "enforce it at the proxy/IdP layer" contradicts the utility of this feature. The entire purpose of requesting role_map was to avoid brittle, custom scripting at the proxy level. If I have to write custom logic in an auth proxy to squash groups into a single role header, this feature becomes redundant. The goal is to take standard IdP outputs (which are lists of groups) and map them inside Frigate.

3. Critical Logic Issues
I understand and accept the design decision that a session resolves to a single role (Admin OR Viewer OR "Limited Viewer"). However, the current implementation has two logic flaws that make standard integration buggy:

A. Deterministic Priority (The "Downgrade" Bug)
In almost all IdP setups, a "Super User" will possess the groups of a "Base User" as well.

• Scenario: User has groups ['sysadmin', 'camera-viewer'].
• Config: sysadmin -> Admin, camera-viewer -> Viewer.
• Current Behavior: The user matches both. If Frigate iterates and matches camera-viewer first, the Admin user is logged in as a Viewer.
• Required Fix: Since we are limited to a single role, the resolution must be deterministic based on privilege. Admin mappings must always be evaluated/prioritized before Viewer mappings.

B. Group Intersection (AND vs OR)
Currently, the list of groups under a role functions as an OR condition (match any group).
To support existing IdP structures without creating custom "Frigate-specific" groups, the list in the original feature request was intended to function as an AND condition (match all groups listed).

• Use Case: I want to grant Admin only to users who are in both sysadmin AND access-level-security.
• Current State: I cannot do this without creating a new unique group in my IdP just for Frigate, which brings us back to the original problem.

Proposed "Middle Ground" Solution
We can keep the "Single Role" architecture while making it robust:

1. Prioritize Admin: Always check for Admin role matches first. If found, stop and assign Admin.
2. Strict Matching (AND): Treat the list of groups under a role key as requirements that must all be present. This allows granular targeting using existing broad groups.

This approach respects Frigate's simple permission model while fixing the "Admin downgrade" bug and allowing the flexibility role_map was intended to provide.

[hawkeye217]

That’s a fair perspective, but at some point we have to choose a simple, predictable behavior. role_map isn’t meant to evaluate identity policy, it’s just mapping identity provider group output to one of Frigate’s coarse roles.

OR semantics answer the straightforward question of “which groups grant this role?” and cover essentially all real-world setups without coupling unrelated claims or pushing intersection logic into Frigate config. Cases that need stricter targeting are better handled upstream where policy evaluation actually belongs.

I had a discussion with the other maintainers and always assigning admin if a role matches admin is reasonable and we will look to implement that in a future version. But switching lists to AND semantics is not something we plan to support.

This keeps role_map aligned with its intended scope rather than turning it into a policy engine.

[miguelangel-nubla]

I accept the decision to keep role_map simple and will defer complex logic to the upstream IdP/Proxy as suggested.

However I don't know what your "essentially all real-world setups" really are.

[hawkeye217]

This is improved in #21934

This may not make it into the final release of 0.17.0 - we'll have to see what other fixes come up and if we end up with another release candidate. If not, then it should be a part of 0.17.1.

[miguelangel-nubla]

This discussion highlights a significant gap in clarity regarding the project's long-term vision for authorization.

Could you please create/publish a high-level conceptual document outlining the long-term goals and non-goals for the permission/auth system?

You mentioned "Frigate isn't attempting to mirror K8s/AWS" and that roles are "coarse-grained gates." While that is helpful context here, it isn't documented anywhere central. Users (and contributors) need a clear, public definition of what "Coarse-Grained" actually means for Frigate's future to avoid repeated arguments about "real-world use cases" that might be completely different from person to person.

For example, without this document, we don't know if the following are planned features or hard "out of scope" design constraints:

Feature Granularity: Will we ever see permissions split by capability (e.g., a user who can watch but not trigger on-demand recordings?)

Data Granularity: Will permissions ever control metadata visibility (e.g., hiding face names for "Viewer" roles)?
If the answer to this questions is no, then it is all or nothing and will either show potential "sensible" face names to everyone, or unable to use this feature unless full admin in which case I can not limit the "neighbor" user to one camera?

Resource Granularity: Is the limit strictly "Access to Camera X," or will it go deeper?

Having a conceptual document that answers "What is the intended scope of Frigate's Auth?" with real use cases with config examples and expected behavior would save everyone time by setting correct expectations upfront and filtering out feature requests that fundamentally misalign with your architecture.

That document would also serve the purpose to be a working ground where to discuss, before moving to the code/actual behavior like we are doing right now.

I have been using Frigate for a long time, read the docs and the code, discussed feature requests with you etc but I am still unable to wrap my head around your intentions, and so feel I am wasting more time creating understandings back and forth between us than actually improving Frigate.

[blakeblackshear]

We don't have any preconceived plans for how far auth will go in the future. We do not currently have any plans to extend into more fine grained permissions management with custom roles assigned to custom sets of permissions. We certainly could, but it seems like a feature that would be useful to such a small number of users that other things will take priority for the foreseeable future. For now, we have no plans to extend auth beyond the functionality available in this release.