Project challenges / verified progress
Beacon: build the ground it stands on

The engineering notebook

Stop carrying keys

How can automation and workloads authenticate without committed long-lived secrets?

Loading Vault account...
Phase 3 — Run and authenticate safely

Step 01 of 06

Understand the idea

Long-lived access keys can be copied, lost, or exposed. Prefer short-lived credentials that are issued only to an approved person or job, for a specific purpose, and expire when they are no longer needed.

TOKEN INSTEAD OF KEYGitLab CI/CDsigned OIDC identityAssume roleshort AWS sessionminutesDeny mismatchrepo or branch wrongno credsAudit trailwho assumed whatCloudTrail
A static key asks defenders to protect one secret forever. Federation asks the cloud to trust a signed statement for one run, one repository and one role. That is a smaller thing to lose.
Step 01

Key technical ideas

A CI access key is a standing invitation

An AWS access key copied into a repository secret can often be used from anywhere until it is rotated. If it leaks, an attacker does not need your pipeline; they need the two strings. Short-lived credentials shrink the useful window. Scoped roles shrink what the credentials can do. Audit logs then show role assumption instead of an anonymous key used from a new IP.

OIDC federation trades secrets for claims

GitLab CI/CD can request an OpenID Connect token signed by GitLab. The cloud identity provider checks claims such as repository, branch, workflow and audience. If they match a trust policy, the job receives temporary credentials for a role. No cloud secret is stored in GitLab. The trust policy becomes the boundary, so write it narrowly.

Workload identity is the same idea inside clusters

Pods sometimes need cloud permissions: read a secret, write an object, call a queue. Mounting a long-lived key as a Kubernetes Secret moves the breach. Workload identity links a Kubernetes service account to a cloud role and issues short-lived credentials to matching pods. The pod gets what it needs without a reusable key sitting in etcd or a container image.

Least privilege is written in verbs

A useful IAM policy says which actions are allowed on which resources under which conditions. AdministratorAccess is not a policy; it is a postponement. Start with read-only where possible, add exact create or update verbs as Terraform errors prove the need, and remove permissions after teardown. The boring work is the control.

A narrow trust policy shape
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/gitlab.com" },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": { "gitlab.com:aud": "sts.amazonaws.com" },
        "StringLike": { "gitlab.com:sub": "project_path:YOUR_NAMESPACE/beacon:ref_type:branch:ref:main" }
      }
    }
  ]
}

The shape matters: audience and subject claims restrict who can assume the role. Replace account, organization and branch with your real values only in a private account.

Static key versus federated role

PropertyStatic keyOIDC role

Stored where

CI secret or laptop

Nowhere long-lived

Lifetime

Until rotated

Minutes to hours

Scope

Often broad

Role policy

Leak impact

Reusable

Usually expires

Technical terms used at work

  • OIDC — OpenID Connect, a standard for signed identity tokens containing claims about a caller.

  • Trust policy — The IAM rule that says who may assume a role and under which claim conditions.

  • Workload identity — A way for workloads such as pods to receive cloud credentials through their runtime identity.

  • Secret manager — A managed service for storing and auditing access to sensitive values outside source code.