Visible groups for Aperture

Visible groups let Aperture resolve Tailscale group memberships so you can use group: identifiers in grant src fields. Without visible groups, Aperture can only match individual login names (alice@example.com) and tagged devices (tag:ci-runner). With visible groups enabled, you can grant model access or admin roles to entire teams.

Aperture supports two kinds of groups:

• Tailscale groups: defined in your tailnet policy file (for example, group:engineering).
• SCIM groups: synchronized from your identity provider (for example, group:sales@example.com or matched by email like engineering@example.com).

How it works

By default, the Tailscale control plane does not send group membership information to devices. To make groups available to Aperture, you add a tailscale.com/visible-groups node attribute to your tailnet policy file targeting the Aperture device. After it's configured, the Aperture device receives group membership data for connecting users, and Aperture can evaluate group: entries in grant src fields.

For a detailed explanation of how visible groups work at the Tailscale platform level, refer to group visibility on Tailscale clients.

Prerequisites

Before you begin, ensure you have the following:

• An Aperture instance with at least one configured provider.
• The nodeattr-visible-groups feature flag enabled for your tailnet. Contact your account manager or email aperture@tailscale.com to enable it.
• Permission to edit your tailnet policy file. You need to be an Owner, Admin, or Network admin.
• (Optional) SCIM groups configured if you want to match identity provider groups.

Configure the node attribute

Add a tailscale.com/visible-groups node attribute to your tailnet policy file. This tells the control plane which groups are visible to the Aperture device.

1. Go to the Access controls page of the admin console.
2. Add a nodeAttrs entry that targets your Aperture device and specifies which groups to expose.

"nodeAttrs": [
  {
    "target": ["tag:aperture"],
    "app": {
      "tailscale.com/visible-groups": [
        {
          "groups": ["*"]
        }
      ]
    }
  }
]

The "groups": ["*"] wildcard makes all groups visible to the Aperture device. To restrict visibility to specific groups, list them explicitly:

"groups": [
  "group:engineering",
  "group:ai-users",
  "group:sales@example.com"
]

Use groups in Aperture grants

After configuring the node attribute, you can use group: identifiers in grant src fields. Aperture evaluates group membership at request time using the identity of the connecting user.

Grant model access to a group

The following example grants members of group:ai-users access to all Anthropic models:

{
  "grants": [
    {
      "src": ["group:ai-users"],
      "app": {
        "tailscale.com/cap/aperture": [
          { "role": "user" },
          { "models": "anthropic/**" }
        ]
      }
    }
  ]
}

Grant admin access to a group

The following example grants admin access to members of group:aperture-admins and standard user access to members of group:ai-users:

{
  "grants": [
    {
      "src": ["group:aperture-admins"],
      "app": {
        "tailscale.com/cap/aperture": [
          { "role": "admin" }
        ]
      }
    },
    {
      "src": ["group:ai-users"],
      "app": {
        "tailscale.com/cap/aperture": [
          { "role": "user" }
        ]
      }
    }
  ]
}

If a user matches both grants, the highest-permissioned role (admin) wins.

Match SCIM groups

You can match SCIM groups using either the group: prefix or the group email directly:

• "group:sales@example.com": matches members of the SCIM group with that email.
• "sales@example.com": also matches SCIM group members by email.

Both formats work in grant src fields.

Verify group visibility

To confirm group memberships are visible to the Aperture device, check the Quotas page of the Aperture dashboard. Check to make sure the quotas granted to groups are reflected for the users of those groups.

Next steps

• Grant model access: configure which models users and groups can access.
• Set up admin access: assign admin roles using groups.
• Aperture configuration reference: full syntax for grants including src match patterns.
• Group visibility on Tailscale clients: platform-level details on how visible groups work.