Skip to main content

The Basics (OIDC)

This guide covers the essential OIDC concepts and configuration needed to connect any OpenID Connect compliant Identity Provider to the User Tasks Bridge Backend.

What is OIDC?​

OpenID Connect (OIDC) is an identity layer on top of OAuth 2.0. It allows applications to verify user identity based on authentication performed by an Identity Provider (IdP) such as Keycloak, Okta, or Auth0.

When a user authenticates with your IdP, the IdP issues JSON Web Tokens (JWTs) that contain claims about the user. The User Tasks Bridge Backend validates these tokens and uses the claims to identify users and determine their permissions.

Required Configuration​

To connect your IdP to the User Tasks Bridge Backend, you need to configure both your IdP and the backend.

IdP Configuration Requirements​

Your IdP must be configured to:

  1. Issue access tokens with the required claims
  2. Provide an issuer URL (iss) that the backend can validate
  3. Support OIDC discovery (recommended) or provide explicit endpoints
  4. Include required claims in access tokens:
    • allowed_tenant: Your LittleHorse tenant ID (required for all users)
    • Admin role claim: A claim that identifies admin users (optional, but recommended)

Backend Configuration​

The User Tasks Bridge Backend uses a YAML configuration file (oidc-properties.yml) to define IdP settings:

config/oidc-properties.yaml
com:
  c4-soft:
    springaddons:
      oidc:
        ops:
          - iss: <issuer-url>
            label-name: <display-name>
            username-claim: <username-claim>
            user-id-claim: <user-id-claim>
            authorities:
              - path: <json-path-to-roles>
            vendor: <vendor-name>
            tenant-id: <tenant-id>
            client-id-claim: <client-id-claim>
            clients:
              - <client-id-1>
              - <client-id-2>

Configuration Fields Explained​

iss (Issuer URL)​

The issuer URL of your Identity Provider. This is the base URL where your authentication server is hosted. The backend uses this to validate tokens and discover OIDC endpoints.

Example: https://your-idp.example.com/realms/your-realm

label-name​

A display name used in the login UI to differentiate between multiple IdPs configured for the same tenant.

Example: "Production Keycloak" or "Corporate Okta"

username-claim​

The JWT claim field that contains the username. Common values:

  • preferred_username
  • email

user-id-claim​

The JWT claim field used as the userId when performing task assignments. You must choose exactly one:

  • EMAIL - Uses the email claim as user ID
  • PREFERRED_USERNAME - Uses the preferred_username claim as user ID
  • SUB - Uses the subject (sub) claim as user ID (typically a UUID)
info

The choice of user-id-claim affects how you assign tasks in workflows. If you choose EMAIL, you'll pass email addresses when assigning tasks. If you choose SUB, you'll pass the subject identifier.

authorities​

JSON paths that indicate where roles are found in the token's claims. This is used to differentiate between ADMIN and NON-ADMIN users. You must provide at least one path.

Examples:

  • $.realm_access.roles (Keycloak realm roles)
  • $.resource_access.*.roles (Keycloak client roles)
  • $.groups (if your IdP uses groups)
  • $.customRole (custom claim name)

vendor​

The name of your Identity Provider vendor. This can be any identifier, but common values include:

  • keycloak
  • okta
  • auth0

tenant-id​

Your LittleHorse tenant ID. This must match a tenant that already exists in your LittleHorse Kernel.

client-id-claim​

The JWT claim field that contains the client ID. This helps identify which application the token was issued for. Common values:

  • azp (Authorized Party) - used by Keycloak
  • cid - used by Okta
  • aud (Audience) - used by some providers

clients​

A list of client IDs that are authorized to access the User Tasks Bridge. Each client ID should match a client ID registered in your Identity Provider.

Required Claims in Access Tokens​

All access tokens must include:

allowed_tenant (Required)​

This claim must be present in all access tokens. It should contain your LittleHorse tenant ID as a string value.

Example: "allowed_tenant": "default"

warning

If the allowed_tenant claim is missing from an access token, the User Tasks Bridge Backend will reject the request, even if the user is otherwise authenticated and authorized.

Admin Role Claim (Optional)​

To enable admin features, you need to configure a claim that identifies admin users. The claim name and value depend on your IdP configuration, but the role value must be lh-user-tasks-admin.

Example: If you configure a custom claim called customRole that contains ["lh-user-tasks-admin"], users with this role will have admin privileges.

Multiple OIDC Providers​

You can configure multiple OIDC providers by adding additional entries under the ops list in the configuration file. Each entry represents a separate Identity Provider configuration with its own issuer URL, clients, and settings.

ops:
  - iss: <issuer-url-1>
    # ... first provider config
  - iss: <issuer-url-2>
    # ... second provider config

Token Validation​

The User Tasks Bridge Backend validates tokens by:

  1. Checking the issuer (iss) matches the configured issuer URL
  2. Verifying the signature using the IdP's JWKS (JSON Web Key Set)
  3. Validating expiration (exp) and not-before (nbf) claims
  4. Checking the audience (aud) if configured
  5. Verifying required claims are present