Access control with RBAC

What RBAC is for

RBAC (role-based access control) controls who can call your workflows' API endpoints. You define roles, write policies that say which roles may use which endpoints, and attach the policies to a workflow. When a request arrives, the caller's roles are read from a token (a JWT) they send, and the policies decide whether it goes through.

This is about the people and systems calling your endpoints. It doesn't control who can sign in to the designer or what its users can edit.

Everything here belongs to the selected store, and has two tabs: Policies and Roles.

Roles

A role is just a name that your tokens carry. Create the roles you need on the Roles tab with Create role.

• Role Name uses the format resource:action, for example orders:read, orders:write or customer:write. Letters, numbers, _ and - are allowed.
• Description says what the role allows.

Deleting a role doesn't remove it from policies that mention it, so check your policies first.

Policies

A policy is a named set of rules. Create one on the Policies tab with Create policy.

• Policy Name and an optional Description.
• Priority: a number, 0 by default. Higher priority policies are evaluated first.
• Rules: add as many as you need with Add Rule. Each rule has:
  • Roles: one or more roles, or * (All roles). Create roles first if the list is empty.
  • HTTP Methods: any of GET, POST, PUT, DELETE and PATCH.
  • Path Pattern: the endpoint path the rule applies to.
  • Effect: Allow or Deny.

Path patterns:

Pattern	Matches
/v2/orders	That exact path
/v2/customer/:customerId	Any single value in that position (a path parameter)
/api/*	One path segment
/api/**	Any number of segments

Each policy shows as a card with its rules, roles, methods, paths and effect. Use Deactivate or Activate to turn a policy off or on, the edit icon to change it, and the trash icon to delete it.

Attaching policies to a workflow

Policies only apply once attached to a workflow.

1. Open the workflow and go to its RBAC tab.
2. Under RBAC Policy, choose one or more policies. Only active policies are listed.
3. Fill in JWT Authentication Configuration, which appears once a policy is chosen:
   • Header Name and Prefix (optional): where the token is sent, normally Authorization with the prefix Bearer .
   • Secret Variable: a secure-string workflow variable holding the secret used to check tokens.
   • Algorithm: HS256, HS384, HS512, RS256, RS384 or RS512.
   • Roles Path: where the roles are in the token, for example roles or permissions.roles.
4. Select Save configuration.

Remove all policies to turn access control off for that workflow.

How a request is decided

When a request reaches a workflow with policies attached:

1. If no rule matches the request's method and path, the request is allowed. Access control only applies to the paths your rules cover.
2. If a rule matches, the token is read and checked, and the caller's roles are taken from it. A missing, invalid or expired token is rejected as unauthorized, and a token with no roles is forbidden.
3. The matching rules are checked in priority order, and the first rule that covers one of the caller's roles decides: Allow lets it through and Deny blocks it.
4. If rules match the path and method but none cover the caller's roles, the request is denied.

So within the paths you cover, access is closed unless a rule opens it.

Changing policies safely

• A published workflow keeps the policies it had when you launched it. Editing, deactivating or deleting a policy doesn't change a live workflow until you publish and configure it again. The page warns about this when you deactivate a policy. See Launching workflows.
• Before launching, try the workflow with test requests from the workflow's tests to check the rules behave as you expect.
• Don't write an Allow rule for a path unless every legitimate caller's role is listed, or the rule uses * (All roles).
• Check that the secret variable has a value and the Roles Path matches where your tokens carry roles. Otherwise every request that matches a rule is rejected.