Service Accounts for Runtimes and Notebooks
Syntasa supports associating Cloud Service Accounts (AWS IAM Roles or IAM Users) directly with Notebook Workspaces and Runtime Templates. When a notebook is launched or a job is submitted, the platform automatically assumes the correct cloud identity - no manual credential management inside notebook code is required.
Cloud provider support: AWS (IAM Roles and IAM Users) is currently supported. GCP and Azure support is planned for a future release.
Overview
This guide covers:
- How credential resolution works across interactive and batch contexts
- Supported AWS identity types and their trade-offs
- Configuration steps for Workspace and Runtime Template service accounts
How It Works: The Identity Resolution Stack
When a kernel starts or a job is submitted, the platform evaluates credentials in a fixed priority order. The first match wins; the rest are skipped.
Notebooks Flow
Applies to: Workspaces, Notebook Cards, Notebook Process
| Priority | Source | Condition |
| 1 — Workspace SA | Service Account attached to the Notebook Workspace | Workspace has a SA configured |
| 2 — Runtime Template SA | Service Account attached to the Runtime Template | Workspace has no SA; Runtime Template does |
| 3 — Session Policy | Dynamically scoped IAM policy (data-plane-restricted credentials) | No SA configured; Session Policy feature is enabled |
| 4 — Default Cluster Credentials | Kubernetes node role or EMR Instance Profile (unrestricted) | Session Policy is disabled, or hits OVER_LIMIT / ADMIN_BYPASS |
Important: A Workspace Service Account fully overrides the Runtime Template Service Account. If the Workspace SA lacks permissions needed by background services in that workspace, those services will fail. Ensure the Workspace SA has all required permissions.
Jobs Flow
Applies to: Spark Processors, Scheduled Jobs
There is no active workspace context in this flow. The resolution is simpler:
| Priority | Source | Condition |
| 1 — Runtime Template SA | Service Account attached to the Runtime Template in the Action object | Runtime Template has a SA configured |
| 2 — Session Policy | Dynamically scoped IAM policy | No SA configured; Session Policy feature is enabled |
| 3 — Default Cluster Credentials | Kubernetes node role or EMR Instance Profile | Session Policy disabled or OVER_LIMIT |
The Workspace Service Account is completely ignored in jobs, even if the job originated from a workspace that has a SA attached.
Supported Cloud Identities (AWS)
Within a Service Account, two types of AWS identity are supported. They are mutually exclusive — configure one or the other, not both.
IAM Role ARN (Recommended)
The platform calls AWS STS AssumeRole to obtain short-lived temporary credentials (access key, secret key, session token) valid for 12 hours.
AWS prerequisite — MaxSessionDuration: The target IAM role must have its MaxSessionDuration set to at least 43200 seconds (12 hours) in AWS IAM. The AWS default is 3600 seconds (1 hour). If this is not configured, AssumeRole will fail with
DurationSeconds exceeds the MaxSessionDuration set for this role
Trust policy requirement: The Syntasa infrastructure role (K8s node role or EMR instance profile) must be listed as a trusted principal in the target role's trust policy:
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::<ACCOUNT_ID>:role/<SyntasaInfraRole>"
},
"Action": "sts:AssumeRole"
}
Syntasa infra role permission: The Syntasa infrastructure role itself must also have sts:AssumeRole permission in its own identity policy to be allowed to make the call. This is typically pre-configured by your platform team — if AssumeRole fails despite a correct trust policy, verify with your platform administrator that this permission is in place.
IAM User (Static Keys)
Provide a static AWS Access Key and Secret Key. These are long-lived credentials with no automatic expiry. While supported, this approach is generally discouraged:
- Keys do not rotate automatically
- If a key is compromised, manual rotation is required
- They do not benefit from the time-limited security of STS sessions
Note: IAM User and IAM Role are mutually exclusive — the UI prevents configuring both on the same Service Account. If both were somehow present, static keys would take priority.
How to Configure
Configuring a Workspace Service Account
- Navigate to Notebook Workspaces in the Syntasa UI.
- Select your workspace (or create a new one).
- Open Workspace Settings → find the Service Account field.
- Select an existing Service Account from the dropdown, or create a new one pointing to your IAM Role ARN or IAM User credentials.
- Save. All kernels launched from this workspace will use these credentials.
Effect: Overrides the Runtime Template SA for all notebook sessions in this workspace.
Configuring a Runtime Template Service Account
- Navigate to Runtime Templates in the Syntasa UI.
- Select an existing template or create a new one.
- Find the Service Account field and assign the appropriate Service Account.
- Save. All runtimes provisioned from this template inherit these credentials.
Effect: Used by notebooks (workspaces and cards) when no Workspace SA is set, and by all background jobs running on this runtime — regardless of any Workspace SA.
Required IAM Permissions
Regardless of whether you use an IAM Role or IAM User, the configured identity must have read/write access to the following Syntasa platform folders in your cloud storage bucket. These folders are used by platform services for workspaces, job execution, logging, and cluster operations.
| Folder | Purpose |
| syn-workspace | Notebook workspace storage (user files, checkpoints) |
| syn-app-logs | Application-level log output |
| syn-cluster-config | Cluster configuration artifacts |
| syn-file-uploads | User-uploaded files and datasets |
| syn-volumes | Persistent volume data for running workloads |
| syn-spark-history | Spark history server event logs |
| syn-cluster-logs | Cluster-level diagnostic and operational logs |
| Folder | Purpose |
In addition, the identity must have access to AWS Bedrock for AI/ML model inference used by Jupyter AI chat in notebooks.
Required Bedrock permissions:
{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": "*"
}
Note: You can restrict Resource to specific model ARNs (e.g. arn:aws:bedrock:<region>::foundation-model/anthropic.claude-*) if your security policy requires least-privilege access to individual models.
Example S3 policy statement (replace <your-bucket> with your actual bucket name):
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::<your-bucket>/syn-workspace/*",
"arn:aws:s3:::<your-bucket>/syn-app-logs/*",
"arn:aws:s3:::<your-bucket>/syn-cluster-config/*",
"arn:aws:s3:::<your-bucket>/syn-file-uploads/*",
"arn:aws:s3:::<your-bucket>/syn-volumes/*",
"arn:aws:s3:::<your-bucket>/syn-spark-history/*",
"arn:aws:s3:::<your-bucket>/syn-cluster-logs/*",
"arn:aws:s3:::<your-bucket>"
]
}
Note: If your IAM role does not have access to these folders, platform services (including notebook kernels and Spark jobs) will fail with AccessDenied errors even if the role is otherwise configured correctly.
Relationship to Session Policy
Service Accounts and Session Policy are complementary, not competing features.
| Feature | Controls | Identity Source |
| Service Account | Which IAM Role or User your session runs as | Configured by workspace/runtime admin |
| Session Policy | Which S3 paths and Glue databases that identity can access | Derived from your data plane assignments |
When a Service Account is configured, Session Policy is skipped — the SA's own IAM permissions govern data access. When no SA is configured, Session Policy applies a data-plane-scoped restriction on top of the default cluster role.
Troubleshooting
DurationSeconds exceeds the MaxSessionDuration set for this role
The target IAM role's MaxSessionDuration is below 43200 seconds. Update it:
aws iam update-role --role-name <RoleName> --max-session-duration 43200
AssumeRole fails at job start, falls back to session policy
Common causes:
- Trust policy on the target role does not include the Syntasa infrastructure role.
- Role ARN is malformed or points to a non-existent role
- Network connectivity to the STS endpoint is blocked
Contact your platform administrator to check the runtime-service logs for details.
Credentials expired mid-session (notebook)
Credentials are issued at kernel start and are not refreshed. Restart the kernel from the Syntasa portal to receive a fresh 12-hour set.
Job uses wrong identity (background job)
Verify the Service Account is attached to the Runtime Template, not the Workspace. Background jobs ignore Workspace SAs entirely.
Identity check shows node role instead of expected SA role
Verify the Service Account is attached to the correct entity — Workspace or Runtime Template — depending on your use case. If the configuration looks correct, contact your platform administrator to review runtime-service logs for credential injection failures.