multi-router.aidocs

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:

  1. Open Settings in the account, then Machine identity, and on the Issuers tab select Register issuer.
  2. Enter a Display name, such as Production cluster, and the Issuer URL.
  3. Choose the setting for when the issuer cannot be reached, and the Maximum token lifetime.
  4. Add the Authorized organizations whose callers will use this issuer.
  5. 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:

FieldDescription
Display nameA name for the issuer, such as Production cluster.
Issuer URLThe issuer, fixed after registration. Trusting a different system means registering it separately.
If the issuer cannot be reachedKeep 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 organizationsThe organizations that may create bindings on this issuer, up to 48.
EnabledA disabled issuer stops authenticating its callers within about a minute.

Token audience

example-co · acc_7Tq2Wd9KxP

Account Settings

Machine identity

Let applications authenticate with tokens their own platform issues, instead of an API key.

Register issuer
Issuers1Bindings0
Production clusterHealthyhttps://oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
Token audience
mr-aud_PtYgjmUhBel31iEl2hpChYgCfrL1spNxnyVmihA_2O7Copy

Put this in the pod spec. Tokens from this issuer are only accepted if they carry it.

Issuer type
AWS EKS cluster
If the issuer cannot be reached
Keep serving with cached keys
Maximum token lifetime
7,200 seconds

Authorized organizations

Only authorized organizations can create bindings on this issuer.

Engineeringorg_3Fh8Wq2LdK

Bindings using this issuer

2 bindings across 1 organization. Read-only — bindings are created and deleted inside each organization.

system:serviceaccount:payments:apiEngineering · mib_7Hn2Qw5RtX
system:serviceaccount:billingEngineering · mib_K4vB9mZp3L
Delete issuer Edit
A registered EKS cluster issuer: its token audience, settings, authorized organization and the bindings that use it. Select to enlarge.

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:

TypeExamplesBindings can
ClusterAWS EKS cluster, Google GKE cluster, Azure AKS clusterMatch an exact service account, or every service account in a namespace.
Shared platformGitHub ActionsMatch an exact subject, or every run of a named repository.
Shared platformGitLab.com, CircleCI, Google AccountsMatch exact subjects.
Custom issuerAny other issuerMatch 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:

SettingBehavior
Keep serving with cached keysRequests keep being checked with the last keys fetched, for up to 24 hours. A key the issuer revoked stays trusted for that time.
Reject requestsAuthentication 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:

BadgeMeaning
HealthyKeys are current.
Loading keysKeys are being fetched.
DegradedThe last refresh failed, and cached keys are in use.
Failed closedThe last refresh failed, and requests are refused.
Stale keys expiredThe keys were last fetched more than 24 hours ago, such as after a quiet day. The next request fetches them again.
Unknown key IDs suppressedMany 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.

OverviewBindings
Was this helpful?