iya-sts

An identity service that speaks every protocol family the sidebar lists in one Node process, in one of two modes (global.mode).

What it speaks about is two protocol-independent objects. A user is one person. An application is one application. The protocols name that pair. Directory.

Development mode, the default, exists to exercise clients: it checks no end user’s password, creates whoever and whatever a request names, and accepts tokens it cannot verify at the doors where a client under test needs to. A client that has only ever met a permissive server has never run its own refusal paths — and a client that has only met a strict one cannot reproduce the behaviour it is trying to detect.

Product mode is meant to be deployed: it verifies every password, creates nothing because something named it, invents no claim value, and implies RFC 9700 mode. What is not checked says exactly where the line is in each.

Where to read

The sidebar on every page is the full list, grouped as below. The protocol pages share one shape — features, what development and product mode change, every setting with its environment variable and default, and the design decisions behind the behaviour — so the same question has the same place on each.

Start here — Getting started · Release notes · Certifications · Architecture · Where a request waits · Configuration · Configuration dump · Endpoints · Trust realms · Listeners and hosted applications · Words a password may not contain · Malware scanning · What is not checked · Security in product mode · Input validation · Data classification · Logging inventory · Key management · Field-level access · Communication inventory · File uploads · Authentication pathways · Availability and resource limits · Conformance suites · Departures from the specifications · Accepted tokens · Token samples · Error codes

Protocol debugger — The protocol debugger: the identity protocol debugger this service embeds on port 8444, for console administrators, with its user guides · Accessing the debugger: signing in, turning it on, and building an image without it

Administration — Admin console: /admin, who may use it and what its pages do · Security Administrator: the role that alone changes policies, and how to give it to somebody who is not an administrator · Audit export destinations: where this process sends its audit events, with an example for syslog, a file, a webhook, Splunk HEC and LogRhythm · OpenAPI reference: every operation of each API this service publishes, its parameters and its answers · Management API: /admin-api, every console control reachable by a machine with an OAuth 2.0 access token · Delegation and impersonation: who may obtain a token about somebody else, the same controls for RFC 8693, WS-Trust, Kerberos and GNAP, the token types and claims, and a worked example of each.

Directory — a user and an application, which belong to no protocol, then the policy they are held to, then how each is configured. Directory · People · Applications: one application, whichever protocol it spoke · Policies: the seven kinds, and how a named policy is chosen · Service accounts · LDAP · LDAP schema · Abstract data model · Directory models · Persistence models · Configuring LDAP · SCIM 2.0 · Bulk directory import.

Configuration recipes — what to register, which settings to change and what the client sends, each given as admin console steps and as Management API calls, with values from this repository’s test jobs. Each sits in its protocol’s section of the sidebar: OAuth 2.0 grants · OpenID Connect flows · SAML 2.0 and SAML 1.1 · WS-Trust · WS-Federation · Federation · OpenID Federation · Kerberos and SPNEGO · TLS and mutual TLS · OpenID4VCI · OpenID4VP and wallet sign-in · LDAP · SCIM 2.0 · XACML and ALFA · GNAP · Shared Signals · Certificate enrollment: ACME, EST, SCEP · SPIFFE · Passkeys and WebAuthn · Post-login activities.

Sessions and signals — Sessions · Identity-provider-initiated sign-in · Several accounts in one browser · Sign-in appearance · Signing out · Risk scoring · Devices · Mail · Reports · Attribute sources · Secret push destinations · CAEP events · Signals received

Authorization — Authorization overview · XACML 3.0 and ALFA · Fine-grained authorization · AuthZEN · User-Managed Access · Remote PEP · Delegation and impersonation

Client libraries — Authentication libraries: client libraries for integrating an application with iya-sts. The four server-side libraries exist in Node.js, Python, Java, Rust, Go, C#, and C and C++, with links to the packages on npm, PyPI, crates.io and NuGet; there are also two in-browser clients and a Swift client. OpenID Connect and CAEP clients is the detailed guide to the browser OpenID Connect client and the Swift client for native macOS apps.

Operating it — The compose stack · Persistence · PostgreSQL schema · Encryption at rest · Caches · How the cluster works · A cluster in AWS · A CDN in front of a cloud deployment · Several regions (cells) · How cells work

For contributors — Repository layout · Parent project migration

Protocols, by the admin console’s Protocols menu

Every page under Protocols in the admin console, and the page here that documents it.

