Starting the authorization server for the first time

saphan-oauth is the authorization server this product runs. It publishes its own description and the public half of the keys it signs with, over an encrypted connection. Everything below is done by your hand, once, in this order.

Decide how the connection is encrypted

There are two arrangements and the server will not pick one for you.

Native. This server holds a certificate and a private key and handles encryption itself. Choose this when the server is reached directly.

Behind a proxy. A load balancer, reverse proxy or tunnel handles encryption and forwards to this machine. This server then speaks plain HTTP, and it will only do so on the local machine: a plaintext listener on an address other people can reach is refused, not warned about.

Write the settings

Add an [oauth_server] section (§4). The smallest working native configuration:

[oauth_server]
issuer    = "https://auth.example.com"
listen    = "127.0.0.1:7655"
tls_mode  = "native"
tls_cert  = "/etc/ssl/certs/auth.example.com.pem"
tls_key   = "/etc/ssl/private/auth.example.com.key"
state_dir = "/var/lib/saphan"

Behind a proxy, replace the three TLS lines with tls_mode = "proxy" and keep listen on a loopback address. If your proxy is on a different machine, add its address range:

trusted_proxies = "10.0.0.0/8"

A proxy on this same machine needs no entry — the local machine is always trusted, and no setting can withdraw that.

issuer is the one that cannot be changed later without cost. It is this server's name. It goes into every token, every client stores it, and it is never taken from an incoming request. Choose the address clients will actually use, and choose it once.

Create the first signing key

saphan-oauth key mint

It prints the key's identifier, whether the key went into use, and the file its material was written to:

Created a signing key.
  identifier: 8FnQ...redacted...
  status:     in use — this server now signs with it and publishes it
  key file:   /var/lib/saphan/auth/keys/8FnQ....pem

Why this is a separate act and not something startup does for you. A key created automatically at startup would replace the old one silently. Every token in flight and every client that had cached the key set would stop working at that moment, and nothing anywhere would record when it happened or why. So the server refuses to start without a key, and creating one stays a thing a person did, at a moment they can point to.

Back up the key file. It is mode 0600 and it is the only copy. The database records where the key is, never the key itself — so a database backup alone will not bring this server back.

Running key mint a second time stages a key rather than replacing the one in use: the new key is not published and signs nothing until the key set is rotated. That rotation verb is not in this release.

Start it

saphan-oauth serve

Add --detach to run it in the background; it prints the process id and the log file.

Check it from outside

curl https://auth.example.com/.well-known/oauth-authorization-server
curl https://auth.example.com/.well-known/openid-configuration
curl https://auth.example.com/jwks

Both discovery addresses are served, because client libraries look in one or the other and which one is not ours to choose. They must report the issuer you configured — not the address you happened to type into curl. If they report something else, stop and read §13.6, because it means something is deriving this server's name from the request.

/jwks answers with the public half of your signing key and nothing else. For the EC key key mint creates, that is exactly five members:

{"keys":[{"kty":"EC","kid":"…","crv":"P-256","x":"…","y":"…"}]}

There is no d — that is the private half, and it never leaves the key file. There is also no n and no e: those describe an RSA key, and on an EC key they mean nothing, so they are absent rather than present-and-empty. A strict JOSE client is entitled to reject a key that carries them.

This release serves those three addresses and nothing else. There is no /authorize and no /token yet, and neither discovery document advertises one — an address that answers 404 is a promise you could dial, and we would rather be visibly incomplete than quietly broken.

When it refuses to start

Every refusal names the setting to change and what to change it to, and prints as a paragraph rather than one line. The ones you are most likely to meet: