Access Control Configuration

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.

​

Enabling Access Control

​

Step 1: Activate Access Control

1

Navigate to Access Control

Go to Manage > Access Control in the sidebar

2

Review the Warning

Read the activation warning carefully. Understand that:

• Users without group assignments will lose access
• You’ll need to configure each resource role individually
• Changes take effect immediately

3

Click Activate

Click Activate to enable Access Control for your organization

​

Step 2: Configure Resource Roles

1

Select a Resource Role

Find the resource role in the list and click to configure

2

Enable Access Control

Toggle the Access Control switch for this resource role

3

Add Allowed Groups

Select which groups can access this resource role

4

Save

Click Save to apply the configuration

​

Group Management

​

Creating Groups

1. Go to Manage > Users & Groups
2. Click the Groups tab
3. Click Create Group
4. Enter a group name (e.g., prod-access, analytics-team)
5. Add users to the group

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

​

Built-in Groups

​

Group Naming Conventions

​

Permission Types

​

Resource Role Visibility

​

Combining with Access Requests

​

Configuration Patterns

​

Pattern 1: Environment-Based

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

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

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

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

​

Identity Provider Integration

​

Syncing Groups from IdP

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:
   IDP_GROUPS_CLAIM=groups
   
   Or for custom claim names:
   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

​

Auditing Access

​

Viewing User Permissions

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

​

Access Logs

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

​

Exporting Access Report

hoop admin get connections -o json | \
  jq '.[] | {name, allowed_groups}'

​

Troubleshooting

​

User Can’t See a Resource Role

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

# 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

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

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

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

​

Best Practices

​

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