We support a variety of Identity Providers to authenticate users in hoop.dev. Integration uses the OIDC (OpenID Connect) or SAML 2.0 protocols. Any OIDC-compliant identity provider should work; the guides below cover providers that have been validated.
Users
Users are active and assigned to the default organization when they sign up. A user can be set to an inactive state to prevent access, however it is recommended to manage user state in the identity provider rather than in hoop.dev.
- The
sub claim is used as the main identifier of the user in the platform.
- The user’s profile is derived from the
email and name claims in the ID token.
When a user authenticates for the first time, hoop.dev performs an automatic signup that persists the profile claims along with their unique identifier.
Groups
Groups control who may access or interact with certain resources.
- For connection resources, groups define which users have access to a connection. This is enforced when the Access Control feature is enabled.
- For access requests, groups define which users are allowed to approve an execution. This is enforced when the Access Requests feature is enabled.
Groups can be managed manually via the Webapp, or propagated automatically by the identity provider via the ID token. When propagated by the IdP, groups are synced each time a user signs in.
Roles
- The admin group grants full access to all resources. Assign this to users responsible for managing the Gateway.
- The auditor group grants read-only access to session resources.
- All other users are regular users who can access their own resources and interact with connections.
The default role names (admin and auditor) can be changed to match the group names in your identity provider via Integrations > Authentication in the Webapp, or via the admin_role_name / auditor_role_name fields in the API.
Role name changes take effect on the next sign-in. If you change the admin role name and no user belonging to the new group has signed in yet, you may lose admin access. Update the role name before removing yourself from the previous admin group.
Configuration
Configuring the identity provider via the Webapp or API is available beginning with version 1.38.12.
Go to Integrations > Authentication to configure the identity provider.After saving, the identity provider reloads automatically with the new settings. Any IDP_* environment variables will be ignored once a configuration is saved here.
Use PUT {API_URL}/api/serverconfig/auth authenticated with an admin Api-Key header.OIDC / OAuth 2.0
| Field | Required | Description |
|---|
auth_method | yes | Set to "oidc" |
oidc_config.issuer_url | yes | The provider’s OIDC discovery base URL |
oidc_config.client_id | yes | OAuth2 client ID |
oidc_config.client_secret | yes | OAuth2 client secret |
oidc_config.scopes | no | Additional scopes to request. Defaults are openid, profile, and email |
oidc_config.audience | no | OAuth2 audience. Required for providers that return opaque access tokens by default (e.g. Auth0) |
oidc_config.groups_claim | no | ID token claim used to read group membership. Default: groups |
admin_role_name | no | Group name mapped to the admin role. Default: admin |
auditor_role_name | no | Group name mapped to the auditor role. Default: auditor |
webapp_users_management_status | yes | "active" enables user management in the Webapp; "inactive" disables it |
curl -X PUT {API_URL}/api/serverconfig/auth \
-H "Api-Key: {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"auth_method": "oidc",
"oidc_config": {
"issuer_url": "https://your-idp.example.com",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"groups_claim": "groups"
},
"webapp_users_management_status": "active",
"admin_role_name": "admin",
"auditor_role_name": "auditor"
}'
SAML 2.0
| Field | Required | Description |
|---|
auth_method | yes | Set to "saml" |
saml_config.idp_metadata_url | yes | URL to the IdP’s SAML metadata XML |
saml_config.groups_claim | no | SAML assertion attribute used to read group membership. Default: groups |
webapp_users_management_status | yes | "active" or "inactive" |
curl -X PUT {API_URL}/api/serverconfig/auth \
-H "Api-Key: {API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"auth_method": "saml",
"saml_config": {
"idp_metadata_url": "https://your-idp.example.com/saml/metadata",
"groups_claim": "groups"
},
"webapp_users_management_status": "active"
}'
| Endpoint | Value |
|---|
| ACS URL / Callback | {API_URL}/api/saml/callback |
| Entity ID / Audience URI | {API_URL}/saml/acs |
Troubleshooting
Groups not syncing
- Confirm the
groups_claim field matches the exact claim name your provider includes in the ID token. You can inspect the claim being received by checking the gateway logs when a user signs in.
- Ensure the claim is configured to be emitted in the ID token (not just the access token). Refer to your provider’s guide for claim configuration.
- Some providers (e.g. Okta) only include the groups claim when a user belongs to at least one group. Ensure every user has at least one group assigned.
Login fails or callback errors
- Verify the redirect URI configured in the identity provider exactly matches
{API_URL}/api/callback (no trailing slash, correct scheme).
- For SAML, confirm the ACS URL is set to
{API_URL}/api/saml/callback and the Entity ID matches {API_URL}/saml/acs.
Access token validation fails (opaque tokens)
Some providers (e.g. Okta with certain authorization server configurations) issue opaque access tokens that cannot be validated directly. Append ?_userinfo=1 to the Issuer URL to instruct the gateway to authenticate via the userinfo endpoint instead:
https://your-org.okta.com/oauth2/default?_userinfo=1
Locked out after misconfiguration
If an incorrect configuration prevents any user from signing in, connect to the Hoop PostgreSQL database and clear the stored configuration:
-- Remove all IDP configuration (gateway will fall back to environment variables or local auth)
DELETE FROM private.authconfig WHERE org_id = (SELECT id FROM private.orgs);
UPDATE private.authconfig
SET admin_role_name = 'my-new-admin-role-group'
WHERE org_id = (SELECT id FROM private.orgs);
