Machine Identity
OverviewEnterprise
Letting workloads call Multi-Router with the identity their own platform gives them, in place of a stored API key.
Machine identity lets an application authenticate to Multi-Router with a short-lived token its own platform issues, such as a Kubernetes service account token or a GitHub Actions OIDC token, instead of an API key stored as a secret. The platform signs the token, Multi-Router checks the signature and the token's subject on every request, and the caller reaches only the routers its binding allows. The platform's own short-lived tokens are the only credential, so there is nothing for the team to store or rotate.
Issuers and bindings
Machine identity has two parts, each set on the Machine identity page in Settings:
| Part | Belongs to | Purpose |
|---|---|---|
| Issuer | The account | A platform that signs tokens, such as an EKS cluster or GitHub Actions, registered by its issuer URL. Each issuer gets a token audience that its tokens must carry. |
| Binding | An organization | A caller, identified by the token's subject such as system:serviceaccount:payments:api, and the routers it may use. |
An issuer is registered once for the account and authorized for the organizations that may bind callers to it. Each organization then creates bindings for its own callers and routers.
How a request is authenticated
Every machine request is checked in four steps:
- The workload asks its platform for a token for the issuer's token audience, and sends it as
Authorization: Bearer. - Multi-Router finds the issuer by the audience, and checks the token's issuer, signature, expiry and lifetime.
- It finds the binding that matches the token's subject, and checks that the binding allows the router the request names.
- The request is served by that router, and Traffic records the issuer, subject and binding.
Machine identity and API keys
Machine identity and API keys both authenticate callers, for different kinds of caller:
| API key | Machine identity | |
|---|---|---|
| Credential | A long-lived sk-mr- key stored as a secret | A short-lived token the platform issues on demand |
| Rotation | Replace the key | Automatic, as the platform issues new tokens |
| Reach | Chosen scopes and routers | Inference, and optionally listing models, on the binding's routers |
| Identity in Traffic | The key id | The issuer, subject and binding |
| Suited to | Scripts, tools, and applications on other platforms | Workloads in Kubernetes clusters and CI jobs |
Supported platforms
Machine identity works with any issuer that publishes an OpenID Connect discovery document and signing keys at a public https address:
| Platform | Issuer type in the dashboard | Subjects |
|---|---|---|
| Amazon EKS cluster | AWS EKS cluster | Kubernetes service accounts, exact or by namespace |
| Google GKE cluster | Google GKE cluster | Kubernetes service accounts, exact or by namespace |
| Azure AKS cluster, with its OIDC issuer turned on | Azure AKS cluster | Kubernetes service accounts, exact or by namespace |
| GitHub Actions | GitHub Actions | Workflow runs, exact or by repository |
| GitLab.com | GitLab.com | Exact CI job subjects |
| CircleCI | CircleCI | Exact CI job subjects |
| Google Accounts | Google Accounts | Exact subjects |
| Any other OpenID Connect issuer | Custom issuer | Exact subjects |
Related topics
The other pages in Machine Identity cover each part in detail:
| Page | Covers |
|---|---|
| Issuers | Registering issuers, token audiences, key fetching and health. |
| Bindings | Subjects, matching, routers and permissions. |
| Kubernetes | Calling Multi-Router from a pod with a service account token. |
| GitHub Actions | Calling Multi-Router from a workflow with an OIDC token. |
| Calling Multi-Router | Token requirements, router selection, limits and Traffic. |
| Troubleshooting | Authentication errors, with causes and fixes. |