Add support for mapping AWS root account principals

[AndreKurait]

What

Add a dedicated RootMapping type and rootMap to the file mapper, enabling explicit mapping of AWS root account principals (arn:aws:iam::ACCOUNT:root) to Kubernetes usernames and groups.

Why

Root account principals are already parsed correctly by arn.Canonicalize() — it returns the ROOT principal type and the canonical ARN. The token verification code in token.go also handles root correctly (line 755: if principalType == arn.FEDERATED_USER || principalType == arn.USER || principalType == arn.ROOT).

However, when the identity reaches the mapper, it falls through with ErrNotMapped because:

• roleMap only contains role ARNs
• userMap only contains user ARNs
• There is no rootMap

The only way a root principal can currently authenticate is via AutoMappedAWSAccounts, which grants blanket access to the entire account without explicit mapping control. There is no way to map root to specific Kubernetes groups while excluding other principals from the same account.

Example

mapRoots:
- rootarn: "arn:aws:iam::012345678912:root"
  username: "root-admin"
  groups:
  - system:masters

Changes

• pkg/config/types.go: New RootMapping struct with rootarn, username, groups fields. New RootMappings []RootMapping field on Config.
• pkg/config/mapper.go: Validate(), Matches(), Key(), IdentityMapping() methods on RootMapping, mirroring UserMapping.
• pkg/mapper/file/mapper.go: rootMap field on FileMapper, populated from Config.RootMappings with arn.Canonicalize() validation. Lookup in Map() after role and user lookups.
• Tests: Unit tests for RootMapping methods and end-to-end FileMapper.Map() test covering match, cross-account rejection, and cross-resource-type rejection.

Design

Mirrors the existing UserMapping/userMap pattern exactly:

• Separate struct type (not shoehorned into UserMapping or RoleMapping)
• Separate map in the mapper (exact key lookup, same as userMap)
• arn.Canonicalize() validation at load time
• Checked after roles and users in Map() (root auth is rare, so checked last)

Backward Compatibility

• No changes to existing role or user mapping behavior
• RootMappings defaults to empty — no root mappings unless explicitly configured
• Root principals that previously fell through to AutoMappedAWSAccounts will continue to work via that path (the root map is checked before IsAccountAllowed in doMapping)

Testing

All existing tests pass. New tests:

• TestRootARNMapping — Validate(), Matches(), Key() methods
• TestRootMap — end-to-end through FileMapper.Map() with match, cross-account rejection, cross-resource-type rejection

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: AndreKurait
Once this PR has been reviewed and has the lgtm label, please assign kmala for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

Hi @AndreKurait. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[bryantbiggs]

/ok-to-test

[AndreKurait]

@bryantbiggs Any feedback based on the successful tests?

[bryantbiggs]

Curious about the motivation here — if you have root credentials, you can create any IAM role or user you need, so every case that might seem to require root auth has an alternative (assume a role and use mapRoles, create a user and use mapUsers, etc.). It's hard to think of a scenario where a role or user ARN genuinely won't work.

EKS Access Entries (AWS's own replacement for aws-auth) deliberately excluded root support — root credentials can't be restricted by IAM policies, SCPs, or permission boundaries, so a root principal reaching Kubernetes with system:masters is completely unconstrained at both layers. That seems like an intentional decision to not normalize root as a valid auth path rather than an oversight. What's the use case that motivated this?