Sovereign Signing Guide
Step-by-step setup for out-of-band JWT signing with external agents
What is Sovereign Signing?
For an application in a signing pool, Orion builds each token and an agent on a host you control signs it. The Orion server never possesses the private key.
If the Orion server or its database is compromised, that gives you three things:
- The key cannot be copied, so the compromise ends when the access ends
- Every token signed is in the agent's own log, outside Orion
- The agent refuses what its own policy does not allow: an application it does not sign for, a token that lives too long
It does not mean that no token can be obtained while Orion is compromised. An agent signs what Orion asks it to sign, within its policy. The policy and the log are what narrow that, so set both (Step 4).
Use sovereign signing when:
- You need token signing authority physically separated from the identity server
- You want agents to enforce their own policy before signing
- Compliance requires hardware-isolated signing keys (HSM, secure enclave)
How it works
Browser login: User logs in normally → Orion shows a brief "Authorizing..." spinner → an external agent receives the unsigned token, signs it with its private key, and submits it back → user is redirected with a valid auth code. Token exchange is instant (the token is pre-signed).
Machine-to-machine: Client calls the token endpoint → Orion signals the agent →
agent signs within seconds → token returned. If the agent doesn't respond within the timeout, the client
gets authorization_pending and can retry. If the agent refuses the token (its own policy does not
allow it), the client gets access_denied with the agent's reason, and retrying gets the same answer.
Which tokens: the agent signs the application's access tokens. ID tokens, and the tokens of the device-code grant, are still signed with the organisation's own key.
A pool, the root certificate its keys must chain to, an agent that brings its own
key, and then the application. Pools, trust anchors and agents are managed at
/sovereign/manage/{your-org}/pools. The agent is the SDK's SovereignAgentRunner,
hosted in a service of yours (Step 4). The certificate for the agent's key comes from your own certificate
authority: Orion works with any that can issue for a key the agent holds, and never holds that
authority's key or the agent's.
Registering a key by hand with an API key still works and is described further down.
1 Create a Signing Pool
Go to /sovereign/manage/your-org/pools and use the "Create Pool" form. A pool is a named group of
agents. Several agents can be in one pool, each with its own key, and any of them can sign: that is how you
get redundancy.
The pool's id (main-pool in this guide) is part of the address its keys are published at, and is what applications name in their configuration.
2 Give the Pool Its Trust Anchor
On the pool's page, under Trust Anchors, paste the root certificate (PEM) of the certificate authority that will issue your agents' certificates. It is the same root your applications pin in Step 6.
With an anchor set, Orion accepts a key only with a certificate chain that ends at it. A key your applications would refuse is then refused when it is published, with the reason, and the pool's page shows when each certificate expires. The anchor is there so that mistakes show early. It is not what protects your applications: that is the root they pin themselves, which Orion cannot change.
When the root has other authorities under it
A root accepts every certificate under it, whichever of its authorities issued it. If your root also has an authority for web servers, or for devices, a certificate from one of those chains to the root just as an agent's does. Paste the certificate of the authority that issues your agents' certificates as well, after the root or together with it: the list then shows a Root and an Issuing authority, and the pool accepts only certificates that authority issued. One the root issued itself, or one from another authority under it, is refused, however its chain is presented. Your applications name the same authority in Step 6.
- An issuing authority narrows a root and never replaces it, so it is accepted only under a root the pool has, and that root cannot be removed while the authority is named: remove the authority first.
- The match is on the authority's own certificate. When that certificate is replaced, add the new one beside the old and remove the old once every agent has a certificate from the new one.
- Anchors are checked when a key is published. A key already in the pool stays until its agent next publishes, which it does at every renewal.
3 Register the Agent
On the pool's page, under Register Agent, give the agent an id and tick The agent brings its own key. You get a one-time enrolment code in place of an API key. No secret that lasts is copied between machines, and the private key is made where it will be used.
- The code is shown once and works once.
- It expires after 15 minutes unless the server sets
ORION_DEVICE_ENROLLMENT_TTL_MINUTES. If it lapses before the host has used it, New enrolment code beside the agent on the pool's page gives it another, and every earlier code for the agent stops working. - The agent is in the pool from now on, but signs nothing until it has published a key.
4 Run the Agent
The agent is SovereignAgentRunner in the SDK package Clashawaun.Orion.Sdk.NetCore
(1.0.280 or later). It is a library with no command line and no console: host it in a service of yours, give
it the key and the certificate, and it does the rest.
What it does when it starts:
- 1. Redeems the enrolment code as a device and keeps that identity in its own directory (
~/.orion/sovereign-agentby default). It never needs the code again, and authenticates from then on with its device certificate. - 2. Publishes the public half of its key with the certificate chain. In a pool with trust anchors, Orion checks the chain here.
- 3. Waits for work. Orion holds each request for work open until a token needs signing, so there is no polling delay to tune.
RunAsync returns when the token is cancelled. It ends by itself in two cases only, both a
SovereignAgentConfigurationException: the options cannot be used, or Orion refused the credential
the first time it was presented. Orion being down, a key Orion will not take yet, a certificate that is not
there yet: all of these are waited out. runner.Status says what it is doing.
The key
ISovereignSigner is the key: its public half, its algorithm (RS256) and "sign these
bytes". The runner never asks for the private key. PemKeySovereignSigner reads a key file, which
holds the key in the clear. On a host with a hardware security module, implement the three members over the
module and the key never enters the process. Every signature is checked against the published public key
before it leaves the agent.
The certificate
ISovereignCertificateSource returns the key's current certificate chain, leaf first. The runner
asks when it starts and every five minutes, and publishes again when the answer changes, so a renewal only has
to start returning the new chain. FileSovereignCertificateSource reads a file that something else
keeps current. A source can also obtain and renew the certificate itself from your certificate authority.
The policy
The agent judges the exact bytes it is asked to sign, never the request around them. It will not start with no
application listed, unless AllowAnyClient is set.
- Applications: every audience of the token, and its client, is in
AllowedClients - Issuer:
issishttps://login.shanecraven.com/oauth/your-org(setIssuerif Orion issues under another address) - Lifetime: the token expires, and lives no longer than
MaximumTokenLifetime(one hour) - Header: names this agent's key and algorithm and nothing unexpected
- Rate: a warning above
SignaturesPerMinuteAlert(120), a refusal aboveSignaturesPerMinuteLimit(none unless set)
A refusal goes back to Orion with its reason: a client at the token endpoint gets access_denied
and that reason, and a person signing in sees it on the waiting page.
The signing log
With SigningLog set, every signature is recorded before it is released, and one that cannot be
recorded is discarded. FileSovereignSigningLog appends one JSON line for each decision, with the
application, the subject, the token's id and expiry, and the SHA-256 of what was signed. A token found in use
with no line in the log was not signed by this agent.
The SDK's repository also has orion-sovereign-agent, a console tool in front of the same runner
for a host with a key file, and docs/sovereign-agent.md, the full guide to all of this.
5 Put an Application in the Pool
Do this once the pool's page shows the agent's key. From the moment an application is in a pool, every access token for it waits for an agent.
On the application's page
Open the application, and in its OAuth settings choose the pool under Sovereign signing pool.
Or by environment variable (takes precedence)
AllowedClients first:
an agent refuses tokens for an application it was not told about.
6 Configure the Relying Application
An application decides which keys it accepts from its own configuration. Orion serves the pool's keys and their certificate chains, and cannot add one that passes this.
Pin the root (recommended)
- Trusted roots. A key is accepted only when its certificate is for exactly that key and chains to one of these roots, through the certificates published with it. A thumbprint is the SHA-256 of the root certificate, as the pool's Trust Anchors list prints it.
- Trusted issuers (SDK 1.0.310 or later). A root accepts every certificate under it. Name the authority that issues your agents' certificates and a key is accepted only when that authority is in its chain, above the key's own certificate: one the root issued itself, or one from another authority under it, is refused, and so is one that merely publishes the authority's certificate beside its own. Issuers narrow the roots and need one: with an issuer and no root the application refuses to start, and nothing is accepted. The match is on the authority's own certificate, so while it is being replaced, name the old and the new.
- Required usage. Set it. One root usually issues for many purposes, and without this any certificate it issued for an RSA key is a token-signing certificate: a web server's, a device's.
- Revocation. Off unless set. A revocation is seen when the cached revocation list expires, not when it is published, so how fast a revoked agent stops being accepted is decided by how long your authority's lists are valid.
With the root pinned, renewing an agent's certificate, replacing its key and adding an agent need no change in any application.
Thumbprint pinning (no certificate authority)
Embedded key (maximum isolation, no JWKS fetch)
See the SDK Integration page for all validation options.
7 Renewal and Rotation
An agent that brings its own key renews and rotates by publishing again. The runner does it by itself when its certificate source returns a new chain, or it is started with a new key.
- A new certificate for the same key keeps the key id. Nothing changes for applications.
- A new key gets a new key id (the RFC 7638 thumbprint of the key). The old key stays in the pool's JWKS for 24 hours, so tokens it signed still verify.
- Applications that pin the root need no change for either. Applications that pin thumbprints need the new one added before the new key signs.
- To retire an agent, deactivate it on the pool's page. Its key leaves the pool's JWKS.
The pool's page shows when each agent's certificate expires. An agent whose certificate has expired refuses to sign, so renew before then: a source that renews for itself should start well ahead.
Registering a Key by Hand
The older way, which still works: you make the key pair, register the public half as an administrator, and the agent authenticates with an API key. Use it for an agent that cannot enrol as a device. In a pool with trust anchors the key needs a certificate chain here too.
On the pool's page, register the agent without ticking "The agent brings its own key": paste
agent-public.pem and, if you have one, the certificate chain (leaf, then intermediates, then
root). You get an API key, shown once, and the key id main-pool-v1. The same can be scripted by an
organisation administrator's signed-in session:
webhookUrl— optional. Orion POSTs to it when a signing request is created. It must be an https address on a public host.keyId— optional. Defaults to{poolId}-v{version}.
Give the runner ApiKey in place of EnrolmentCode. To rotate, register a second
agent with the new key, switch the agent's host to it, and deactivate the first after a grace period: both
keys are served in the pool's JWKS meanwhile.
SovereignAgentClient is the SDK's earlier agent: a key file, an API key and a callback, with no
policy and no signing log. It still works. Prefer the runner.
The Agent Protocol (Any Language)
The runner is this protocol. An agent written in another language speaks it directly, under
https://login.shanecraven.com/oauth/your-org/sovereign/agent, authenticating each call with
Authorization: DeviceAssertion <jwt> (an agent that enrolled with a code, see
Device Identity) or
Authorization: Bearer <api key>.
GET /self— what Orion has for this agent, and the pool's trust anchors, each arootor anissuerPUT /key— publish a key:publicKeyPemandcertificateChainPem(leaf first). The same call renews and rotates.POST /claim— take the next request. With{"wait": 25}Orion holds the call open for up to 25 seconds until one arrives.POST /sign— return the signed tokenPOST /reject— refuse, with a reasonPOST /challenge— ask the person signing in a question first
By hand with curl, for testing
What Users See
During a sovereign-signed login flow:
- User logs in normally (email/password, passkey, etc.)
- A dark-themed "Authorizing your session" page appears with a spinner
- If the agent issues a challenge, a prompt appears inline (e.g., "Approve sign-in for john@example.com?")
- Once signed, the user is redirected to the application (typically <1 second)
- If the agent rejects or times out, the user sees an error message
The wait page uses Server-Sent Events (SSE) for real-time updates — no page refresh needed.
Troubleshooting
| Symptom | Cause & Fix |
|---|---|
| Wait page spins forever | No agent in the pool is running, or none has published a key yet (an agent with no key claims nothing). The pool's page shows each agent and its key; the agent's own log and status say what it is waiting for. |
| Agent sign returns 400 "payload mismatch" | The header.payload portion of the signed JWT must be byte-identical to the unsignedPayload from the claim response. Don't modify the payload before signing. |
| SDK rejects valid sovereign tokens | Check how the application validates. Pinning the root: the root in its configuration must be the one the agent's certificate chains to, the certificate must carry any usage the application requires, and with revocation on the authority's revocation list must be reachable and in date. Pinning thumbprints: the thumbprint must be the signing key's. |
client_credentials returns authorization_pending |
No agent answered within ORION_SOVEREIGN_M2M_TIMEOUT_SECONDS (default 30s). A running agent answers in well under a second, so this usually means none is running or none has a key. The client can retry; add a second agent to the pool so one host being down does not stop tokens. |
Token endpoint returns access_denied: "The signing agent refused to sign this token" |
The agent answered, and said no. The reason follows in error_description and is in the agent's own log: usually the application is not one the agent is configured to sign for, or the token would live longer than the agent allows. Change the agent's policy on its host, or the application; retrying changes nothing. |
| The agent reports that Orion refused its key | The pool has trust anchors and the chain does not end at a root among them, the pool names an issuing authority and the certificate is not from it, the certificate is not for this key, or it has expired. The answer says which. In a pool with no anchors, an agent cannot replace a key it has already published. The agent keeps trying, so correcting the certificate is enough. |
| The agent stops at once with a configuration error | Its options cannot be used (no application listed and AllowAnyClient not set, for one), or Orion refused its credential the first time it was presented: an enrolment code that was already used or is more than 15 minutes old. While the agent has not enrolled, New enrolment code on the pool's page gives it another. An agent that has enrolled keeps its device: to move it to another host, register a new agent and deactivate the old one. |
| Pool JWKS returns empty keys array | No active agent in the pool has a key. An agent that brings its own key is listed from the moment it is registered, but has no key until its host has published one. |
| Agent webhook not being called | Verify the webhookUrl is reachable from the Orion server. Check agent registration includes the URL. Webhook failures don't block the flow — agents can still poll. |