Workload identity

A service on Helm7 can prove who it is to another system without holding a long-lived key for it. It asks Helm7 for a token, names the system it is for, and that system checks the token against keys Helm7 publishes.

Tokens last 10 minutes. Each one is for a single audience, so a token meant for one system is useless to another.

Set up the other side

In the system that will accept the token, add Helm7 as an OIDC issuer. It needs only the issuer URL; the rest is found from discovery. Then write the rule against the subject, so only the service you mean can use it.

# issuer https://www.helm7.com

# discovery https://www.helm7.com/.well-known/openid-configuration

# keys https://www.helm7.com/.well-known/jwks.json

# subject helm7:org:org_xxxxxxxxxxxxxxxxxxxx:product:inkrobin:environment:production:service:web

Ask for a token

Every service started after this shipped gets three variables. Redeploy an older service to pick them up. They are set after your own variables, so one you define under the same name is ignored.

HELM7_OIDC_TOKEN_URL: Where the service asks for a token.
HELM7_OIDC_REQUEST_TOKEN: The credential it asks with. Specific to the running deployment.
HELM7_OIDC_ISSUER: The issuer the tokens carry, for the other system to trust.

# from inside the service

curl -s -X POST "$HELM7_OIDC_TOKEN_URL" \

-H "Authorization: Bearer $HELM7_OIDC_REQUEST_TOKEN" \

-H "Content-Type: application/json" \

-d '{"audience":"https://api.example.com"}'

The response has token, expires_at and expires_in. Keep the token until shortly before it expires and ask again then; the endpoint allows 120 requests a minute per deployment. A GET with ?audience= works too.

What the token says

iss: https://www.helm7.com
sub: helm7:org:<organization id>:product:<slug>:environment:<name>:service:<name>
aud: The audience the service asked for.
product, environment, service: The same names, as separate claims.
organization_id, product_id, service_id, deployment_id: The stable ids.

Rules worth knowing

A credential works only while its deployment is starting or live. Redeploying or deleting the service retires it.
The subject starts with your organisation id, so another organisation using the same names cannot match your rule.
Renaming a product, environment or service changes the subject, so a rule written against the old one stops matching. That fails closed.
The token endpoint is /oidc/token. It is not an API operation, because the caller is a running service and holds no API key.
A control plane without a signing key answers 503 on discovery and on the token endpoint, with what to set.