Documentation / Security & Access
Workflow deployment and handler execution permissions
Configure deploy permissions, workflow permissions and handler permissions across manifest locks, scoped AWS IAM publication, activation and admission.
1. Deploy permissions, workflow permissions and handler permissions
Rippflow enforces separate checks for workflow permissions (reading catalog definitions or activating versions), deploy permissions (publishing immutable definitions), and handler permissions (binding approved Lambda versions or Batch job definitions). A Controller role alone cannot register or approve an arbitrary Lambda ARN, Batch queue, or IAM role.
| Operation | Contract & Minimum Version | Required Identity & Preconditions |
|---|---|---|
Workflow catalog read (workflows list, versions) | Controller API (>=1.0.0) | Controller JWT with workflow:read in the authoritative tenant. |
| Artifact & manifest lock verification | Local / CI build + installation catalog | .rippflow/manifest.lock SHA-256 artifact digests matched against installation-approved runtime groups or pinned versions. |
Scoped publication (rippflow deploy / Custom::RippflowWorkflow) | scoped-deployments-v1 / native-iam-v1 (>=1.9.0) | AWS SigV4 IAM caller (RIPPFLOW_DEPLOYMENT_URL): either a pre-provisioned PRINCIPAL#{RoleId|UserId} grant (AuthorizationMode=Default) or an IAM role under /tenants/<tenantId>/<role> or /rippflow-admin/<role> (AuthorizationMode=NativeIAM). |
Legacy manifest publication, activate & rollback | Frozen CLI contract (>=1.0.0) or delegated owner (>=1.9.1) | Requires deployment:write / deployment:rollback plus configured WorkflowRegistryOwnerArn (owner-registry-v1); standalone Controller catalog is read-only. |
Phase dispatch & workflow execution admission (deployments dispatch|run) | scoped-deployments-v1 / scoped-workflow-executions-v1 (>=1.9.0) | Separate IAM principal grant or scoped tenant role with dispatch or execute authority, unrevoked deployment claim, and signed Starter admission. |
2. Dual authorization modes: Default grants vs NativeIAM role paths
The deployment stack parameter AuthorizationMode (Default or NativeIAM) selects between explicit DynamoDB grant rows and AWS-native IAM role path scoping. Toggling AuthorizationMode on stack update is immediate and preserves existing deployments.
| Authorization Mode | Caller & Tenant Scoping | Workload Role & Lifecycle Enforcement |
|---|---|---|
Default (Admin-Gated) | Administrator writes a PRINCIPAL#{RoleId|UserId} item in GrantPoliciesTableName pinning tenantId, namespace, and allowed operations (deploy, read, revoke, dispatch, execute, inspect, cancel). | Every bound Lambda/Batch target and role must match an approved binding entry in the principal's grant policy. |
NativeIAM (native-iam-v1, Self-Service) | Authorizes IAM roles under /tenants/<tenantId>/<role> (matching ^[a-z0-9][a-z0-9_-]{0,62}$) or cross-tenant /rippflow-admin/<role>. Unscoped roles at / fail closed (403). STS sessions resolve via iam:GetRole with cryptographic RoleId binding. | Bound workload roles (invocationRoleArn, executionRoleArn, submissionRoleArn, jobRoleArn) must reside in the caller's AWS account/partition under /tenants/<tenantId>/* (or /rippflow-admin/*) and exclude ReservedRoleArns. Dynamically creates TENANT#<tenantId> on first publish (cross-account claims fail with 409). |
json
// Default mode: explicit GrantPoliciesTableName record
[
{
"principalId": "AROAEXAMPLEROLEID",
"tenantId": "orders",
"namespace": "fulfillment",
"operations": ["deploy", "read", "revoke"],
"bindings": [
{
"type": "lambda",
"functionArn": "arn:aws:lambda:eu-west-1:123456789012:function:charge:42",
"invocationRoleArn": "arn:aws:iam::123456789012:role/tenants/orders/invoke-charge",
"executionRoleArn": "arn:aws:iam::123456789012:role/tenants/orders/charge-workload",
"isolationBoundary": "dedicated_lambda_execution_role"
}
]
}
]
// NativeIAM mode: IAM PassRole policy scoping a CI deployer to /tenants/orders/*
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowPassOnlyOrdersTenantRoles",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::123456789012:role/tenants/orders/*"
}
]
}3. Configure AuthorizationMode, publish, activate and run
shell
# Optional: switch deployment stack to AWS-native self-service IAM mode:
aws cloudformation deploy \
--template-file execution-plane/deployment-service/template.json \
--stack-name "$DEPLOYMENT_STACK" \
--capabilities CAPABILITY_IAM \
--parameter-overrides "AuthorizationMode=NativeIAM"
# Scoped deployment (>=1.9.0 via AWS SigV4 IAM):
export RIPPFLOW_DEPLOYMENT_URL="https://REPLACE.execute-api.eu-west-1.amazonaws.com/v1"
export AWS_PROFILE=orders-deployer
rippflow deploy workflow.yaml --tenant orders --namespace fulfillment --bindings bindings.json --json
rippflow deployments dispatch "$DEPLOYMENT_ID" --phase charge --dispatch-id run-01 --input input.json --json
rippflow deployments run "$DEPLOYMENT_ID" --execution-id exec-01 --input input.json --json
# Legacy / owner-backed version pointer management:
rippflow deploy workflow.yaml --manifest-digest sha256:REPLACE --manifest-ref v1.0.0 --handler-bindings bindings.json
rippflow activate WORKFLOW_NAME --version 1.0.0 --expected-version 0.9.0 --expected-binding-digest "$CURRENT_BINDING_DIGEST" --json
rippflow rollback WORKFLOW_NAME --version 0.9.0 --expected-version 1.0.0 --expected-binding-digest "$CURRENT_BINDING_DIGEST" --jsonVerified sources
Checked 2026-11-05.
- Scoped deployment contract v1 3a3be99 · main
- Native IAM deployment authorization 3a3be99 · main
- Workflow registry ownership 3a3be99 · main
- Deploy, activate, rollback and dispatch routes 7f5ea32 · main
- Approved role bindings and session policies 04cb082 · main