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
scopeclaim, 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.externalIssuersnames the issuer, its token type and one or two public keys.- Each issuer is checked with its own name, type and keys only.
scopesis required. A token'sscopeis cut to it, and a token withoutscopegets exactly that list, never every scope.profileslists the profiles a token may name. Any other gets 401.profileis the issuer's profile for a token that names none, elseauth.defaultProfile.- A token always resolves to a profile the operator chose. A configuration without the issuer's
profileand withoutauth.defaultProfileis 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.
maxMinutescaps 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
maxMinuteslow and give each issuer only the scopes and profiles it needs. - 0009 and 0010 cover the tokens the server signs itself.