# 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 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

```sh
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).

## Related

- [Give an instance a role](give-an-instance-a-role.md)
