Skip to main content
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.
For an introduction to Access Control concepts, see Access Control Overview.

​
Enabling Access Control

Access Control restricts resource roles to the groups you assign. Plan your group assignments so users who need access aren’t unintentionally locked out.
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:
1

Set group information

Enter a Name to identify the group (for example, engineering-team).
2

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

Attribute configuration

Under Attributes, select which attributes this group should have access to. See ABAC for how attributes refine access.
4

Save

Click Save to create the group and apply the configuration.

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

​
Built-in Groups

GroupDescriptionPermissions
adminAdministratorsFull access to all resource roles and settings
auditorAudit accessRead-only access to sessions and logs
Admin users bypass Access Control and can access all resource roles regardless of group configuration.

​
Group Naming Conventions

Recommended naming patterns:
PatternExampleUse Case
Environmentprod-access, staging-accessEnvironment-based access
Teamengineering, analytics, supportTeam-based access
Roledba, developer, viewerRole-based access
Combinedprod-dba, staging-devSpecific combinations

​
Permission Types

​
Resource Role Visibility

When Access Control is enabled on a resource role:
User’s GroupsResource Role Visibility
In allowed groupsResource role is visible and accessible
Not in allowed groupsResource role is hidden completely
Admin groupAlways visible (bypasses Access Control)

​
Combining with Access Requests

Access Control and Access Requests work together:
Access ControlAccess RequestsResult
AllowedNot enabledDirect access
AllowedJIT enabledMust request time-based access
AllowedAction enabledEach command needs approval
Not allowedAnyResource 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: 
    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

Okta

Configure Okta group sync

Auth0

Configure Auth0 group sync

Azure AD

Configure Azure AD group sync

Google

Configure Google Workspace groups

​
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: 
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: 
# 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

Start Restrictive

Begin with minimal access and expand as needed

Use Groups, Not Users

Always assign access to groups, never individuals

Document Policies

Maintain a document of who should access what

Regular Reviews

Audit access quarterly

​
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

Access Control Overview

Learn Access Control concepts

Identity Providers

Configure SSO and group sync

Access Requests

Add approval workflows

Managing Access

User and group management in Web App