Identity and access
A workflow says who should approve something without knowing how your company stores people. This section connects your login and your directory to IdentityFlow and decides who may do what. Afterwards, a signed-in person gets principals from your own code, and two checks use them.
Before you start: a running IdentityFlow with an OIDC login (Install and run IdentityFlow), or the starter from the tutorial. First step: Connect your identity provider.
The examples in this section use the provider ID acme. Replace it with an ID
for your own system.
- Who may answer a dialog is decided by the dialog’s assignees against the account’s current principals. No access configuration is involved. Continue with Assignee sources when the group lives in another system.
- Who may start, view, operate or audit a workflow family is decided by the access configuration, with the four access functions. Continue with Access control.
An instance’s recipients, the people it is about, are business data. Being a recipient grants nothing by itself; a principal relation in the access configuration can turn it into access.
Connect your identity provider walks through the hooks file: how the host finds it, how a login is routed to your provider, how your directory reports changes through a signed webhook, how to switch between a test directory and a live one, and how to test the file without a database.
Assignee sources covers dialogs whose
group is maintained elsewhere: the assigneeSource field, the resolver, when
IdentityFlow recomputes assignees, and when it checks who may answer.
Access control covers authorization.ts:
access functions, targets and scopes, principal relations, activation when the
host starts, and the My access page that shows what an account can reach.
For a small, complete hooks file with its test, see the recipe Map a login to principals. Every registration and limit is listed in Hooks API. To test who can act in a workflow, see Test workflows.
- A person signs in through your OIDC identity provider. IdentityFlow records an account: the login origin and the OIDC subject.
- The origin, a name you give that login configuration, decides which provider is responsible. The host configuration maps each origin to exactly one provider ID.
- The provider, code in your hooks file, returns the account’s current
principals:
{ providerId, subject }pairs such as{ providerId: 'acme', subject: 'role:vacation-approver' }. - A dialog names its assignees as principals. An account may answer when one of its current principals matches one of the assignees.
- Separately, the access configuration says which principals may start, view, operate or audit each workflow family.
The workflow names a principal, for example as a dialog’s assignees.
IdentityFlow compares that principal with the principals of whoever tries to
act. Neither the workflow nor IdentityFlow parses the subject string; its
meaning belongs to your provider, so prefixes like role: or manager-of: are
your own vocabulary:
assignees: [{ providerId: 'acme', subject: 'role:vacation-approver' }],- compared exactly
- your vocabulary, any case
Subjects are compared without regard to letter case; provider IDs are compared exactly. See Write the hooks file.
- Account: an identity that signed in through OIDC and was verified.
- Origin: the name of one login configuration (
auth.oidc.origin). It routes to one provider; it is not the issuer URL. - Provider: the code you register with
hooks.identity.provider(id, …). Its ID scopes every principal it returns. - Principal: a person, role, membership or relationship, as your provider names it, always together with the provider ID.
- Assignee: a principal recorded on a pending dialog as someone who may answer it.
- Assignee source: a reference to a group maintained in another system, resolved again when a change event arrives.
- Change event: a signed webhook call from your directory that IdentityFlow
turns into a change with an
eventId. - Access function:
starter,viewer,operatororauditor.
Concepts places these terms next to workflows, instances and steps.
Why the provider ID travels with every principal
Section titled “Why the provider ID travels with every principal”user:alex from provider A and user:alex from provider B are two different
principals. This matters when you merge two directories, or run a test provider
next to a real one: without the provider ID, the matching string would grant
access to the wrong person. A pending dialog therefore stores the provider ID
next to every assignee, and IdentityFlow compares both before it considers
visibility, ordering, paging, or letting a command through.
IdentityFlow asks the provider when someone signs in. For reads, such as lists
and pages, it reuses that answer for up to principalCacheTtl, 15 minutes by
default, then asks again. Whenever someone acts, it asks the provider fresh: a
membership removed a minute ago no longer counts, and if the provider cannot
answer, the action is refused.