Portal Community
App Studio

Passport IAM Integration

App Studio does not manage users or roles — it reads them from the Passport JWT issued at login. The context object in every App Studio session is populated directly from the Passport token claims, making role changes in Passport immediately effective on the next session start.

How context.roles Is Populated

1
User logs in via Passport

Passport authenticates the user and issues a signed JWT. The JWT payload includes standard claims plus BizFirstGO-specific claims: tenantId, roles, userId, custom claims.

2
App Studio reads the JWT at session start

When App Studio loads for a tenant+app, it reads the current Passport JWT from the session. It extracts the claims and builds the context object.

3
context is injected into the token evaluator

All token expressions throughout the app (visibility rules, data source params, widget config) can read from context.*. This includes context.roles, context.userId, context.tenantId.

4
context is refreshed on token renewal

When the Passport JWT is renewed (typically every 15-60 minutes), App Studio updates the context object. Role changes take effect at the next token renewal — not immediately.

Passport JWT Claims Used by App Studio

// Typical Passport JWT payload for App Studio use
{
  "sub": "user-abc-123",           // → context.userId
  "tid": "tenant-acme",            // → context.tenantId
  "roles": ["admin", "sales"],     // → context.roles
  "name": "Jane Smith",            // → context.displayName
  "email": "jane@acme.com",        // → context.email
  "iat": 1716640000,
  "exp": 1716643600,
  "custom_claim_1": "value"        // → context.claims.custom_claim_1
}

Custom Claims in context.claims

Passport can issue custom claims beyond the standard set. These are available under context.claims:

// Passport custom claim: region
// JWT: { "region": "APAC" }
// Available in App Studio as:
{{ context.claims.region }}   →   "APAC"

// Use in visibility expression
"visibilityExpression": "{{ context.claims.region === 'APAC' || context.roles.includes('admin') }}"

When Role Changes Take Effect

ChangeWhen effective in App Studio
Role added to user in PassportNext JWT renewal (session refresh, typically within the token TTL)
Role removed from user in PassportNext JWT renewal — old JWT still valid until expiry
User deactivated in PassportImmediately on next API call (Passport rejects the JWT)
App Studio allowedRoles changedImmediately on next app load
No user management in App Studio App Studio has no user management UI. To add users, assign roles, or revoke access: use Passport. App Studio reads roles; it does not write them.

Testing Permissions as a Different Role

In the App Studio Designer, the State Inspector allows you to simulate a different context to preview how the app looks for different roles without logging out:

// State Inspector — simulate context for preview
{
  "context": {
    "userId": "test-user",
    "tenantId": "acme",
    "roles": ["viewer"],           // Preview as a viewer role
    "displayName": "Test Viewer"
  }
}
// All visibility rules re-evaluate with this simulated context
// The canvas updates live to show the viewer's perspective
← Data Scoping Next: Permissions Audit →