Console group Console pages Documentation Configuration recipes
OAuth2 / OIDC /admin/oauth2, /admin/authorization-servers, /admin/token-lifetimes, /admin/claims, /admin/userinfo-claims OAuth 2.0 and OpenID Connect, Security profiles: RFC 9700, OAuth 2.1, DPoP, mTLS, JWT assertions OAuth 2.0 grants, OpenID Connect flows
SAML /admin/saml2, /admin/saml11, /admin/saml-assertions, /admin/saml-attributes SAML 2.0 Web Browser SSO, SAML 1.1, SAML assertions as grants (RFC 7522) SAML 2.0 and SAML 1.1
Verifiable Credentials /admin/vc — Metadata, OpenID4VCI settings, Credential claims, OpenID4VP settings and Verifier request tabs; what was issued and each credential’s status at /admin/vc/monitor, under Monitoring Verifiable credentials and wallets (OID4VC), OpenID4VCI and status lists, OpenID4VP and wallet sign-in OpenID4VCI, OpenID4VP
XACML /admin/xacml, /admin/xacml/policies, /admin/xacml/editor, /admin/xacml/peps, /admin/xacml/decide XACML 3.0 and ALFA, Remote PEP XACML and ALFA
SCIM /admin/scim SCIM 2.0 SCIM 2.0
Shared Signals, CAEP, RISC /admin/ssf, /admin/caep, /admin/risc Shared Signals, CAEP events, Signals received Shared Signals
Federation /admin/federation Federation, Consumer and social providers Federation
OpenID Federation /admin/oidfed OpenID Federation OpenID Federation
GNAP /admin/gnap GNAP GNAP
TOTP MFA, Recovery codes, WebAuthn /admin/totp, /admin/backup-codes, /admin/webauthn Authentication, Passkeys and WebAuthn Passkeys and WebAuthn
Device registration /admin/device-registration Devices  
Kerberos /admin/kerberos, /admin/kerberos/principals Kerberos and SPNEGO Kerberos and SPNEGO
LDAP / LDAPS /admin/ldap LDAP LDAP
WS-Trust /admin/wstrust WS-Trust WS-Trust
WS-Federation /admin/wsfed WS-Federation WS-Federation
PKI /admin/pki PKI  
PKI trust /admin/pki/trust Signer truststore, use cases, paranoid PKI mode  
Cryptography /admin/crypto-metadata Signature algorithms  
Cert issuance (ACME, EST, SCEP and SPIFFE tabs) /admin/cert-issuance ACME, EST, SCEP, SPIFFE ACME, EST, SCEP, SPIFFE
TLS / mutual TLS /admin/tls, /admin/tls/trust TLS and mutual TLS TLS and mutual TLS

Start here

git clone --recursive https://github.com/rcbj/iya-sts.git
cd iya-sts
docker build -t iya-sts .
docker run --rm -p 8081:8081 iya-sts

It runs from an image: part of the service is TypeScript, compiled while the image is built, and a checkout does not run on its own.

https, and your browser will warn you once. Every appconfig file here sets global.https, so the main port is TLS on the same certificate the LDAPS 636 listener uses, issued under this service’s own Root CA — which, in development mode, is rebuilt on every start, so nothing can have trusted it in advance. Accept it, or fetch the certificate, its chain and the Root with curl -k https://localhost:8081/tls/server-certificate and trust the Root (TLS); STS_HTTPS=false runs the plain port this used to be.

Then open https://localhost:8081/ — a front page with the six things worth having on one: this repository, its issues, this site, and the three surfaces on that instance that a person rather than a client goes to — the admin console, reports at /report, and the user portal at /portal, which is that instance’s account page for whoever signs in to it. Its Overview draws every standard inetOrgPerson attribute the signed-in person’s directory entry could hold — all fifty, grouped by the three object classes a person here is filed under, with the LDAP attribute name and the RFC printed under each value, because the reason to read it on a test service is usually to find out what something is called before writing it over LDAP.

The page worth going to next is https://localhost:8081/admin/sts-metadata — every protocol this service speaks, and every endpoint it registers, read off the live Express router, with a sentence about each and a link to the specification it implements. It is a page of the admin console, so it asks you to sign in first: in development mode any username will do, because no password is checked; in product mode sign in as the bootstrap administrator admin, whose password is written to the log once at the first start unless admin.bootstrapPassword supplied one.

Getting started has the rest: the ports, the container, and what to do when 389 or 88 will not bind.

Architecture

One front process owns every listener, and a request dispatcher hands work from it to two pools of worker threads. The protocol families and hosted applications share one session model and one set of services, over an embedded directory and key material sealed in their stores. Architecture has the diagram and a walk through each layer.

What it speaks

