Manage Groups & Access Control

How to manage groups for group-based access control in Wiretastix -- create, list, update, and delete group policies.

Groups are Wiretastix’s group-based access control mechanism: they let you apply shared configuration (allowed IPs, DNS, search domain, max devices) and firewall rules to a set of users at once.

Membership Comes From OIDC, Not the CLI

Group membership itself comes from your OIDC provider’s group claims at login time – there is no CLI command to manually add or remove a specific user from a group. A group in Wiretastix is really a policy target keyed to an OIDC group claim value (its oidc field); whoever’s claims include that value is a member, automatically, the next time they sign in. See OIDC Integration for how claims map to groups.

Group commands take plain key/value pairs as arguments, not --flags. The oidc key (the group name/claim value as it appears in your IdP) and policy are both required; everything else is optional.

The default_group Fallback Needs an Actual Group to Exist

If a user’s OIDC claims don’t match any of your configured groups, Wiretastix falls back to the group named by the default_group global setting (see Configuring Global Defaults) – but only if a group with that exact oidc name actually exists and is enabled. A fresh install ships default_group pre-set to the string fallback, but does not create a group named fallback for you – until you do, that setting points at nothing.

The practical consequence: a user who doesn’t match any real group, on a system where default_group is unset or points at a group that doesn’t exist, cannot get a group assigned at all, and their self-service tunnel creation fails outright (surfaced as a generic “not found” error in the web UI) – not just “no group-level settings applied.” If you expect any users to fall through to a catch-all rather than always matching a specific OIDC group, create that group first:

> group create oidc fallback name "Fallback" policy accept

Whichever policy you give this group is exactly what applies to anyone who lands in it – including a user who used to match a real group but no longer does. Group membership re-syncs on every successful token refresh, not just at login (see OIDC Integration), so if someone drops out of their assigned group at the IdP, they fall into default_group and start getting its policy applied on their next refresh cycle – promptly, not just the next time they sign in. A default_group created with policy drop (or restrictive rules) is therefore a reasonable way to make sure anyone who falls out of a real group loses network access quickly rather than keeping whatever access their old group granted until they happen to log out and back in.

(or point default_group at whatever group name you actually want to serve that role, and make sure it’s enabled).

Group Policy Is Required, and It’s a Real Catch-All

policy (accept, drop, or none) is enforced as the group’s fallback for any traffic its own network rules don’t match – it isn’t just a label. A group created with policy drop and zero rules yet blocks all traffic for its members immediately, from the moment it’s created; a policy accept group with no rules allows everything. Neither is a no-op. policy none makes no catch-all statement at all, letting unmatched traffic fall through. See NFTables Integration for exactly how this is enforced.

Because of this, group create rejects an empty or missing policy – there’s no default.

Priority Decides Which Group Wins When a Peer Is in More Than One

A user’s OIDC claims can match multiple groups at once. When they do, prio (lower number = evaluated first) decides which group’s policy gets the final say: the first group in priority order whose policy is accept or drop wins, and groups after it never get a chance to decide for that peer’s traffic. policy none defers instead of deciding, so evaluation continues to the next group. Two groups left at the same priority have no defined tie-break – set distinct priorities if the outcome between overlapping groups matters. See NFTables Integration for the full mechanics.

Create a Group

wiretastix-cli
> group create oidc developers name Developers prio 10 policy drop

To also set default allowed-ips, dns, or search-domain values that peers in this group inherit:

> group create oidc marketing policy drop allowed-ips 192.168.1.0/24 dns 1.1.1.1

List Groups

> group list

Get Group Details

Use group show with the group’s OIDC name:

> group show developers

Update a Group

> group update marketing dns 8.8.8.8

Enable or Disable a Group

> group disable marketing
> group enable marketing

Delete a Group

> group delete developers

Note: Deleting a group does not delete the users or peers that were associated with it, but they will no longer inherit configuration or rules from that group.

Next Steps

To manage the individual users who fall into these groups, see Manage Users. To apply firewall rules per group, see Configure Network Rules.