> ## 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.

# OAuth2 Authentication

OAuth2 authentication delegates login to an external OAuth2 / OIDC identity provider using Spring Security's OAuth2 support. It works with any standard provider (tested with Keycloak and Auth0).

## Dependencies

```xml theme={null}
<dependency>
  <groupId>org.aseeflow.bpm.springboot</groupId>
  <artifactId>aseeflow-bpm-spring-boot-starter-security</artifactId>
  <version>${aseeflow.bpm-platform.version}</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
```

The ASEE Flow security starter is `provided` in the WebAdmin starter, so include it explicitly.

## Configuration

Enable the mode, then configure the OAuth2 client with standard [Spring Security OAuth2](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html) properties. The example below mirrors the demo's Keycloak setup (realm `aseeflow`, externalized under a `keycloak:` block so the URLs and client secret can be overridden with environment variables):

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

# Externalized identity-provider 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
  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
    # Bearer-token acceptance on /engine-rest — enable only if you have external REST clients
    resourceserver:
      jwt:
        issuer-uri: ${keycloak.url.auth}/realms/aseeflow
        audiences:
          - account
```

The `keycloak` registration/provider IDs are arbitrary labels — use whatever matches your provider. The realm here is `aseeflow`; change it to your own realm.

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

<Warning>
  **`user-name-attribute` and `group-name-attribute` bridge your identity provider to ASEE Flow's permissions.** `user-name-attribute` (here `preferred_username`) becomes the engine user ID — if authorizations are assigned to a username but the IdP maps a UUID, the user logs in but has no permissions. `group-name-attribute` (here `groups`) must match the token claim that carries group memberships, or all group-based authorization checks fail.
</Warning>

Bearer-token validation on `/engine-rest` activates only when `spring.security.oauth2.resourceserver.jwt.issuer-uri` is set (the `resourceserver` block above) — omit that block to make REST session-only (the SPA still works over the SSO session). The `group-name-attribute` claim usually has to be added on the provider so it appears in the token.

## How it works

Unauthenticated UI requests are redirected to the provider; after login, the access token authorizes subsequent UI and REST requests. REST endpoints (`/engine-rest/**`) are protected by default (set `disable-rest-security: true` to disable — only when REST is secured elsewhere; see [consequences](/webadmin/security#never-leave-the-engine-rest-api-unprotected)). Logout is handled by the provider's logout flow.

## When to use it

OAuth2 suits enterprise applications with centralized identity management and integration with providers such as Keycloak, Auth0, or Okta. For deep Keycloak integration with user/group synchronization, use [Keycloak authentication](/webadmin/authentication/keycloak) instead.

## Properties

| Property | Type | Default | Description |
| - | - | - | - |
| `aseeflow.webadmin.authentication` | String | `basic` | Set to `oauth2` 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). |
| `camunda.bpm.oauth2.sso-logout.enabled` | Boolean | `false` | Enables OIDC client-initiated logout. |
| `camunda.bpm.oauth2.sso-logout.postLogoutRedirectUri` | String | empty | Redirect target after logout; defaults to the base path. |
| `camunda.bpm.oauth2.identity-provider.group-name-attribute` | String | `groups` | Token claim that holds group memberships. |

Login behavior and REST token validation derive from the standard `spring.security.oauth2.client.registration.<id>.*` and `spring.security.oauth2.client.provider.<id>.*` properties — see the [Spring Boot OAuth2 reference](https://docs.spring.io/spring-boot/reference/web/spring-security.html) for the full set.


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