Skip to main content

Developer Guide

This guide helps you build with the User Tasks Bridge (UTB). If you want a gentle foundation before diving in, read the short Concepts overview and the OIDC Primer. When you are ready to build, this page shows you how to configure the backend, sign in through your Identity Provider, and call the API from your own app or the Console.

You can use UTB in a few ways. The Console is the fastest way to try things out since it already handles login and token management in the browser. If you are writing your own frontend, you authenticate with your IdP, obtain an access token, and then call the UTB backend either directly over HTTP or through the API Client. All three paths lead to the same API on the backend.

One key detail to keep in mind is how identities line up. The LittleHorse Kernel treats user_id and user_group as strings. UTB connects those strings to real identities from your IdP. If you want a deeper explanation of how that mapping works, start with Users & Groups.

Getting started​

Begin by configuring your IdP in the UTB Backend. In most setups you also choose which claim from the token should be the user identifier. You can choose one of sub, email, or preferred_username. That choice affects how you pass a user id when you assign a task in a workflow. The configuration steps are in the Backend Configuration guide.

Next, run the UTB Backend and check that the OpenAPI docs are available at /swagger-ui.html. The Backend page gives an overview and links to the API reference you will use while building.

After the backend is running, sign in. If you open the Console, it will redirect you to your IdP and handle the login flow for you. If you are building your own UI, use the Authorization Code flow with PKCE to obtain an access token from your IdP. Your frontend then sends that token to UTB on each call.

Once you have a token, you can call the API directly or use the API Client. The client gives you typed methods, but the underlying calls are the same HTTP requests. Here is a minimal example of listing tasks with the client:

import { LHSWBApiClient } from "@littlehorse-enterprises/user-tasks-bridge-api-client";

const client = new LHSWBApiClient({
  baseUrl: "http://localhost:8089",
  tenantId: "default",
  accessToken: "<your-access-token>",
});

const tasks = await client.listUserTasks({ limit: 10, status: "UNASSIGNED" });

For more examples, see the API Client page.

Assigning tasks from a workflow​

From inside a WfSpec, you can direct a UserTask to a specific person or to a group. What you pass as the user id depends on your backend configuration. If you picked email as the user id claim, pass the email address. If you assign to a group, pass the group name.

// Assign to a specific user (for example, by email if configured)
wf.assignUserTask("approve-request", "user@example.com", null);

// Assign to a group by name
wf.assignUserTask("approve-request", null, "approvers");

If that mapping between claims and ids is unfamiliar, the Users & Groups concept page explains it with more context.

How authentication works in practice​

For single page apps and mobile apps, use Authorization Code with PKCE. The browser is sent to your IdP to log in. Your app receives a short code, exchanges it for tokens, and then calls UTB with the access token.

Where to go next​

If you want to configure providers, continue with the Backend Configuration. If you prefer to try things in the browser, open the Console Usage Guide. If you are calling from code, the API Client page has more examples. For more background, read User Tasks in the Kernel, Brokering, and Federation.