Set up an OpenID Connect app

Point your library at the issuer

The issuer is the same for every organization. Your client ID tells Trustaige which organization the app belongs to.

curl https://id.trustaige.com/.well-known/openid-configuration

Trustaige supports the code response type, returned in the query string (response_mode=query). Every authorization request needs the openid scope.

GET https://id.trustaige.com/oauth2/authorize
  ?response_type=code
  &client_id=<your-client-id>
  &redirect_uri=<your-app-url>/callback
  &scope=openid%20email%20profile
  &state=<random_state>
  &code_challenge=<code_challenge>
  &code_challenge_method=S256

Client authentication

How the app proves who it is at the token endpoint. Change it under Edit app → OIDC Configuration → Token Endpoint Auth Method.

An app with a secret can send it either way, Basic or in the body; Trustaige accepts both whichever was chosen. If it sends both, both must be right.

curl https://id.trustaige.com/oauth2/token \
  -u '<your-client-id>:<your-client-secret>' \
  -d grant_type=authorization_code \
  -d code=<code_from_callback> \
  -d redirect_uri=<your-app-url>/callback \
  -d code_verifier=<code_verifier>

A code works once, and for 10 minutes.

Rotate the secret with the regenerate button beside Client Secret on the app’s page. The current secret stops working at once, so have the new one ready to deploy.

private_key_jwt

No shared secret exists: the app signs a short JWT with its private key, and Trustaige checks it against the app’s public keys. Under Token Endpoint Auth Method choose Private Key JWT, then give the public keys one of two ways:

• Hosted JWKS URL: an https address that serves the key set. Trustaige caches it, and fetches it again when an assertion names a key it hasn’t seen, so rotating keys needs nothing in the hub.
• Pasted key set: a JWKS document stored with the app. Rotating means pasting a new set.

Verify keys checks each key before you save. Assertion Signing Algorithm accepts Any supported (RS256, ES256, PS256 or EdDSA) or pins one.

The assertion goes in the token request as client_assertion, with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer:

PKCE

PKCE ties the code to the app that asked for it, so an intercepted code is useless.

• S256 is the only method. Send code_challenge_method=S256 with every challenge: a request that leaves the method out is refused.
• The challenge is the unpadded base64url SHA-256 of a random verifier of 43 to 128 characters. Send the verifier as code_verifier with the code.
• A public client must use PKCE. A web app may; Trustaige checks the verifier whenever a challenge was sent. To require it from a web app, turn on Require PKCE under Edit app.

import crypto from 'node:crypto';

const verifier = crypto.randomBytes(32).toString('base64url');
const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');

import (
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
)

func pkcePair() (verifier, challenge string) {
	b := make([]byte, 32)
	rand.Read(b)
	verifier = base64.RawURLEncoding.EncodeToString(b)
	sum := sha256.Sum256([]byte(verifier))
	return verifier, base64.RawURLEncoding.EncodeToString(sum[:])
}

import base64, hashlib, secrets

verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()