Prove an instance's identity
Let a machine prove who it is to a third party with a short-lived signed token, for one audience, without sharing any secret.
The identity secret proves a machine to Deutsche Cloud and never leaves it. To prove itself to someone else (a function of yours, Vault, your own service), the machine asks for an identity token: a JWT signed by Deutsche Cloud (RS256), valid five minutes, for one audience it names.
Prerequisites
- A running instance. Every instance gets an identity at launch (a secret in
/etc/ews/instance-identity, readable by root only) and theews-instancehelper; the identity stops working when the instance is terminated. No instance role and no IAM permission are needed.
Get a token on the machine
TOKEN=$(ews-instance token https://my-service.example.com)
curl -H "Authorization: Bearer $TOKEN" https://my-service.example.com/The audience may contain letters, digits and . _ : / -; anything else is refused by the helper
before it asks.
Verify it at the receiver
Verify it like any OIDC token:
- Issuer:
https://console.platform-development.deutschecloud.app/api/instance/v1. Keys at…/api/instance/v1/jwks, discovery at…/api/instance/v1/.well-known/openid-configuration. - A function reaches the API only through
$DCLOUD_API_URL; it reads the same keys at$DCLOUD_API_URL/ec2/api/instance-identity/jwks(public, no key needed). - Check
iss,aud(your own name, so a token meant for another service is worthless to you) andexp, then the claims you trust:
| Claim | Value |
|---|---|
sub |
instance:i-… |
org_id |
Your organization's id |
instance_id |
i-… |
region, zone |
For example de1, de1a |
image_id |
The machine image (ewi-…) or catalog image it booted from |
role |
The instance role's name, or null |
autoscaling_group_id |
asg-… when it belongs to an auto scaling group, else null |
launch_template_id |
The group's launch template, else null |
lifecycle_state |
Its state in the group, else null |
Every claim is always present (null when it does not apply), so a check like
autoscaling_group_id == "asg-…" never passes by a missing claim. Tags are not claims. The tokens
are signed with keys of their own: they never verify against the Deutsche Cloud CI OIDC keys, nor the
other way round.
Result
Each token issued is in the audit log (ec2:GetInstanceIdentityToken, with the audience).