> ## 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. # Keycloak > Connect hoop.dev to Keycloak using OpenID Connect (OIDC). ## Requirements * A running Keycloak instance (v17 or later recommended) * Admin access to the Keycloak Admin Console * `API_URL` is the public DNS name of the Hoop gateway instance (e.g. `https://hoop.yourcompany.com`) Contact the administrator of the Hoop gateway instance to retrieve the `API_URL` address. > [!NOTE] > > The Keycloak instance must be reachable by both the Hoop gateway (for server-side token exchange) and end users' browsers (for the login redirect). If your Keycloak hostname resolves differently inside your VPC, use the internal hostname as the Issuer URL. ## Identity Provider Configuration ### 1. Create a Client * Log in to the Keycloak Admin Console at `https:///admin` * Select your **Realm** from the top-left dropdown > [!NOTE] > > The **master** realm is acceptable for testing. A dedicated realm is recommended for production. * Go to **Clients** and click **Create client** * Set **Client type** to `OpenID Connect` * Set **Client ID** to a name that identifies your Hoop instance (e.g. `hoop`) * Click **Next** On the **Capability config** step: * Enable **Client authentication** (this makes the client confidential) * Enable **Standard flow** * Click **Next**, then **Save** ### 2. Configure the Redirect URIs * Open the client you just created and go to the **Settings** tab * Set **Valid redirect URIs** to: `{API_URL}/api/callback` * Set **Valid post logout redirect URIs** to: `{API_URL}/api/logout` * Click **Save** ### 3. Collect the Credentials * Go to the **Credentials** tab of the client * Copy the **Client Secret** — this is generated automatically when client authentication is enabled The **Client ID** is the value you set during creation (e.g. `hoop`). It is also visible on the **Settings** tab. ### 4. Collect the Issuer URL The Issuer URL format depends on your Keycloak version: * **Keycloak v17 and later:** `https:///realms/` * **Keycloak v16 and earlier:** `https:///auth/realms/` To confirm the exact value, go to **Realm Settings > General** and click **OpenID Endpoint Configuration**. The `issuer` field in the returned JSON is the value to use. ### 5. Configure an Audience Mapper Keycloak does not include the client audience in the token by default. Without it, Hoop cannot validate the token. You must add an audience mapper to the client. * Go to **Clients** and select your client * Open the **Client scopes** tab * Click the link named `{your-client}-dedicated` (e.g. `hoop-dedicated`) to open the dedicated scope for this client > [!NOTE] > > This dedicated scope is only visible inside the client's **Client scopes** tab. It does not appear in the global **Client scopes** menu in the left sidebar. * Click **Add mapper > By configuration** * Select **Audience** * Set **Name** to `hoop-audience` * Set **Included Client Audience** to your Client ID (e.g. `hoop`) * Enable **Add to ID token** and **Add to access token** * Click **Save** ## Configuring Groups (Optional) Groups in Keycloak are propagated to Hoop via a claim in the ID token. Complete this section if you want Hoop to sync Keycloak group membership on every login and use groups for access control. ### 1. Create a Groups Scope * Go to **Client scopes** in the left sidebar and click **Create client scope** * Set **Name** to `groups` * Set **Type** to `Optional` * Click **Save** * Go to the **Mappers** tab and click **Add mapper > By configuration** * Select **Group Membership** * Set **Name** to `groups` * Set **Token Claim Name** to `groups` * Disable **Full group path** unless your group names include a path separator * Click **Save** ### 2. Assign the Scope to Your Client * Go to **Clients** and select your client * Open the **Client scopes** tab * Click **Add client scope** * Select `groups` and choose **Optional** * Click **Add** ## Configure Hoop Gateway Once you have collected the credentials from Keycloak, configure the identity provider in the Hoop web app. Go to **Integrations > Authentication** and provide the following values: | Field | Value | | - | - | | **Client ID** | The Client ID set during client creation (e.g. `hoop`) | | **Client Secret** | The secret copied from the **Credentials** tab | | **Issuer URL** | `https:///realms/` | | **Custom Scopes** | Optional. Add `groups` here if you completed the Groups configuration above. | | **Groups Claim** | `groups` — required if you completed the Groups configuration above. | | **Audience** | Leave blank (see note below) | > [!WARNING] > > Do not set the **Audience** field when using Keycloak. Audience validation is enforced through the token mapper configured in Step 5, not the authorization request. Setting this field will cause Keycloak to reject logins with a 400 error. Click **Save**. Your users can now log in to Hoop using their Keycloak credentials. For a full reference of gateway environment variables, see the [Environment Variables documentation](https://mintlify.hoop.dev/docs/setup/configuration/env-vars.md). ## Troubleshooting **Token validation fails after login** The most common cause is a missing or misconfigured audience mapper. Confirm that the `aud` claim in the issued token matches the Client ID. You can inspect the token by decoding it at [jwt.io](https://jwt.io). **Wrong Issuer URL format** Keycloak changed its URL structure in v17. If the issuer URL returns a 404, check whether your instance uses `/auth/realms/` (v16 and earlier) or `/realms/` (v17 and later). **Login redirects to Keycloak but returns a 400 error** This is most commonly caused by the **Audience** field being set in Hoop's gateway configuration. Leave it blank — see the [Configure Hoop Gateway](#configure-hoop-gateway) section above. **Groups not syncing** Confirm that the `groups` client scope is assigned to the client and that the user belongs to at least one group. Hoop will not sync an empty groups claim. **Keycloak is unreachable from the Hoop gateway** Confirm that the Issuer URL is accessible from within the network where the Hoop gateway is deployed, not just from a browser. The gateway makes server-side requests to Keycloak for token exchange. If the hostname resolves differently inside your VPC, use the internal hostname as the Issuer URL. **Locked out after configuration** If a misconfigured IDP locks you out of the application, refer to the [Identity Providers troubleshooting guide](https://mintlify.hoop.dev/docs/setup/configuration/idp/get-started.md#troubleshooting). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.