> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/p0-management/group-based-access-control.md).

# Group-based access control

Group-based access control lets you grant P0 roles to entire identity-provider groups instead of adding users one at a time. When you map a group to a role, anyone who signs in and belongs to that group receives the role automatically. Remove someone from the group in your identity provider and they lose the role the next time they sign in.

You can grant any P0 role to a group:

* **Owners**
* **Security Reviewers**
* **Assessment Users**
* **Assessment Viewers**

For a description of what each role can do, see [Role-based access control](/p0-management/role-based-access-control.md).

## How it works

P0 reads group membership from the `groups` claim in the ID token it receives when you sign in through OpenID Connect (OIDC) single sign-on (SSO). Your identity provider populates this claim with the names of the groups the signed-in user belongs to. P0 then grants each mapped role to every user whose token carries the matching group name.

Because this relies on the identity provider sending a `groups` claim, group-based access control works with Okta and with other OIDC identity providers that can emit a groups claim.

{% hint style="warning" %}
Google Workspace sign-in does not send group claims in the ID token, so group-based access control is not available when you sign in with Google Workspace. Use Okta (or another OIDC provider that emits a groups claim) for this feature.
{% endhint %}

## Prerequisites

Before you configure group-based access control, make sure you have:

* Administrative access to the P0 app as an **Owner**.
* Administrative access to your Okta org, with permission to edit the OIDC application used for P0 sign-in (Super Administrator or Application Administrator).
* Users who sign in to P0 through Okta OIDC SSO.

## Step 1: Send a groups claim from Okta

Configure your Okta OIDC application to include a claim named exactly `groups` (lowercase) in the ID token. The claim must contain an array of the group names the user belongs to.

The exact location depends on which authorization server your Okta application uses.

### Find which authorization server your app uses

1. In the Okta Admin Console, go to **Applications** and open the OIDC application used for P0 sign-in.
2. Open the **Sign On** tab and find the **OpenID Connect ID Token** section:
   * If this section has a **Groups claim** setting, your app uses Okta's built-in **org authorization server**. Follow [Standard case](#standard-case-org-authorization-server).
   * If the app uses a **custom authorization server** (the issuer is an authorization server you created, not the org default), the groups claim is managed on that authorization server. Follow [Custom authorization server case](#custom-authorization-server-case).

### Standard case: org authorization server

1. On the application's **Sign On** tab, click **Edit** in the **OpenID Connect ID Token** section.

<figure><img src="/files/LWKzJMnonib4hZCCsf52" alt="" width="558"><figcaption></figcaption></figure>

2. Under **Groups claim**, set the claim name to `groups`.
3. Choose a **filter** that selects which groups Okta sends:

   * To send every group the user belongs to, select **Matches regex** and enter `.*`.
   * To scope the claim to specific groups, use a narrower filter (for example, **Starts with** `p0-`).

   <figure><img src="/files/H7t7sLC4z03FfVWumLMX" alt="" width="554"><figcaption></figcaption></figure>
4. Click **Save**.

### Custom authorization server case

If your application authenticates against a custom authorization server, add the claim on that authorization server:

1. In the Okta Admin Console, go to **Security** > **API** > **Authorization Servers**.
2. Select the authorization server your application uses.
3. Open the **Claims** tab and click **Add Claim**.
4. Configure the claim:
   * **Name:** `groups`
   * **Include in token type:** **ID Token**
   * **Value type:** **Groups**
   * **Filter:** choose a filter that selects the groups to send (for example, **Matches regex** `.*` for all groups, or a narrower filter to scope it).
5. Click **Create**.
6. Confirm that the P0 sign-in application uses this authorization server. If it isn't, the claim isn't included in the token.

{% hint style="info" %}
Okta sends group **names** as the values in the `groups` claim. Note the exact names of the groups you plan to map. You enter these same names in P0 in the next step, and they must match exactly.
{% endhint %}

## Step 2: Map groups to roles in P0

1. Sign out of P0 and sign back in so your session carries a fresh token that includes the new `groups` claim. The **Groups** field doesn't appear until your session includes a groups claim.
2. In the [P0 app](https://p0.app), go to **P0 Management** > **Access control**.

<figure><img src="/files/IYhBHOjrtLp2UEkWh0kU" alt="" width="542"><figcaption></figcaption></figure>

3. Find the role you want to grant (for example, **Security Reviewers**).
4. In the **Groups** field under that role, enter the Okta group name (case sensitive) and press **Enter**.
5. Add any more group names for that role, and repeat for other roles as needed.

Each group name you enter must match exactly what Okta sends in the `groups` claim. Members of a mapped group receive the role the next time they sign in.

## Verify the configuration

1. Ask a member of a mapped group to s**ign out of P0 and sign back in through Okta**.
2. Confirm that the user can perform the actions the mapped role allows.
3. If the user doesn't receive the expected access, see [Troubleshooting](#troubleshooting).

## Troubleshooting

### The Groups field doesn't appear

The **Groups** field appears only when your current session already carries a `groups` claim. If it's missing:

* Confirm that Okta sends a claim named exactly `groups` (lowercase) in the **ID token**, not the access token, and not a claim with a different name.
* Sign out of P0 and sign back in. Configuration changes in Okta take effect only in a new token, so you must re-authenticate after editing the claim.
* If you use a custom authorization server, confirm that the P0 sign-in application points to that authorization server.

### Group members do not receive the role

* Check that the group name in the P0 **Groups** field matches the name Okta sends exactly. Names are case-sensitive, so `Engineering` and `engineering` are treated as different groups.
* Confirm the affected users have signed out and signed back in since you mapped the group. Access updates only when the user gets a new token.
* Confirm the users are members of the group in Okta and that your groups claim filter includes that group.

### A group grants access under one login but not another

Group access depends on the sign-in provider used to authenticate. A group you add while signing in with one provider doesn't grant access when a user signs in with a different provider. Add the group under the provider your users actually sign in with.

## Related topics

* [Role-based access control](/p0-management/role-based-access-control.md)
* [Okta integration](/integrations/directory-integrations/okta.md)