Skip to content

0014 Tokens from an external issuer

Sources: #487, the decision on #487

Context and Problem Statement

PowerShell Universal knows who is signed in to it. It should hand that person a short-lived pivotkit token without a sign-in provider. How does pivotkit-server accept such tokens, and how much may they carry?

Considered Options

  • An HMAC key shared with the other system.
  • An Ed25519 key pair: the other system holds the private key, pivotkit only the public one.
  • The other system's tokens carry what they claim: every scope without a scope claim, any configured profile.
  • The other system's tokens are capped by what the operator allows for that issuer.

Decision Outcome

Chosen options: the Ed25519 key pair, with caps per issuer.

  • auth.externalIssuers names the issuer, its token type and one or two public keys.
  • Each issuer is checked with its own name, type and keys only.
  • scopes is required. A token's scope is cut to it, and a token without scope gets exactly that list, never every scope.
  • profiles lists the profiles a token may name. Any other gets 401. profile is the issuer's profile for a token that names none, else auth.defaultProfile.
  • A token always resolves to a profile the operator chose. A configuration without the issuer's profile and without auth.defaultProfile is refused. The sources' own policy never applies.
  • These tokens get no links or uploads bound to a sign-in, and token exchange stays refused.
  • There is no deny list. maxMinutes caps a token's lifetime (default 60, at most 1440).
  • The tokens carry no audience.

Why the key pair: #487 prefers it, so pivotkit can never mint tokens for the other system.

Why the caps: the other system is a sign-in provider, not an operator. Its tokens never get more than the operator allowed it.

Why there is no deny list and no audience: the tokens are kept short (maxMinutes) instead.

Not decided

  • The PowerShell Universal side: the function that mints the tokens.
  • Key rotation beyond two keys per issuer.
  • Limits per person.

Consequences

  • A leaked token works until it expires, at most maxMinutes.
  • Every pivotkit-server that trusts the same public key accepts the same token.
  • A stolen private key of the issuer makes tokens for any person, within the issuer's scopes and profiles.
  • Operators keep maxMinutes low and give each issuer only the scopes and profiles it needs.
  • 0009 and 0010 cover the tokens the server signs itself.