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.

Last updated 18 November 2026View as Markdown

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 the ews-instance helper; 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) and exp, 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).

Did this page help you?