Machine Identity
IssuersEnterprise
Registering the platforms that sign your workloads' tokens, and keeping them healthy.
An issuer is a platform that signs tokens for workloads, such as a Kubernetes cluster or GitHub Actions, registered in Multi-Router by its issuer URL. Issuers belong to the account and are managed on the Issuers tab of Machine identity in Account Settings. Multi-Router reads the issuer's signing keys from its discovery document and uses them to check every token.
Registering an issuer
An issuer is registered in five steps:
- Open Settings in the account, then Machine identity, and on the Issuers tab select Register issuer.
- Enter a Display name, such as Production cluster, and the Issuer URL.
- Choose the setting for when the issuer cannot be reached, and the Maximum token lifetime.
- Add the Authorized organizations whose callers will use this issuer.
- Select Fetch keys and register. Multi-Router reads the discovery document and signing keys, and registers the issuer.
The Issuer URL is the token's iss value, such as https://oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE or https://token.actions.githubusercontent.com. Its discovery document at /.well-known/openid-configuration must be reachable over public https and report the same issuer. As the URL is typed, the form shows how Multi-Router classifies it.
Fields
An issuer has these settings:
| Field | Description |
|---|---|
| Display name | A name for the issuer, such as Production cluster. |
| Issuer URL | The issuer, fixed after registration. Trusting a different system means registering it separately. |
| If the issuer cannot be reached | Keep serving with cached keys, the default, or Reject requests. See Key fetching below. |
| Maximum token lifetime (seconds) | Tokens valid for longer than this are refused. The default is 7200, and the maximum 86400 (24 hours). |
| Authorized organizations | The organizations that may create bindings on this issuer, up to 48. |
| Enabled | A disabled issuer stops authenticating its callers within about a minute. |
Token audience
Each issuer receives a token audience when it is registered, a value starting with mr-aud_ shown under Token audience with a Copy button. Workloads request tokens for this audience from their platform, and Multi-Router accepts a token only when it carries the audience. The audience identifies the issuer registration; it is safe to place in configuration such as a pod spec or a workflow file.
Issuer types
Multi-Router classifies each issuer from its URL, which decides how bindings can match subjects:
| Type | Examples | Bindings can |
|---|---|---|
| Cluster | AWS EKS cluster, Google GKE cluster, Azure AKS cluster | Match an exact service account, or every service account in a namespace. |
| Shared platform | GitHub Actions | Match an exact subject, or every run of a named repository. |
| Shared platform | GitLab.com, CircleCI, Google Accounts | Match exact subjects. |
| Custom issuer | Any other issuer | Match exact subjects. |
A shared platform issues tokens for every one of its customers, so bindings on it name a specific repository or subject. A cluster issues tokens only for its own workloads.
Key fetching
Multi-Router keeps the issuer's signing keys, and fetches them again on the first request after they are 10 minutes old, and at once when a token is signed with a new key. The setting for when the issuer cannot be reached decides what happens when a fetch fails:
| Setting | Behavior |
|---|---|
| Keep serving with cached keys | Requests keep being checked with the last keys fetched, for up to 24 hours. A key the issuer revoked stays trusted for that time. |
| Reject requests | Authentication stops until the keys can be fetched again, with the next attempt up to 10 minutes later. |
Health
Each issuer card shows a health badge:
| Badge | Meaning |
|---|---|
| Healthy | Keys are current. |
| Loading keys | Keys are being fetched. |
| Degraded | The last refresh failed, and cached keys are in use. |
| Failed closed | The last refresh failed, and requests are refused. |
| Stale keys expired | The keys were last fetched more than 24 hours ago, such as after a quiet day. The next request fetches them again. |
| Unknown key IDs suppressed | Many tokens used unknown keys, and Multi-Router paused fetching for them. |
Editing, disabling and deleting
Edit changes everything except the Issuer URL. The Enabled toggle on the card turns the issuer off and on, within about a minute. Delete issuer removes the registration permanently once its bindings and organization authorizations are removed; the card says how many remain, and which organizations hold the bindings. An account holds up to 100 issuers.