Access Control Configuration

​

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 connection individually
• Changes take effect immediately

3

Click Activate

Click Activate to enable Access Control for your organization

​

Step 2: Configure Connections

1

Select a Connection

Find the connection in the list and click to configure

2

Enable Access Control

Toggle the Access Control switch for this connection

3

Add Allowed Groups

Select which groups can access this connection

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

​

Connection Visibility

​

Combining with Access Requests

​

Configuration Patterns

​

Pattern 1: Environment-Based

Connection: prod-database
  Allowed Groups: senior-engineers, dba

Connection: staging-database
  Allowed Groups: engineering, qa

Connection: dev-database
  Allowed Groups: engineering, contractors

​

Pattern 2: Team-Based

Connection: payments-db
  Allowed Groups: payments-team

Connection: inventory-db
  Allowed Groups: inventory-team

Connection: analytics-warehouse
  Allowed Groups: analytics-team, data-science

​

Pattern 3: Read/Write Separation

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

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

​

Pattern 4: Contractor Access

Connection: 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:
   Copy

   Ask AI

   IDP_GROUPS_CLAIM=groups
   
   Or for custom claim names:
   Copy

   Ask AI

   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 connection configurations

​

Access Logs

1. Go to Sessions
2. Filter by user or connection
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 Connection

1. Is Access Control enabled on the connection?
   • Go to connection 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 connection’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 Connection But Can’t Connect

1. Access Requests: Is JIT or Action approval required?
2. Guardrails: Are there blocking rules?
3. Connection 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 connections
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 connection 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