policy

package
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (
	Version2008 = "2008-10-17"
	Version2012 = "2012-10-17"
)

Recognized values for a policy document's Version element.

View Source
const AssumeRoleWithWebIdentityAction = "sts:AssumeRoleWithWebIdentity"

AssumeRoleWithWebIdentityAction is the sts action name role trust statements must (directly, or via a wildcard) authorize for AssumeRoleWithWebIdentity to succeed.

View Source
const MaxDocumentLength = 131072

MaxDocumentLength is IAM's parameter-level maximum length for a PolicyDocument value.

View Source
const MaxSessionPolicyBytes = 2048

MaxSessionPolicyBytes is the maximum length, in bytes, of the optional inline session policy document AssumeRoleWithWebIdentity's Policy parameter accepts, matching AWS's documented quota for that parameter.

View Source
const MaxTrustPolicyBytes = 2048

MaxTrustPolicyBytes is IAM's ACLSizePerRole quota: a role has exactly one trust policy, so unlike inline identity policies (which sum across all of a user's/role's named policies) this is a plain length check against the single AssumeRolePolicyDocument/PolicyDocument value.

Variables

This section is empty.

Functions

func Parse

func Parse(raw string) error

Parse parses raw as an IAM policy document and checks it against IAM policy grammar

func ParseTrust

func ParseTrust(raw string) error

