Sovereign Signing Guide

Step-by-step setup for out-of-band JWT signing with external agents

Back to Docs

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.


What you set up.

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.
A pool with no trust anchor accepts a key with or without a certificate, and an agent in it may publish its first key but cannot replace it, because there is nothing to check a new key against. Leave a pool without one only if your applications pin the key itself (Step 6, thumbprint pinning).

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.

using OrionDotNetCore.Sovereign; var options = new SovereignAgentRunnerOptions { ServerBaseUrl = "https://login.shanecraven.com", OrganisationId = "your-org", EnrolmentCode = File.ReadAllText("/etc/orion-agent/enrolment-code").Trim(), // from Step 3; used once Signer = PemKeySovereignSigner.FromFile("/etc/orion-agent/signing-key.pem"), Certificates = new FileSovereignCertificateSource("/etc/orion-agent/chain.pem"), SigningLog = new FileSovereignSigningLog("/var/log/orion-agent/signing.log"), }; options.Policy.AllowedClients.Add("billing"); // the applications this agent signs for var runner = new SovereignAgentRunner(options, logger); await runner.RunAsync(stoppingToken);

What it does when it starts:

  • 1. Redeems the enrolment code as a device and keeps that identity in its own directory (~/.orion/sovereign-agent by 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: iss is https://login.shanecraven.com/oauth/your-org (set Issuer if 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 above SignaturesPerMinuteLimit (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)

# ORION_SOVEREIGN_SIGNING_POOL__<CLIENT_ID>=pool-id # The client id in upper case, with "-" and "." written as "_". For the application "billing-api": export ORION_SOVEREIGN_SIGNING_POOL__BILLING_API=main-pool
Start with an application that is not critical, and list it in the agent's 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)

using OrionDotNetCore.Sovereign; services.AddSovereignSigning(o => { o.FederationServer = "https://login.shanecraven.com/federation"; o.OAuthOrganisationId = "your-org"; o.OAuthClientId = "billing"; o.PoolId = "main-pool"; o.TrustedRootCertificates = new[] { File.ReadAllText("sovereign-root.pem") }; // or, with no copy of the root: // o.TrustedRootThumbprints = new[] { "C4:8F:32:..." }; // Where the root has other authorities under it: only this one's certificates. o.TrustedIssuerCertificates = new[] { File.ReadAllText("sovereign-issuing-ca.pem") }; // or: o.TrustedIssuerThumbprints = new[] { "9A:01:5E:..." }; o.RequiredCertificateUsages = new[] { "1.3.6.1.5.5.7.3.2" }; // the usage your authority gives signing agents o.RevocationMode = X509RevocationMode.Online; });
  • 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)

// SHA256(RSA_Modulus_bytes || RSA_Exponent_bytes) → base64, for each key you accept. // Every new key needs its thumbprint added here before it signs. services.AddSingleton<IFederationConfig>(new FederationConfig { FederationServer = "https://login.shanecraven.com/federation", FilterType = FederationFilterType.OAuthUserBearer, OAuthOrganisationId = "your-org", OAuthClientId = "billing", SovereignSigningPoolId = "main-pool", SovereignKeyThumbprints = new[] { "sha256:YOUR_KEY_THUMBPRINT_HERE" } });

Embedded key (maximum isolation, no JWKS fetch)

services.AddSingleton<IFederationConfig>(new FederationConfig { FederationServer = "https://login.shanecraven.com/federation", FilterType = FederationFilterType.OAuthUserBearer, OAuthOrganisationId = "your-org", OAuthClientId = "billing", SovereignPublicKeys = new[] { "-----BEGIN PUBLIC KEY-----\nMIIBI..." } });

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 agent's host: the private key stays there openssl genrsa -out agent-private.pem 4096 openssl rsa -in agent-private.pem -pubout -out agent-public.pem

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:

POST https://login.shanecraven.com/oauth/your-org/sovereign/admin/agents { "poolId": "main-pool", "agentId": "agent-01", "name": "Primary Signing Agent", "publicKeyPem": "(PEM, or base64 DER)", "certificateChainPem": "(optional: leaf first)", "webhookUrl": "https://agent.example.com/signing-webhook" } # Response (the apiKey is shown only once): { "id": 1, "agentId": "agent-01", "keyId": "main-pool-v1", "keyVersion": 1, "apiKey": "Rk9PQkFSLi4u..." }
  • 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 a root or an issuer
  • PUT /key — publish a key: publicKeyPem and certificateChainPem (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 token
  • POST /reject — refuse, with a reason
  • POST /challenge — ask the person signing in a question first
var baseUrl = "https://login.shanecraven.com/oauth/your-org"; var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", agentApiKey); var rsa = RSA.Create(); rsa.ImportFromPem(File.ReadAllText("agent-private.pem")); while (true) { // 1. Claim the next pending request. With "wait", Orion holds the call open // (up to 25 seconds) until a request arrives, so there is no delay to tune. var claimResp = await client.PostAsJsonAsync($"{baseUrl}/sovereign/agent/claim", new { wait = 25 }); var claim = await claimResp.Content.ReadFromJsonAsync<ClaimResponse>(); if (!claim.Claimed) continue; // Nothing arrived while waiting; ask again // 2. Apply your policy to the bytes you are about to sign: decode the payload and // check its audience, issuer and expiry. To refuse: POST /sovereign/agent/reject // 3. Sign the unsigned payload exactly as it was claimed. Its header already // names this agent's key id: Orion writes it when the request is claimed. var unsignedPayload = claim.UnsignedPayload; // "base64url-header.base64url-payload" var dataToSign = Encoding.UTF8.GetBytes(unsignedPayload); var signature = rsa.SignData(dataToSign, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1); var signedJwt = unsignedPayload + "." + Base64UrlEncoder.Encode(signature); // 4. Submit the signed JWT await client.PostAsJsonAsync($"{baseUrl}/sovereign/agent/sign", new { requestId = claim.RequestId, signedJwt = signedJwt }); }

By hand with curl, for testing

# Claim a request CLAIM=$(curl -s -X POST https://login.shanecraven.com/oauth/your-org/sovereign/agent/claim \ -H "Authorization: Bearer $AGENT_API_KEY" \ -H "Content-Type: application/json" -d '{}') REQUEST_ID=$(echo $CLAIM | jq -r '.requestId') PAYLOAD=$(echo $CLAIM | jq -r '.unsignedPayload') # Sign it with the agent's private key SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -sign agent-private.pem | base64 | tr '+/' '-_' | tr -d '=\n') SIGNED_JWT="${PAYLOAD}.${SIGNATURE}" # Submit curl -X POST https://login.shanecraven.com/oauth/your-org/sovereign/agent/sign \ -H "Authorization: Bearer $AGENT_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"requestId\": \"$REQUEST_ID\", \"signedJwt\": \"$SIGNED_JWT\"}"

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.

Verify Your Setup

# 1. Check pool JWKS serves the agent's key curl https://login.shanecraven.com/oauth/your-org/sovereign/pools/main-pool/jwks.json # Should return: {"keys":[{"kty":"RSA","kid":"...","x5c":[...]}]} # The kid is the key's thumbprint for a key an agent published, main-pool-v1 for one registered by hand # 2. Check main JWKS does NOT include the agent's key curl https://login.shanecraven.com/oauth/your-org/.well-known/jwks.json # Should NOT contain that kid # 3. Check pool discovery document curl https://login.shanecraven.com/oauth/your-org/sovereign/pools/main-pool/.well-known/openid-configuration # Should point jwks_uri to the pool JWKS # 4. Test the agent queue (an agent registered with an API key) curl -H "Authorization: Bearer $AGENT_API_KEY" \ https://login.shanecraven.com/oauth/your-org/sovereign/agent/queue # Should return: {"requests":[]}
← SDK Integration Security Features →