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

# Keycloak Authentication

Keycloak authentication combines OAuth2 / OIDC login with a dedicated Keycloak identity provider plugin, giving you single sign-on plus full synchronization of Keycloak users and groups into the ASEE Flow engine.

## Dependencies

```xml theme={null}
<dependency>
  <groupId>org.camunda.bpm.extension</groupId>
  <artifactId>camunda-platform-7-keycloak</artifactId>
  <version>${camunda.platform-7-keycloak.version}</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
```

These are `provided` in the starter, so include them explicitly. `camunda-platform-7-keycloak` (the Keycloak identity provider plugin) is `7.24.0`. The `org.camunda.bpm.*` coordinate is correct — it is an external Camunda extension that ASEE Flow uses as-is.

## Configuration

Enable the mode and configure the Spring Security OAuth2 client (as for [OAuth2](/webadmin/authentication/oauth2)):

```yaml theme={null}
aseeflow:
  webadmin:
    authentication: keycloak

# Externalized Keycloak configuration
keycloak:
  url.auth: ${KEYCLOAK_URL_AUTH:http://localhost:9000/auth}      # browser redirects (SSO login)
  url.token: ${KEYCLOAK_URL_TOKEN:http://localhost:9000/auth}    # server-side token requests
  url.plugin: ${KEYCLOAK_URL_PLUGIN:http://localhost:9000/auth}  # Identity Provider plugin access
  client.id: ${KEYCLOAK_CLIENT_ID:aseeflow-identity-service}
  client.secret: ${KEYCLOAK_CLIENT_SECRET:<your-client-secret>}  # inject via env var; never commit

camunda.bpm.oauth2:
  sso-logout:
    enabled: true
    postLogoutRedirectUri: http://localhost:8080/webadmin
  identity-provider:
    group-name-attribute: groups

spring.security:
  oauth2:
    client:
      registration:
        keycloak:
          provider: keycloak
          client-id: ${keycloak.client.id}
          client-secret: ${keycloak.client.secret}
          authorization-grant-type: authorization_code
          redirect-uri: "{baseUrl}/{action}/oauth2/code/{registrationId}"
          scope: openid, profile, email
      provider:
        keycloak:
          issuer-uri: ${keycloak.url.auth}/realms/aseeflow
          authorization-uri: ${keycloak.url.auth}/realms/aseeflow/protocol/openid-connect/auth
          user-info-uri: ${keycloak.url.auth}/realms/aseeflow/protocol/openid-connect/userinfo
          token-uri: ${keycloak.url.token}/realms/aseeflow/protocol/openid-connect/token
          jwk-set-uri: ${keycloak.url.token}/realms/aseeflow/protocol/openid-connect/certs
          user-name-attribute: preferred_username
    resourceserver:
      jwt:
        issuer-uri: ${keycloak.url.auth}/realms/aseeflow
        audiences:
          - account
```

Then configure the identity provider plugin so the engine can resolve users and groups from Keycloak:

```yaml theme={null}
plugin.identity.keycloak:
  keycloakIssuerUrl: ${keycloak.url.plugin}/realms/aseeflow
  keycloakAdminUrl: ${keycloak.url.plugin}/admin/realms/aseeflow
  clientId: ${keycloak.client.id}
  clientSecret: ${keycloak.client.secret}
  useEmailAsCamundaUserId: false
  useUsernameAsCamundaUserId: true
  useGroupPathAsCamundaGroupId: true
  enforceSubgroupsInGroupQuery: true
  administratorGroupName: aseeflow-admin
  disableSSLCertificateValidation: true   # development only — use proper certificates in production
```

<Note>
  These values are for **local testing** — a Keycloak at `localhost:9000`, the demo `aseeflow` realm and client, and disabled SSL validation. For production, point at your own Keycloak realm and URLs, supply the client secret via an environment variable, remove `disableSSLCertificateValidation`, and harden per [Security](/webadmin/security).
</Note>

## How it works

Users are redirected to Keycloak for OAuth2 / OIDC login; Spring Security manages the session. The identity provider plugin synchronizes Keycloak users, groups, and roles into the engine's Identity Service in real time, including nested group hierarchies and an administrator-group mapping. On logout, an OIDC-compliant flow returns the user to `/webadmin/`.

When deploying behind a reverse proxy or load balancer, a `ForwardedHeaderFilter` ensures OAuth2 redirect URIs are assembled correctly, and a customized firewall permits the URL-encoded slashes used in nested Keycloak group paths.

## When to use it

Keycloak authentication is ideal when your organization already uses Keycloak for SSO and you want full Keycloak role and group integration with ASEE Flow, beyond what token claims alone provide.

## Properties

WebAdmin properties:

| Property | Type | Default | Description |
| - | - | - | - |
| `aseeflow.webadmin.authentication` | String | `basic` | Set to `keycloak` to enable this mode. |
| `aseeflow.webadmin.disable-rest-security` | Boolean | `false` | When `true`, REST endpoints are reachable without authentication — only safe when secured elsewhere; see [REST security](/webadmin/security#never-leave-the-engine-rest-api-unprotected). |

Keycloak identity provider plugin properties (under `plugin.identity.keycloak`):

| Property | Type | Description |
| - | - | - |
| `keycloakIssuerUrl` | String | Keycloak realm issuer URL. |
| `keycloakAdminUrl` | String | Keycloak admin API URL for the realm. |
| `clientId` | String | OAuth2 client ID. |
| `clientSecret` | String | OAuth2 client secret. |
| `useEmailAsCamundaUserId` | Boolean | Use the email claim as the engine user ID. |
| `useUsernameAsCamundaUserId` | Boolean | Use the username claim as the engine user ID. |
| `useGroupPathAsCamundaGroupId` | Boolean | Use the full group path as the engine group ID. |
| `enforceSubgroupsInGroupQuery` | Boolean | Include nested subgroups when resolving group memberships. |
| `administratorGroupName` | String | Keycloak group whose members are treated as administrators (the demo uses `aseeflow-admin`). |
| `disableSSLCertificateValidation` | Boolean | Disable SSL validation (development only). |

<Note>
  Use proper SSL certificates in production; `disableSSLCertificateValidation` is for development only. The demo enables it because Keycloak runs locally over HTTP.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.