> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Control Configuration

> Configure group-based access policies for your resource roles

Access Control lets you restrict which users can see and access specific resource roles based on their group memberships. This page covers detailed configuration options.

<Note>
  For an introduction to Access Control concepts, see [Access Control Overview](/learn/features/access-control).
</Note>

***

## Enabling Access Control

<Warning>
  Access Control restricts resource roles to the groups you assign. Plan your group assignments so users who need access aren't unintentionally locked out.
</Warning>

Access Control is configured by creating **access control groups**. Each group has a name, the resource roles it can access, and the attributes it applies to. You can either create these groups directly in the Web App or sync them from your identity provider.

### Step 1: Open Access Control

In the Web App, open the **Discover** section in the sidebar and select **Access Control**.

### Step 2: Create an Access Control Group

Click to create a new access control group and fill in:

<Steps>
  <Step title="Set group information">
    Enter a **Name** to identify the group (for example, `engineering-team`).
  </Step>

  <Step title="Resource Role configuration">
    Under **Resource Roles**, select which resource roles this group should have access to. You can add as many resource roles to a group as you need.
  </Step>

  <Step title="Attribute configuration">
    Under **Attributes**, select which attributes this group should have access to. See [ABAC](/learn/features/abac) for how attributes refine access.
  </Step>

  <Step title="Save">
    Click **Save** to create the group and apply the configuration.
  </Step>
</Steps>

### Step 3: Verify Access

After creating a group, confirm the policy behaves as expected:

1. Log in as a user in the group
2. Verify you can see and access the assigned resource roles
3. Log in as a user **not** in the group
4. Verify those resource roles are not visible

***

## Group Management

### Creating Groups

Groups can be created in two ways:

**Option A: In the Web App**

