Skip to main content

Users & Groups

When using User Tasks in the LittleHorse Kernel, you have to coordinate Users and Groups across your own Identity Provider (IdP) and also your workflows (WfSpecs and WfRuns). This is the most important problem solved by Pony ID.

Users​

Users are the people to whom UserTasks are assigned. They are the ones that can actually complete the UserTasks.

User Id​

In most IdPs, the ID for a user is a UUID. By default, this means that when you assign a UserTaskRun to a user from within the LittleHorse orchestrator (eg. wf.assignUserTask("my-user-task", userId, null);), you need to know the UUID of the user you're assigning it to. That is often tricky—sometimes, it's an easier developer experience to use other fields such as the username or email.

The User Tasks Bridge allows you to configure which JWT claim is used to represent the user_id. This is done via a configuration property in the Pony ID Backend. There are three alternatives: sub (the UUID of the user in the IdP), email, or preferred_username.

You can configure this by setting the user-id-claim in your oidc-properties.yml file under the specific provider configuration. For example, to use the user's email address as the ID for a specific provider:

com:
  c4-soft:
    springaddons:
      oidc:
        ops:
          - iss: <issuer-url>
            # ... other provider properties
            user-id-claim: EMAIL
            # ... other provider properties

With this configuration, you can now assign tasks using the user's email address.

User Profile​

When a user is created in or brokered to Pony ID, we can store profile data for them. Initially, this includes their First Name and Last Name, but this is configurable and can be extended to include other details like phone numbers, addresses, or profile picture URLs.

Groups​

Groups are a way to group users together. They allow UserTasks to be assigned to a collection of users, any of whom can claim and complete the task. For example, a UserTask named ticket-1234 could be assigned to the support-team group. Any user in that group can then claim and complete the ticket.

When assigning a UserTask to a group, you should use the group's name.

Managing Groups​

Groups and users membership of those groups currently must be managed directly within Pony ID. They are not automatically synchronized from an external Identity Provider (IdP).

You can manage groups using the Pony ID administrative UI or programmatically via the API.

Usage in Workflows​

From within a WfSpec, you can assign UserTasks to either an individual user or a group of users. This is done using the assignUserTask function, which is available on the workflow context. The function typically takes three parameters: the UserTask name, a userId, and a groupId.

Assigning to a User​

To assign a UserTask to a specific user, you provide their user ID as the second parameter and null for the group ID. The format of the userId depends on your user-id-claim configuration in Pony ID.

// Example: Assigning a UserTask to a user by email
wf.assignUserTask("approve-request", "user@example.com", null);

Assigning to a Group​

To assign a UserTask to a group, you provide the group name as the third parameter and pass null for the user ID. Any member of the group can then claim and complete the task.

// Example: Assigning a UserTask to the 'approvers' group
wf.assignUserTask("approve-request", null, "approvers");