Family Where Read
OAuth 2.0 and OpenID Connect — a full authorization server /oauth2/*, /.well-known/openid-configuration oauth-oidc
DPoP (RFC 9449) and certificate-bound tokens (RFC 8705) the token endpoint and the four protected endpoints oauth-security
RFC 9700, the Security BCP, as an optional MODE GET /oauth2/rfc9700 oauth-security
OAuth 2.1 (draft-16) as an optional MODE, which turns the one above on GET /oauth2/oauth21 oauth-security
Post-quantum and hybrid JWE key establishment — ML-KEM, and HPKE over ML-KEM or X-Wing (drafts) every encrypted token and response; a realm’s own keys by opt-in post-quantum-encryption
WS-Trust 1.0 – 1.4 /sts, /sts/metadata, /sts/mex ws-trust
WS-Federation 1.2, passive requestor /wsfed ws-federation
SAML 2.0 Web Browser SSO — a full identity provider, all four bindings /saml2, /saml2/metadata/{sp} saml2-sso
SAML 1.1 browser profiles — Browser/POST and Browser/Artifact, and an attribute authority /saml11, /saml11/metadata/{rp} saml11
SAML 2.0 and SAML 1.1 assertions inside all four above saml2-sso
Federation — this service as either end of a relationship with a foreign identity service, in five of those protocols /federation, /admin/federation federation
Consumer and social providers — Google, Apple, Microsoft, GitHub, Discord and eleven more as federation relationships of their own category, off by default per realm; a person connects one to an existing account on the portal /federation, /admin/federation, /portal/connected-accounts federation-consumer-providers
OpenID Federation 1.1 — every realm a federation entity (Trust Anchor, Intermediate or Leaf) with its own Federation Entity Keys; Subordinate Statements with metadata policy and constraints, Trust Chain resolution, Trust Marks, and the section 8 endpoints /.well-known/openid-federation, /oidfed/*, /admin/oidfed oidfed
JWT assertions (RFC 7521, RFC 7523) — both halves: an assertion instead of a client secret, and an assertion instead of an authorization code the token endpoint jwt-assertions
SAML 2.0 assertions (RFC 7521, RFC 7522) — the same framework’s other profile: a signed <saml:Assertion> instead of a client secret, and instead of an authorization code. A separate key pair per application from the JWT one, and neither can sign for the other the token endpoint saml-assertions
A certificate authority — ONE Root for the service, an Intermediate per trust realm and per the process, an Issuing CA per use case, and every key pair this service generates as a leaf of it /admin/pki, /admin-api/pki pki
WebAuthn Level 3 over FIDO CTAP2, the relying party’s half — passkeys as a second factor or the only credential on an account, with or without a username, classical and post-quantum (ML-DSA) side by side the login screen, /portal/keys, /admin/webauthn passkeys, authentication
TOTP (RFC 6238) — an authenticator app as a second factor, enrolled as a QR code and genuinely verified /portal/mfa, /authn/totp, /admin/totp authentication
Recovery codes — the way back in when the second factor is not to hand, generated by the person, shown once and stored as a hash — NIST SP 800-63B-4’s look-up secrets /portal/mfa, /authn/backup-code, /admin/backup-codes authentication
App passwords — what a person with a second factor gives a client at the five doors that take only a password (LDAP, WS-Trust, SCIM, SSF and EST Basic), which in product refuse their own password; generated, shown once, hashed, scoped to the doors named and never accepted at a browser sign-in /portal/app-passwords, /admin/users, /admin-api/users/app-passwords authentication
Kerberos v5 — a KDC, a protected service, and MS-KKDCP; a person’s keytab, derived from a password in hand TCP/UDP 88, /KdcProxy, /portal/kerberos kerberos
SPNEGO (RFC 4559/4178) /authn/spnego kerberos
LDAP v3 (RFC 4511) and LDAPS TCP 389 and 636 ldap
SCIM 2.0 provisioning /scim/v2 scim
TLS and mutual TLS — a client certificate asked for and never required, and a sign-in for a verified one the main port, /tls/sign-in, /admin/tls-connection tls
SPIFFE — bundle endpoint, Workload API, SPIRE Server API /spiffe, four gRPC sockets spiffe
OpenID4VCI 1.0 — a Credential Issuer /oid4vci/* oid4vci, verifiable-credentials
OpenID4VP 1.0 — a Verifier, and a sign-in with a wallet in any credential format, through the W3C Digital Credentials API /oid4vp/*, /authn/wallet, /admin-api/verifications oid4vp, verifiable-credentials
SIOPv2 — the relying party of a Self-Issued OpenID Provider: a sign-in with an ID Token a wallet signs with an enrolled key, a preferred DID released as the did claim; off until a realm turns it on /authn/wallet, /portal/self-issued verifiable-credentials, oid4vp
Token Status List and W3C Bitstring Status List — what this issuer publishes about what it issued /oid4vci/status-lists*, /admin/vc/monitor oid4vci
W3C DID Core with DIF domain linkage /.well-known/did.json oid4vp
A did:web this realm publishes for a person, with every version of its keys kept; off until a realm turns it on /users/{rid}/did.json, /portal/self-issued person-dids
The W3C VC API (VCALM) — an issuer, holder, verifier and status service over Data Integrity (RDFC, JCS, ecdsa-sd-2023) and VC-JOSE-COSE, and DID resolution; off until a realm turns it on /vc-api/* vc-api
Shared Signals (SSF 1.0) with CAEP and RISC — a transmitter, and a receiver of its own /ssf/*, /admin/ssf shared-signals
XACML 3.0 and ALFA — a PDP, a policy repository, and the PEPs that decide this service’s own issuance /xacml/*, /admin/xacml xacml
AuthZEN Authorization API 1.0 — access evaluations over the same XACML engine, mapped through a per-realm attribute catalogue /access/v1/* authzen
Application-scoped fine-grained authorization — a policy each application owns for the details of its own authorization_details types, created with it and retired with it, enforced at issuance and at AuthZEN access evaluations once the application switches it on /admin/applications (Fine-grained authorization tab), /admin/xacml fga
GNAP (RFC 9635) with RFC 9767 resource server connections /gnap/*, /admin/gnap gnap
User-Managed Access 2.0 — a resource owner’s own XACML policy per person, the protection API, the uma-ticket grant; off until a realm turns it on /uma/*, /.well-known/uma2-configuration, /portal/shared uma
ACME, EST and SCEP certificate enrollment /enroll/acme, /.well-known/est, /enroll/scep acme, est, scep

The four things to know before you rely on it

In development mode nothing you would miss persists. The signing keys and the certificate authority are regenerated on every start — deliberately, so that a client cannot cache a key it should be re-fetching — and every document that carries a key is served Cache-Control: no-store. Product mode keeps them, sealed under a key-encryption key; persistence says what survives in each.

Every surface tells you what it does not do. That is not modesty; it is the point. GET /oauth2/rfc9700 publishes every BCP requirement with yes, detected, always, deployment or no and the reason. GET /spiffe names the six of forty-two SPIRE methods that are unimplemented and why each one is. GET /admin/ldap/service says the directory is schemaless. A service that quietly pretended would teach you something false about every real server you will ever meet.

The admin console at /admin asks for a sign-in and a role — unconditionally, with no setting that opens it — and the roles are two ordinary groups in the embedded directory. In development mode it is a turnstile and not a lock: no password is checked, so anybody who can reach this port can sign in as anybody. In development mode, until the bootstrap administrator admin first signs in, anybody who signs in holds both roles; product mode never opens it that way, and admin claims it only by signing in with its password. The console can revoke tokens, add claims to every future token and assertion, and create people in the directory. Do not put a development-mode instance on a public address. Admin console has the rest.

/admin-api requires an OAuth 2.0 access token — audienced to this API, carrying admin:read to read and admin:write to change anything. Ask the token endpoint for one with the client-credentials grant as the seeded client sts-api-client, whose secret is adminApi.clientSecret, and send resource=<base>/admin-api so the audience is right. On the compose stack that secret is kept in OpenBao and is for the first token only; after that, use an application of your own that holds the admin roles (Getting a token). adminApi.authRequired=false opens the API in development mode; product mode ignores it, and always requires the token.

Federation is the one feature that refuses by default, and that is deliberate. Everywhere else this service accepts what it is given. It cannot do that where it CONSUMES somebody else’s assertions: /federation/acs/{id} receives an unauthenticated HTTP request claiming to be a person, and the session it would produce is the same one every other protocol here reads — so “accept anything” would be an authentication bypass for the whole process rather than a permissive test setting. A relationship must be configured, is created disabled, and refuses an assertion that does not verify against the certificate configured on it. And the gate is on the subject too: a partner signs in only the person its subject is linked to, and an unlinked one naming an existing person must first sign in here as that person (#109). One naming nobody is created as <relationship>~<subject> when that relationship’s fedAutocreateUsers is on (on for a new relationship in development, off in product), and refused otherwise. See federation and what is not checked.