> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak (OIDC)

The Keycloak connector integrates the Maverics Orchestrator with Keycloak -- enabling OIDC-based single sign-on using the open-source identity platform.

> [!NOTE]
>
> **Console terminology:** In the Maverics Console, this section is called
> **Identity Fabric**. The YAML configuration uses the `connectors` key to define
> identity provider integrations.

## Overview

The Keycloak connector uses OpenID Connect. Keycloak publishes a standard OIDC discovery endpoint per realm, making it straightforward to integrate with the Orchestrator -- whether Keycloak is self-hosted or running in a managed environment.

## Use Cases

* **Unify SSO with open-source identity** -- Extend Keycloak authentication to legacy and enterprise applications, delivering seamless SSO for organizations that prefer open-source identity infrastructure
* **Rationalize commercial IdP costs** -- Use Keycloak as a cost-effective replacement for commercial identity platforms, orchestrating gradual migration without disrupting application access
* **Self-hosted identity resilience** -- Deploy Keycloak as a self-hosted failover IdP alongside a primary SaaS provider, ensuring authentication continuity even during cloud provider outages
* **On-premises and private-cloud identity** -- Connect to Keycloak deployments running in private environments where a SaaS IdP is not an option, bridging air-gapped or regulated infrastructure with modern applications

## Setup

**Console UI**

To create a Keycloak (OIDC) connector in the Maverics Console:

1. Navigate to **Identity Fabric** in the Console sidebar.
2. Click **Create** and select **Keycloak (OIDC)**.
3. Enter a **Name** -- this is the friendly name that identifies your provider.
4. Enter the **OIDC Well Known URL** -- for Keycloak, this follows the pattern `https://{host}/realms/{realm}/.well-known/openid-configuration`.
5. Enter the **OAuth Client ID** -- the client ID of the Maverics application registered in your Keycloak realm.
6. Enter the **OAuth Client Secret** -- the client secret from the Keycloak client configuration.
7. Under **Redirect URLs**, add the callback URL where Keycloak will redirect after authentication. This URL must match the Valid Redirect URIs configured in your Keycloak client.
8. Optionally configure **Logout Callback URLs** for single logout support.
9. Optionally set **Scopes** (space-separated). Default scopes are typically `openid profile email`.
10. The **PKCE** toggle is enabled by default. Disable it only if your Keycloak client is not configured to support Proof Key for Code Exchange.
11. Optionally enable **Offline Access** for token refresh support (Proxy apps only).
12. Click **Save**.

**Configuration**

```yaml maverics.yaml theme={null}
connectors:
  - name: keycloak
    type: oidc
    oidcWellKnownURL: "https://{{ env.KEYCLOAK_HOST }}/realms/{{ env.KEYCLOAK_REALM }}/.well-known/openid-configuration"
    oauthClientID: "{{ env.KEYCLOAK_CLIENT_ID }}"
    oauthClientSecret: <vault.keycloak_client_secret>
    oauthLoginRedirect:
      urls:
        - https://app.example.com/oidc/callback
    scopes: "openid profile email"
```

> [!NOTE]
>
> Keycloak's well-known URL is realm-specific. Make sure to include the correct realm name in the path: `/realms/{realm}/.well-known/openid-configuration`.

## Configuration Reference

| Key | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Unique connector identifier referenced in app policies |
| `type` | string | Yes | Must be `oidc` |
| `oidcWellKnownURL` | string | Yes | Keycloak OIDC discovery endpoint URL (realm-specific) |
| `oauthClientID` | string | Yes | OAuth 2.0 client ID from the Keycloak admin console |
| `oauthClientSecret` | string | Yes | OAuth 2.0 client secret (use secret reference syntax) |
| `oauthLoginRedirect.urls` | list | Yes | Callback URL(s) registered with the Keycloak client. The Orchestrator selects the URL whose host matches the incoming request. |
| `oauthLogoutRedirect.urls` | list | No | URL(s) called by Keycloak after a successful logout. |
| `scopes` | string | No | Space-separated OAuth scopes (default: `openid profile email`) |
| `tls` | string | No | Named TLS profile for provider communication |

For the complete field reference including health checks, offline access, and PKCE settings, see [Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference).

## Troubleshooting

* **Verify the well-known URL is accessible** from the Orchestrator host -- ensure the Keycloak host and realm name are correct
* **Ensure each URL in `oauthLoginRedirect.urls` matches exactly** what is registered in the Keycloak client under Valid Redirect URIs
* **Check that the client secret reference resolves correctly** via your secret provider
* **Confirm the Keycloak realm is active** -- disabled or misconfigured realms will cause OIDC discovery to fail

## Related Pages

> **[Identity Fabric](/reference/orchestrator/identity-fabric)**
>
> Overview of all identity providers

> **[Generic OIDC](/reference/orchestrator/identity-fabric/custom-oidc)**
>
> Generic OpenID Connect connector

> **[Okta](/reference/orchestrator/identity-fabric/okta)**
>
> OIDC connector for Okta

> **[Microsoft Entra ID](/reference/orchestrator/identity-fabric/azure-ad)**
>
> OIDC connector for Microsoft Entra ID