# Visible groups for Aperture

Last validated Jun 16, 2026

> **Note:** Visible groups for Aperture is currently in alpha.

\[Missing snippet: contact\_account\_manager.mdx]

Visible groups let Aperture resolve Tailscale group memberships so you can use `group:` identifiers in [grant `src` fields][kb-aperture-grants]. 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][kb-tailnet-policy-file] (for example, `group:engineering`).
* **SCIM groups**: [synchronized from your identity provider][kb-user-group-provisioning] (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][kb-node-attributes] 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][kb-group-visibility-clients].

## Prerequisites

Before you begin, ensure you have the following:

* An [Aperture instance][kb-get-started] 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][kb-tailnet-policy-file]. You need to be an [Owner, Admin, or Network admin](/docs/reference/user-roles/).
* (Optional) [SCIM groups][kb-user-group-provisioning] configured if you want to match identity provider groups.

## Configure the node attribute

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

1. Go to the [Access controls](https://login.tailscale.com/admin/acls/file) page of the admin console.
2. Add a `nodeAttrs` entry that targets your Aperture device and specifies which groups to expose.

```json
"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:

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

> **Note:**
>
> The tailnet policy file validation does not check whether the groups you list exist in your tailnet.

## 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.

\[Missing snippet: aperture\_grant\_dst\_note.mdx]

### Grant model access to a group

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

```json
{
  "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`:

```json
{
  "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 **Quota Usage** page (admin only) 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][kb-grant-model-access]: configure which models users and groups can access.
* [Set up admin access][kb-set-up-admin-access]: assign admin roles using groups.
* [Aperture configuration reference][kb-aperture-configuration]: full syntax for grants including `src` match patterns.
* [Group visibility on Tailscale clients][kb-group-visibility-clients]: platform-level details on how visible groups work.

[kb-aperture-configuration]: /docs/aperture/configuration

[kb-aperture-grants]: /docs/aperture/configuration#grants

[kb-get-started]: /docs/aperture/get-started

[kb-grant-model-access]: /docs/aperture/how-to/grant-model-access

[kb-group-visibility-clients]: /docs/features/group-visibility-clients

[kb-node-attributes]: /docs/reference/syntax/policy-file#nodeattrs

[kb-set-up-admin-access]: /docs/aperture/how-to/set-up-admin-access

[kb-tailnet-policy-file]: /docs/features/tailnet-policy-file

[kb-user-group-provisioning]: /docs/features/user-group-provisioning