Skip to main content

OpenID Connect Primer

OpenID Connect (OIDC) is an identity layer on top of OAuth 2.0. In OIDC, an application relies on an Identity Provider (IdP) such as Keycloak, Okta, or Auth0 to authenticate users. When the user is authenticated, the IdP issues JSON Web Tokens (JWTs) which the application (and UTB) validates.

You don’t need to become a protocol expert. You only need to recognize who issues tokens (the IdP), who consumes them (your app and UTB), and what the tokens are used for (identifying the user and authorizing calls).

The LittleHorse User Tasks Bridge (UTB) connects human users to workflow tasks: it lets users view, claim, and complete tasks generated by LittleHorse workflows. UTB uses OIDC to authenticate users, map identities to UTB users and groups, and authorize calls to its backend APIs.

Some key terms in OpenID Connect are:

  • Identity Provider (IdP) / OpenID Provider (OP): the OAuth/OIDC service that authenticates users and issues tokens.
  • Relying Party (RP): the application or API that trusts the IdP and validates presented tokens.
  • ID Token: a JWT that conveys identity claims about the authenticated user to the client.
  • Access Token: a JWT presented to resource APIs (like UTB) to authorize calls.
  • Claim: a key–value attribute inside a token (for example sub, email, or preferred_username).

Where OIDC Fits in UTB​

UTB sits behind your IdP (for example, Keycloak, Okta, or Auth0). Users authenticate with your IdP; then your UI or client code calls the UTB backend with an Access Token. You can use the UTB Console (which handles OIDC under the hood), build your own frontend that talks to the IdP directly, or use the API Client so long as you supply a valid token.

Tokens and Claims​

There are three token types you’ll encounter. The ID Token tells the client who the user is and carries identity claims. The Access Token is presented to APIs like UTB and conveys what the client is allowed to do; you send it as Authorization: Bearer <token>. The Refresh Token allows the client to get new tokens without making the user log in again.

For identity, a few claims matter most. The sub claim is a stable unique identifier in the IdP (often a UUID). Many deployments also rely on email or preferred_username. The UTB backend lets you choose which of these claims is treated as the canonical user_id for assignments and audit. You pick exactly one: sub, email, or preferred_username.

The Login Flow (Authorization Code + PKCE)​

For SPAs and mobile apps, Authorization Code with PKCE is the modern, secure approach. The client sends the user to the IdP to log in, receives an authorization code, exchanges it for tokens using a code verifier, and then calls UTB with the resulting Access Token. The client never stores a client secret, and PKCE protects the token exchange.

Validating Tokens​

On the backend, the token’s issuer must match the IdP’s iss, the aud must be appropriate for the client or API, and the signature is checked against the IdP’s JWKS (discoverable via the standard .well-known/openid-configuration). The exp and nbf claims must be valid. Because different machines can have slightly different system time (clock skew), a freshly issued token might appear "not yet valid" (nbf) or "expired" (exp). Mitigate this by syncing server clocks with NTP and configuring a small allowable skew window in your validator or reverse proxy (for example 60-300 seconds). In many setups, your IdP library or API gateway handles these details, but the important part is that the Access Token presented to UTB is valid and intended for it.

Brokering, Federation, and Direct Integration (Three Ways to Bring Identities into Your System)​

There are a few ways to bring identities into your system. With brokering, your primary IdP (for example, Keycloak) lets users sign in with an external IdP (for example, Okta). Users are imported on first login, and IdP‑level profile mappers can copy over attributes. With federation, users are synchronized from an external directory - useful for batch import or ongoing sync. You can also connect directly: your application talks to the IdP, obtains tokens, and then calls UTB with those tokens.

See also: User Tasks in the Kernel, Users & Groups, Brokering, and Federation.

Profile Mapping (Context)​

Profile mapping lives in the IdP and defines how claims from an external IdP are copied or transformed into profile fields in your primary IdP during brokering - for example, splitting a fullName field into firstName and lastName. This is separate from UTB’s choice of user_id: UTB’s backend configuration picks which claim - sub, email, or preferred_username - to treat as the user’s ID for assignments.

Next Steps​

To see how these ideas show up in practice, start with User Tasks in the Kernel and Users & Groups. To decide how users authenticate, read Brokering and Federation. If you prefer client helpers, see Using the API Client. If you are building your own UI, follow the Authorization Code with PKCE flow above to obtain tokens from your IdP and call UTB with the Access Token.