Policy reference

[!caution]

This service is not deployed. There is no iam.shelfcs.com or sts.shelfcs.com in the published endpoint list, and no call on this page will answer. This page is the specification, not a description of something running.

For the identity system that does exist — the identity service users, one project, one role, and EC2 access keys — read Identity, as deployed.

Objective

This page is the most consequential in the whole v1 documentation set. Every service’s actions have to be nameable in a policy on the day that service ships, so the naming scheme is decided once, here, and never changed.

Document structure

PROPOSED: the AWS IAM policy JSON document structure, unchanged, so that existing policies and existing policy tooling work.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowReadOnlyEC2",
      "Effect": "Allow",
      "Action": ["ec2:DescribeInstances", "ec2:DescribeImages"],
      "Resource": "*"
    }
  ]
}

Action naming

An action is <service>:<ActionName>, where the service prefix is the same string used in the endpoint host and in the SigV4 credential scope. One string, three places, always identical.

PROPOSED: v1 service prefixes — iam, ec2, account, billing.

Prefixes for services that do not exist yet are reserved now: s3, elb, rds, ecr, sqs, logs, route53, acm, secretsmanager, kms. They are reserved so that a future service cannot be forced into a name that clashes with an existing one, and so that AWS-compatible policies keep working when the matching service arrives.

Wildcards are permitted in actions: ec2:Describe*, ec2:*, *.

Resource matching

Resources are matched by ARN, with * and ? wildcards permitted in any segment.

arn:aws-shelf:ec2:hel1:123456789012:instance/*
arn:aws-shelf:ec2:*:123456789012:instance/i-0a1b2c3d4e5f60718

An action that operates on no particular resource — a list across the account, for example — is documented per action as requiring Resource: "*", and the per-action page states it explicitly. Guessing which actions are resource-scoped is the single largest source of policy mistakes, so every action page carries the answer.

Evaluation

1. An explicit Deny in any applicable policy denies the request.
2. Otherwise, an Allow in any applicable policy allows it.
3. Otherwise, the request is denied.

There is no implicit allow, for anyone, including the account owner.

OPEN (Michael): whether the account owner, or a root credential, bypasses policy evaluation. AWS’s root user does. A design where nothing bypasses policy is safer and is also a way to lock an account out of itself permanently. Both positions are defensible; the decision must be made before the first policy is written.

Conditions

OPEN (Michael): whether condition keys exist in v1, and which. Conditions are how customers express “only from this address” and “only with MFA”. They are also a large surface. Shipping a policy engine without conditions and adding them later is safe; shipping them incompletely is not.

Implementation

PROPOSED: the policy engine is Cedar rather than hand-rolled. Cedar is an open-source policy language with a Go implementation, designed for exactly this evaluation model, and it removes the risk of a hand-written evaluator that subtly disagrees with itself between services.

If Cedar is chosen, the AWS-shaped policy document is translated into Cedar at write time, and the translation is part of the contract: a policy that cannot be translated must be rejected at creation, never silently accepted and evaluated differently.

Go further

• Shelf Cloud API conventions
• Shelf Cloud API Reference