> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cross-Cloud IAM
> How AWS IAM in your application adapts to a customer's deployment target.
This page describes IAM resources that belong to **your application**: identities, roles, policies and the IAM API calls your application makes. The [Permissions Model](/byoc/fundamentals/permissions-model) describes access granted to the Tensor9 BYOC control plane. Installation documentation covers the appliance's cloud identity.
Applications use cloud IAM to define who may call a service, which actions are allowed and which resources are in scope. Those definitions are specific to the origin cloud. A deployment on another cloud must preserve the application's authorization behavior even when the target uses a different identity system.
Tensor9 BYOC adapts AWS IAM through two [adaptation tiers](/byoc/service-adapters/overview#adaptation-tiers). The **[Infrastructure only adaptation tier](/byoc/service-adapters/overview#adaptation-tiers)** maps permissions declared in infrastructure to native grants during deployment. The **[Max adaptation tier](/byoc/service-adapters/overview#adaptation-tiers)** serves supported AWS IAM calls and evaluates the adapted policy inside each appliance.
## Origin and targets
This page covers an AWS origin stack: an application built for AWS, using AWS IAM, deployed to a customer running a different cloud. The IAM service adapter reads identities and policy statements from the AWS model, then applies the adaptation tier selected for the deployment. Infrastructure only emits grants in the target cloud's IAM system. Max retains an adapted policy model and authorizes requests inside the appliance.
Google Cloud, Azure and OCI are available as native-IAM targets, where deployment emits grants in that cloud's own IAM system. Private Kubernetes has no native cloud IAM to emit into, so it requires the [Max adaptation tier](/byoc/service-adapters/overview#adaptation-tiers), with [Cedar](https://cedarpolicy.com/en) evaluating the adapted policy inside the appliance. Cedar is also what evaluates your policies at Max on any of the other three.
## Policy compatibility
Before deployment, the IAM service adapter evaluates every statement in a policy document against the selected target. The document receives one of four outcomes:
| Outcome | Deployment behavior |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Faithful | Deployment proceeds with the policy's restrictions intact. |
| Narrower | Deployment proceeds and reports a recommendation. The workload receives less permission than requested and may fail at runtime. |
| **Wider** | **Deployment is blocked by default.** You must accept the broader grant explicitly. |
| Incompatible | Deployment is refused because the target cannot express the policy. An acceptance cannot override this result. On the native-grant path, examples include `Deny` and `NotAction`. |
For an AWS origin, an accepted policy maps to Cedar for runtime authorization or to the target cloud's native IAM during deployment.
A failure applies to the entire policy document. The adapter reports the document name and reason; it does not remove an unsupported statement and continue with the rest.
### Accept a broader grant
Only the Wider outcome can be accepted. At the **[Infrastructure only adaptation tier](/byoc/service-adapters/overview#adaptation-tiers)**, place the annotation immediately above the IAM resource whose target grant may be broader:
```hcl theme={null}
# This bucket-scoped grant may become project-scoped on the target cloud.
#@iam(compat='widen')
resource "aws_iam_role_policy" "object_access" {
role = aws_iam_role.application.id
policy = jsonencode({
Version = "2012-10-17"
Statement = [{
Effect = "Allow"
Action = ["s3:GetObject", "s3:PutObject"]
Resource = "arn:aws:s3:::application-data/*"
}]
})
}
```
The annotation applies to that resource. Other policies remain subject to the default block. Keeping the acceptance next to the policy also makes its owner and scope visible during code review.
At the **[Max adaptation tier](/byoc/service-adapters/overview#adaptation-tiers)**, the acceptance travels on the create request instead of through Terraform. Put the tuning entry in the request's `Tags` field. For example:
```bash theme={null}
aws iam create-role \
--role-name application \
--assume-role-policy-document file://trust-policy.json \
--tags \
Key='t9:tuning:[....]',Value=''
```
The key after `t9:tuning:` identifies the target attribute. Values are strings on the wire and are parsed into the corresponding native type. Lists use comma-delimited values without brackets, and maps are set one scalar entry at a time. Because the tag is part of the IAM create request, no separate configuration file or client protocol is required. Neither acceptance form can release an Incompatible policy.
### Policy forms that are refused
At Max, the following forms cause the complete policy document to fail:
| Policy form | Reason |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `"Action": "s3:Get*"` | Declarable action groups are limited to `*` and `:*`. `s3:*` is accepted; a narrower prefix is refused. |
| `"Action": ["s3:GetObject", "s3:List*"]` | One statement combines exact and starred actions. Use separate statements. |
| `NotAction`, `NotResource`, `NotPrincipal` | The inverse match has no faithful equivalent. |
| `"Principal": "*"` | The statement grants access to an unbounded principal set. |
| `"Principal": {"Service": "..."}` | Service principals are not supported. |
| A principal in another AWS account | Concrete cross-account principals are refused. |
| `${aws:username}` or another policy variable | Policy-variable interpolation is not supported. |
| A `?` wildcard | Only `*` wildcards are supported. |
| A condition key outside the supported set below | The adapter cannot reconstruct a value for the condition from the request. |
### Supported condition keys
Five condition keys survive into the Cedar policies your adapter evaluates at runtime, and which of
them you get depends on the tier. At Infrastructure only there is a second, separate set: your
permissions become grants in the target cloud's own IAM, and each cloud expresses a different handful
of conditions. That per-cloud table is below, and it is not a subset of these five.
| Condition key | Max | Infrastructure only |
| ------------------------------------------------------- | --------- | ------------------- |
| `aws:CurrentTime` | Supported | Supported |
| `aws:EpochTime` | Supported | Refused |
| `route53:ChangeResourceRecordSetsNormalizedRecordNames` | Supported | Refused |
| `route53:ChangeResourceRecordSetsRecordTypes` | Supported | Refused |
| `route53:ChangeResourceRecordSetsActions` | Supported | Refused |
The split is about **where the policy is evaluated**, not about the tier you bought. A condition can only be
checked if something can supply its value at the moment of the decision.
The appliance evaluating a request as it serves it has the request in hand, so it can reconstruct the three
Route 53 keys from the change batch. That is the Max column. A policy compiled into target-cloud grants at
deployment time has no request to read, so only the clock keys survive; that is the Infrastructure-only
column, and it also applies to a policy you declare in Terraform even on a Max deployment, because that
policy goes through the compiler on its way in. If you declare a Route 53 condition in your stack today,
expect the compiler to refuse it whichever tier you are on.
At Infrastructure only your permissions become grants in the target cloud's own IAM at deployment time, and
each cloud carries its own small set of expressible conditions:
| Target | Conditions it can express |
| ------------ | ------------------------------------------------------------------------------------------- |
| Google Cloud | `aws:CurrentTime` with a relational date comparison, as a CEL expression on the binding |
| Azure | `aws:CurrentTime` with a relational date comparison |
| OCI | `aws:CurrentTime`, `aws:RequestedRegion`, `aws:userid`, `aws:username`, `aws:PrincipalType` |
A policy whose conditions fall outside the column that applies does not deploy without the condition. Which
refusal you get follows the same axis: a policy your application submits at runtime fails as a whole document,
and a policy you declare in your stack reaches the widen gate described under
[Accept a broader grant](#accept-a-broader-grant), where the grant is blocked because dropping the condition
would widen it, and deploys only if you accept that widening with `#@iam(compat='widen')`. That is true of a
declared policy on a Max deployment as much as on an Infrastructure-only one, because a declared policy is
compiled either way. The default is the safe direction in both: a condition silently dropped is a grant wider
than the one you wrote.
Every condition key outside the two tables above is refused, including the ones an application is most
likely to use.
Attribute-based access control is unavailable in the Cedar runtime: conditions that depend on
`aws:PrincipalTag`, session tags, `aws:SourceIp`, `aws:PrincipalOrgID` or `aws:SecureTransport` cause the
complete document to fail, as do `aws:PrincipalArn`, `aws:SourceVpc` and service-specific keys such as
`s3:x-amz-acl`. Role tags are stored but are not used during authorization.
Note that OCI's native IAM does express three principal attributes (`aws:userid`, `aws:username` and
`aws:PrincipalType`) when your policy is compiled into its grants. That is not a Cedar capability and it
does not make ABAC available at Max; it is what that one target cloud can say for itself.
The runtime catalog does not contain AWS-managed policy documents. Replace a reference such as `AmazonS3ReadOnlyAccess` with a customer-managed policy that uses supported action forms.
## Cedar runtime authorization
This section describes the Cedar authorization destination: your AWS policies adapted to Cedar and evaluated inside the appliance, whichever cloud that appliance runs in.
At Max, each receiving service adapter verifies the signed AWS request. The principal and resource are synthesized from ARNs in that request and passed to Cedar with the adapted policy set. Cedar applies explicit-deny-wins semantics: a matching deny overrides an allow, and a request with no matching allow is denied.
The request supplies the principal and resource used for authorization. A request that cannot supply either value is denied.
For example, consider a signed `GetObject` request. The receiving S3 adapter verifies the signature, derives the caller and object ARN from the request, and asks Cedar whether the adapted policy allows `s3:GetObject`. A matching deny rejects the call even if another statement allows it. With no matching allow, Cedar also rejects the call.
No directory lookup occurs during this evaluation. Each entity has an ARN attribute, so a policy cannot depend on principal or network attributes that are absent from the request. Actions outside the receiving adapter's service catalog are denied.
Production adapters enforce the decision. Report-only mode is available before cutover: calls that enforcement would deny are recorded and allowed to continue. This setting belongs to each receiving adapter, which lets services move to enforcement independently. If the appliance has not received a policy set, enforcement denies the request.
## Adaptation tiers
The tiers differ in when authorization is decided and whether the application can call the AWS IAM API at runtime.
| | [Max adaptation tier](/byoc/service-adapters/overview#adaptation-tiers) | [Infrastructure only adaptation tier](/byoc/service-adapters/overview#adaptation-tiers) |
| ---------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| IAM administration API | Supported AWS IAM operations are served inside the appliance | IAM administration operations are not served |
| Authorization decision | Cedar, inside the appliance | Target cloud's native IAM |
| Policy location | Adapted policy set in each appliance | Native grants in the target cloud |
| Available targets | Google Cloud, Azure, OCI and Private Kubernetes | Google Cloud, Azure and OCI |
Infrastructure only fits applications whose infrastructure declares all required permissions and that do not administer IAM at runtime. Max is required when the application makes supported AWS IAM administration calls after deployment. It is also required on Private Kubernetes, which has no native IAM to translate grants into.
Tier selection is made from the origin stack and target cloud. The service adapter analysis identifies the services and policy constructs that determine the result.
## Cedar IAM behavior
Everything below applies wherever Cedar is the authorization destination, whichever cloud the appliance runs in. The AWS names in it, such as ARNs and `AssumeRole`, come from the origin model your application still speaks, not from the target cloud.
### Policy synchronization
Each appliance maintains its own policy set. Changes are checked about every 30 seconds, although that interval is not a propagation deadline. There is no fixed upper bound for revocation to take effect.
When the policy source is unavailable, the appliance continues to use its last-known-good policy set and reports that the data is stale. The policy does not expire automatically. A change applied to one appliance has no effect on another.
### Accounts and root credentials
Account IDs in adapted ARNs identify logical accounts within an appliance. The ARN spelling is inherited from the origin model and names nothing in AWS: these do not create AWS accounts or billing relationships, and AWS Organizations policies do not apply.
Each appliance issues one long-lived access key and secret for the logical account root, and shows the secret once. Because this principal has unrestricted access and the IAM API cannot rotate its credential, store it with the controls used for the appliance's most privileged secret.
### API coverage and logging
Each appliance serves 50 origin-model IAM administration operations for roles, customer-managed policies, instance profiles and OIDC providers. It also serves `GetCallerIdentity`, `AssumeRole` and `AssumeRoleWithWebIdentity`. A role's trust policy controls session creation; deleting the role invalidates its sessions.
Allowed calls are absent from the per-request audit log. Diagnostics contain denied calls and report-only findings.
## Cedar IAM limitations
These limitations apply to your AWS policies adapted to Cedar at the [Max adaptation tier](/byoc/service-adapters/overview#adaptation-tiers). They are properties of that adaptation, not of any one target cloud. The [AWS IAM service adapter](/byoc/service-adapters/aws/security-identity/aws-iam) provides operation-by-operation coverage.
| Limitation | Effect |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attribute-based access control | `aws:PrincipalTag`, session tags, `aws:SourceIp`, `aws:PrincipalOrgID` and `aws:SecureTransport` are unsupported. A policy that uses one fails as a complete document. |
| Permissions boundaries | Boundaries are not enforced. Creating a role with one is rejected unless the loss is acknowledged explicitly. |
| AWS-managed policies | Their documents are not supplied by the runtime catalog. Re-author them as customer-managed policies. |
| Resource-based policies | General resource-policy evaluation is unavailable. |
| Organizations SCPs | Service control policies are not enforced. |
| Users, groups, access-key administration and SAML federation | These IAM families are not served. |
| Audit records for allowed calls | Diagnostics do not record each allowed call or identify the matching policy statement. |
| Access Analyzer, credential reports and Access Advisor | These features are unavailable. |
| `SimulateCustomPolicy` | The IAM administration endpoint does not implement this operation. `SimulatePrincipalPolicy` is limited to the workload-identity endpoint, its configured principal and concrete resources. |
`AssumeRole` does not accept role chaining, session policies, `ExternalId` or MFA inputs. A design that depends on `ExternalId` for confused-deputy protection must provide that protection elsewhere.
Cross-account role assumption is supported between configured logical accounts when both the caller's policy and the target role's trust policy allow it. A policy document that names a concrete principal from another AWS account is refused.
## Related topics
* [**Adapter Errors**](/byoc/fundamentals/adapter-errors): Telling an authorization denial apart from a backing-store refusal when a call fails
* [**AWS IAM service adapter**](/byoc/service-adapters/aws/security-identity/aws-iam): Coverage for each supported IAM and STS operation
* [**Permissions Model**](/byoc/fundamentals/permissions-model): Access granted to the Tensor9 BYOC control plane inside a customer's environment
* [**Security Model**](/byoc/fundamentals/security-model): Trust relationships between Tensor9 BYOC, you and your customer
* [**Service Adapters**](/byoc/service-adapters/catalog): Supported services and target-cloud mappings