Create access control groups directly in **Discover > Access Control**, as described in [Enabling Access Control](#enabling-access-control). Each group defines its name, the resource roles it can access, and its attributes.

**Option B: Sync from Identity Provider**

Groups can be automatically synced when users log in:

1. Configure your IdP to include `groups` claim in the ID token
2. Users' groups are synced on each login
3. See [Identity Provider Configuration](/setup/configuration/idp/get-started)

### Built-in Groups

| Group     | Description    | Permissions                                    |
| --------- | -------------- | ---------------------------------------------- |
| `admin`   | Administrators | Full access to all resource roles and settings |
| `auditor` | Audit access   | Read-only access to sessions and logs          |

<Note>
  Admin users bypass Access Control and can access all resource roles regardless of group configuration.
</Note>

### Group Naming Conventions

Recommended naming patterns:

| Pattern     | Example                               | Use Case                 |
| ----------- | ------------------------------------- | ------------------------ |
| Environment | `prod-access`, `staging-access`       | Environment-based access |
| Team        | `engineering`, `analytics`, `support` | Team-based access        |
| Role        | `dba`, `developer`, `viewer`          | Role-based access        |
| Combined    | `prod-dba`, `staging-dev`             | Specific combinations    |

***

## Permission Types

### Resource Role Visibility

When Access Control is enabled on a resource role:

| User's Groups         | Resource Role Visibility                 |
| --------------------- | ---------------------------------------- |
| In allowed groups     | Resource role is visible and accessible  |
| Not in allowed groups | Resource role is hidden completely       |
| Admin group           | Always visible (bypasses Access Control) |

### Combining with Access Requests

Access Control and Access Requests work together:

| Access Control | Access Requests | Result                         |
| -------------- | --------------- | ------------------------------ |
| Allowed        | Not enabled     | Direct access                  |
| Allowed        | JIT enabled     | Must request time-based access |
| Allowed        | Action enabled  | Each command needs approval    |
| Not allowed    | Any             | Resource role not visible      |

***

## Configuration Patterns

### Pattern 1: Environment-Based

Separate access by environment:

```
Resource Role: prod-database
  Allowed Groups: senior-engineers, dba

Resource Role: staging-database
  Allowed Groups: engineering, qa

Resource Role: dev-database
  Allowed Groups: engineering, contractors
```

### Pattern 2: Team-Based

Each team accesses their own resources:

```
Resource Role: payments-db
  Allowed Groups: payments-team

Resource Role: inventory-db
  Allowed Groups: inventory-team

Resource Role: analytics-warehouse
  Allowed Groups: analytics-team, data-science
```

### Pattern 3: Read/Write Separation

Create separate resource roles with different access levels:

```
Resource Role: prod-db-readonly
  Allowed Groups: engineering, analytics, support
  (Configured with read-only database user)

Resource Role: prod-db-readwrite
  Allowed Groups: dba, senior-engineers
  (Configured with read-write database user)
```

### Pattern 4: Contractor Access

Limited access for external contractors:

```
Resource Role: contractor-db
  Allowed Groups: contractors
  (Limited database, Live Data Masking enabled)
```

***

## Identity Provider Integration

### Syncing Groups from IdP

To automatically sync groups from your identity provider:

1. **Configure IdP to include groups claim:**

   In your IdP (Okta, Auth0, Azure AD, etc.), configure the OIDC application to include a `groups` claim in the ID token.

2. **Set environment variables on gateway:**

   ```bash theme={"dark"}
   IDP_GROUPS_CLAIM=groups
   ```

   Or for custom claim names:

   ```bash theme={"dark"}
   IDP_GROUPS_CLAIM=https://mycompany.com/groups
   ```

3. **Groups sync on login:**

   When users log in, their groups are automatically synced from the IdP.

### Provider-Specific Guides

<CardGroup cols={2}>
  <Card title="Okta" href="/setup/configuration/idp/okta">
    Configure Okta group sync
  </Card>

  <Card title="Auth0" href="/setup/configuration/idp/auth0">
    Configure Auth0 group sync
  </Card>

  <Card title="Azure AD" href="/setup/configuration/idp/azure">
    Configure Azure AD group sync
  </Card>

  <Card title="Google" href="/setup/configuration/idp/google">
    Configure Google Workspace groups
  </Card>
</CardGroup>

***

## Auditing Access

### Viewing User Permissions

To see what a user can access:

1. Go to **Manage > Users**
2. Click on a user
3. View their group memberships
4. Cross-reference with resource role configurations

### Access Logs

All access attempts are logged:

1. Go to **Sessions**
2. Filter by user or resource role
3. See successful connections and denied attempts

### Exporting Access Report

Generate a report of who can access what:

```bash theme={"dark"}
hoop admin get connections -o json | \
  jq '.[] | {name, allowed_groups}'
```

***

## Troubleshooting

### User Can't See a Resource Role

**Checklist:**

1. **Is Access Control enabled on the resource role?**
   * Go to resource role settings
   * Check if Access Control toggle is on

2. **Is the user in an allowed group?**
   * Go to **Manage > Users**
   * Check user's group memberships
   * Verify groups match resource role's allowed groups

3. **Has the user logged out and back in?**
   * Groups sync on login
   * Have user log out and log in again

4. **Is the IdP sending groups correctly?**
   * Check IdP configuration
   * Verify `groups` claim in ID token

**Debug steps:**

```bash theme={"dark"}
# Check user's groups
hoop admin get user <email>

# Check connection's allowed groups
hoop admin get connection <name>
```

### User Sees Resource Role But Can't Connect

This is likely NOT an Access Control issue. Check:

1. **Access Requests:** Is JIT or Action approval required?
2. **Guardrails:** Are there blocking rules?
3. **Resource role status:** Is the agent online?

### Groups Not Syncing from IdP

**Check:**

1. IdP is configured to include `groups` claim
2. `IDP_GROUPS_CLAIM` environment variable is set correctly
3. User has groups assigned in the IdP
4. Gateway was restarted after configuration

**Debug:**

* Decode the ID token to verify `groups` claim is present
* Check gateway logs for group sync errors

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Start Restrictive" icon="lock">
    Begin with minimal access and expand as needed
  </Card>

  <Card title="Use Groups, Not Users" icon="users">
    Always assign access to groups, never individuals
  </Card>

  <Card title="Document Policies" icon="file-lines">
    Maintain a document of who should access what
  </Card>

  <Card title="Regular Reviews" icon="calendar-check">
    Audit access quarterly
  </Card>
</CardGroup>

### Before Enabling Access Control

1. Inventory all resource roles
2. Identify who needs access to each
3. Create groups in IdP or Hoop
4. Assign users to groups
5. Document the access policy
6. Test with a non-production resource role first

### Quarterly Access Review

1. Export current access configuration
2. Review with team leads
3. Remove departed employees
4. Verify contractor access is time-limited
5. Update documentation

***

## Related

<CardGroup cols={2}>
  <Card title="Access Control Overview" icon="lock" href="/learn/features/access-control">
    Learn Access Control concepts
  </Card>

  <Card title="Identity Providers" icon="id-card" href="/setup/configuration/idp/get-started">
    Configure SSO and group sync
  </Card>

  <Card title="Access Requests" icon="clock" href="/learn/features/access-requests/jit">
    Add approval workflows
  </Card>

  <Card title="Managing Access" icon="users" href="/clients/webapp/managing-access">
    User and group management in Web App
  </Card>
</CardGroup>