Documentation
¶
Index ¶
Constants ¶
const ( Version2008 = "2008-10-17" Version2012 = "2012-10-17" )
Recognized values for a policy document's Version element.
const AssumeRoleWithWebIdentityAction = "sts:AssumeRoleWithWebIdentity"
AssumeRoleWithWebIdentityAction is the sts action name role trust statements must (directly, or via a wildcard) authorize for AssumeRoleWithWebIdentity to succeed.
const MaxDocumentLength = 131072
MaxDocumentLength is IAM's parameter-level maximum length for a PolicyDocument value.
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.
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 ParseTrust ¶
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 ¶
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 ¶
Document is a parsed AWS IAM policy document.
func (*Document) UnmarshalJSON ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.