ParseTrust parses raw as an IAM role trust-policy document (the value of AssumeRolePolicyDocument / UpdateAssumeRolePolicy's PolicyDocument) and checks it against trust-policy grammar: Principal is required (the opposite of an identity policy), Action/NotAction values must carry the "sts:" prefix, and Resource/NotResource are forbidden.

func Validate

func Validate(field, raw string) error

Validate checks raw against IAM's parameter-level constraints for a PolicyDocument value: a maximum length of 131072 and the allowed character set (tab/LF/CR plus printable Latin-1, U+0020-U+00FF, with at least one such character present — so an empty value is rejected here too, as a charset violation).

Types

type Decision

type Decision int

Decision is the tri-state result of evaluating a set of identity policy documents. A caller combining this with another policy source (e.g. an S3 bucket policy) needs this distinction, not a plain bool, to implement AWS's real cross-policy precedence: an explicit Deny from either source wins outright over an Allow from the other, but a NoMatch from one source leaves the other free to grant access on its own.

const (
	// DecisionNoMatch means no statement in any document matched reqCtx at
	// all — neither an Allow nor a Deny.
	DecisionNoMatch Decision = iota
	// DecisionAllow means at least one statement matched with Effect Allow,
	// and no statement matched with Effect Deny.
	DecisionAllow
	// DecisionDeny means a statement matched with Effect Deny, or the
	// evaluation failed closed (unparseable/invalid document, or a
	// Condition that couldn't be evaluated).
	DecisionDeny
)

func EvaluateIdentityPolicies

func EvaluateIdentityPolicies(documents []types.PolicyEntry, reqCtx RequestContext) Decision

EvaluateIdentityPolicies reports how documents (each a user's or role's inline policy entry) decide reqCtx, using IAM's evaluation semantics: a statement must cover the action, the resource, and (if present) its Condition block to be considered at all; a matching explicit Deny statement makes the whole evaluation DecisionDeny regardless of any Allow found elsewhere (in the same or another document); absent an explicit deny, at least one covering Allow statement is required for DecisionAllow — an identity with no matching statement at all gets DecisionNoMatch, not DecisionAllow.

A document that fails to parse, or a statement whose Condition block can't be evaluated, returns DecisionDeny rather than being skipped: PutUserPolicy/PutRolePolicy already reject any policy document that wouldn't parse or whose Condition uses an unrecognized operator, so this only matters for documents written before that validation existed - and for exactly that legacy-data case, we can't rule out a hidden Deny inside the part we can't evaluate, so the safe outcome is to deny rather than silently proceed as if it wasn't there.

type Document

type Document struct {
	Version   string
	Statement []Statement
}

Document is a parsed AWS IAM policy document.

func (*Document) UnmarshalJSON

func (d *Document) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts Statement as either a single JSON object or an array of objects, matching the AWS IAM policy grammar. A missing or JSON-null Statement leaves Document.Statement nil rather than erroring here — Validate reports that as a grammar error so all "empty document" shapes produce the same message.

func (Document) Validate

func (d Document) Validate() error

Validate checks d against IAM policy document grammar: a valid Version if present, a non-empty Statement (single object or array), document-wide unique Sids, and per statement, the rules enforced by Statement.Validate.

func (Document) ValidateTrust

func (d Document) ValidateTrust() error

ValidateTrust checks d against IAM's trust-policy document grammar: a valid Version if present, a non-empty Statement (single object or array), document-wide unique Sids, and per statement, the rules enforced by Statement.ValidateTrust.

type ProviderLookup

type ProviderLookup func(federatedArn string) (url string, ok bool)

ProviderLookup resolves a Federated principal ARN to the scheme-stripped Url of the OIDC provider it names, reporting ok=false for any ARN that doesn't correspond to a provider that actually exists.

type RequestContext

type RequestContext struct {
	// Action is the "<service>:<Action>" string being authorized, e.g.
	// "iam:GetRole".
	Action string
	// Resource is the ARN of the specific resource the action targets
	// (e.g. a role's own Arn for GetRole, or "*" for an action AWS
	// classifies as resource-less, such as a List action).
	Resource string
	// Condition is the "aws:<GlobalKey>"-keyed context (aws:SourceIp,
	// aws:username, aws:PrincipalArn, aws:userid, ...) a statement's
	// Condition block is evaluated against.
	Condition map[string][]string
}

RequestContext carries the request-scoped values an identity-policy statement is evaluated against, matching AWS's treatment of authorization as a full request-context decision (action, resource, and condition — principal is already fixed by which documents are passed in) rather than the action name alone.

type Statement

type Statement struct {
	Sid          string
	Effect       string
	Action       StringOrSlice
	NotAction    StringOrSlice
	Resource     StringOrSlice
	NotResource  StringOrSlice
	Principal    json.RawMessage
	NotPrincipal json.RawMessage
	Condition    json.RawMessage
}

Statement is a single element of a policy document's Statement list.

func (Statement) Validate

func (s Statement) Validate() error

Validate checks s against IAM policy statement grammar: a valid Effect, no Principal/NotPrincipal, an Action or NotAction (not both) with vendor-prefixed values, a Resource or NotResource (not both) with ARN-shaped values, and - if present - a Condition block whose operators are all recognized (condition *keys* and operand *values* are deliberately not validated here, matching AWS behavior).

func (Statement) ValidateTrust

func (s Statement) ValidateTrust() error

ValidateTrust checks s against IAM trust-policy statement grammar: a valid Effect, a required Principal (never NotPrincipal), an Action or NotAction with only "sts:"-prefixed values, no Resource/NotResource, and - if present - a Condition block whose operators are all recognized (see condition.ShapeValid, shared with the identity-policy side; condition *keys* and operand *values* are deliberately not validated here, matching AWS behavior).

type StringOrSlice

type StringOrSlice []string

StringOrSlice decodes a JSON value that may be either a single string or an array of strings, matching the AWS IAM policy grammar for Action, NotAction, Resource, and NotResource. A JSON-null value decodes to a nil StringOrSlice, identical to the key being absent.

func (*StringOrSlice) UnmarshalJSON

func (s *StringOrSlice) UnmarshalJSON(data []byte) error

type WebIdentityContext

type WebIdentityContext struct {
	ProviderURL string
	// Audience is the token's effective audience: azp when present,
	// otherwise the token's single aud value. Mapped to <provider-url>:aud.
	Audience string
	// OriginalAudience is the token's actual aud claim value(s), only ever
	// set when azp is present (and therefore differs from Audience) —
	// mapped to <provider-url>:oaud. This matters for Google hybrid
	// clients, where aud names the backend project and azp names the
	// actual OAuth client that requested the token.
	OriginalAudience []string
	Subject          string
	// Claims holds every other top-level string/string-array claim from
	// the token, for Condition keys beyond aud/sub (e.g. a custom "amr"
	// or "groups" claim). Values are pre-normalized to []string.
	Claims map[string][]string

	// SourceIP is the caller's address, mapped to aws:SourceIp.
	SourceIP string
	// Secure is whether the connection is TLS, mapped to
	// aws:SecureTransport - AWS documents this key as present on every
	// request, not just TLS ones.
	Secure bool
	// Now is the request's evaluation time, mapped to aws:CurrentTime and
	// aws:EpochTime.
	Now time.Time
	// RoleSessionName is the caller-supplied RoleSessionName parameter,
	// mapped to sts:RoleSessionName.
	RoleSessionName string
}

WebIdentityContext carries the token values needed to evaluate a trust statement's Condition block, keyed the way AWS's own condition context keys are: "<provider-url>:<claim-name>".

type WebIdentityMatch

type WebIdentityMatch int

WebIdentityMatch is the outcome of evaluating a role's trust policy against an authenticated web identity federation attempt. The distinct NoPrincipal/NoIssuerMatch/ConditionFailed cases exist because AWS reports two different errors depending on which one occurs: NoPrincipal (no Federated principal in the trust policy resolves to a provider that actually exists) is reported as AccessDenied identically to a nonexistent role, while NoIssuerMatch and ConditionFailed (an existing, referenced provider's signing keys and claims were checked and didn't satisfy the request) are both reported as InvalidIdentityToken.

const (
	NoPrincipal WebIdentityMatch = iota
	NoIssuerMatch
	ConditionFailed
	ExplicitlyDenied
	Allowed
)

func EvaluateWebIdentityTrust

func EvaluateWebIdentityTrust(document string, lookup ProviderLookup, wctx WebIdentityContext) (WebIdentityMatch, string)

EvaluateWebIdentityTrust evaluates document (a role's AssumeRolePolicyDocument) against wctx, resolving each statement's Federated principal(s) via lookup.

The evaluation order mirrors AWS's observed behavior: first, whether any statement's Federated principal resolves to a provider that actually exists (regardless of whether its Url matches the token) determines NoPrincipal vs the later cases; only among statements whose provider exists AND whose Url matches wctx.ProviderURL does the token's Condition get evaluated. An explicit Deny statement matching the same provider, action and condition overrides an otherwise-matching Allow.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL