Authentication libraries
These libraries are the relying party’s side of a protocol iya-sts implements, packaged so an application can sign people in without writing the protocol itself. They are a set of client libraries for integrating applications with iya-sts. Each one is written to its specification, so it also works with other providers that implement the same specification.
There are four server-side libraries — OpenID Connect, GNAP, SAML 2.0 and WS-Federation — in Node.js, Python, Java, Rust, Go, C#, and C and C++. There are also two in-browser clients, for OpenID Connect and GNAP, and a Swift client for native macOS apps. Every repository is public and every library is under the MIT License.
| Language | Where the packages are published |
|---|---|
| Node.js (TypeScript and JavaScript) | npm |
| Python | PyPI |
| Java | Maven Central, group com.iyasec |
| Rust | crates.io, with API documentation on docs.rs |
| Go | Git tags v<version>, served by the Go module proxy, with API documentation on pkg.go.dev |
| C# | NuGet |
| C and C++ | Not published to a package manager; build it from the repository with CMake, or put it in your Conan cache from a clone of a release tag |
| Swift | GitHub Releases, through Swift Package Manager |
Each repository has a test that signs its demo application in to a fresh
iya-sts built from the latest main branch. The test then sends two CAEP
events — a credential change and a revoked session — and checks the library
acted on both. A nightly workflow in each repository runs that test with
the rest of the suite.
How a library is called is in that library’s own documentation. How iya-sts behaves as the provider is on the protocol page for that family: OAuth 2.0 and OpenID Connect, SAML 2.0 Web Browser SSO, WS-Federation, GNAP and Shared Signals.
A longer guide to the browser OpenID Connect client, and to the Swift client for native macOS apps, is OpenID Connect and CAEP clients.
Trusting iya-sts’s TLS certificate
Every server-side library has a setting for the CA trust chain of
iya-sts’s TLS listener: tlsCa for OpenID Connect and GNAP, idpCa for
SAML 2.0 and WS-Federation. Each repository’s install script writes the
whole chain iya-sts publishes at GET /tls/server-certificate to the
file that setting names, and the demo’s image build copies that file in.
Run the install script again and rebuild the image when you point the demo
at a different iya-sts. The libraries trust only that chain when the
setting is present, and they check the host name against the certificate.
What the OpenID Connect confidential client checks
The seven server-side OpenID Connect libraries (oidc-caep-risc in every
language) behave the same way, with the same JSON configuration keys and
the same defaults. Every check below applies however the client is
created: loaded from a configuration file, or built directly in code.
- PKCE,
state,nonceand issuer identification. Every authorization request carries an S256 code challenge, astateand anonce. The response’sissparameter (RFC 9207) is checked when the provider advertises it, and iya-sts does. - Pushed Authorization Requests (RFC 9126).
parisauto(the default),alwaysornever.autopushes whenever the provider has a PAR endpoint. When the provider setsrequire_pushed_authorization_requests,par: neverfails when the client is created, and so doespar: alwaysagainst a provider with no PAR endpoint. - DPoP (RFC 9449).
dpopisauto(the default),alwaysornever.autoturns DPoP on when the provider lists ES256 indpop_signing_alg_values_supported, which iya-sts does. The client sends a proof to the PAR and token endpoints, and to UserInfo and the Shared Signals transmitter with the access token’s hash (ath). It sendsdpop_jkton the authorization request. When a server answersuse_dpop_nonce, the client retries once with the nonce it was given. The token response’stoken_typemust beDPoPwhen a proof was sent andBearerwhen none was. The key is an ES256 key pair generated when the client is created and held in memory. An application that runs several processes names one P-256 key for all of them withdpopKey. - The ID token’s signature.
idTokenSigningAlgsis the list of algorithms the client accepts,["RS256"]by default. Only the algorithms in that list that the provider also advertises are used, and the client fails at creation when none are left.noneis never accepted, and an HMAC algorithm only when the list names it. - The ID token’s
typ,at_hashandiat. The header’stypmust beJWTorapplication/jwt. When the token response carries an access token, the ID token must carry a matchingat_hash. SettingrequireIdTokenTypAndAtHashtofalsechecks each only when it is present, for a provider that leaves them out; iya-sts includes both. An ID token issued more thanmaxIdTokenAgeSecago (600 seconds by default), or more thanclockToleranceSecin the future (30 seconds by default), is refused. acr.acrValues(a string or a list) is sent asacr_valueson every authorization request, and a single sign-in can name its own. When values were requested, the ID token must carry anacrthat is one of them. A refresh does not checkacragain.- TLS. The issuer and every provider endpoint must be
https, unlessallowInsecureis set, which is for development only. A redirect URI and the post-logout redirect URI must behttps, orhttpon a loopback host (localhost,127.0.0.1,[::1]), and so must a redirect URI a single sign-in overrides.allowInsecuredoes not relax that rule. - A token cache per session. After a sign-in, the client keeps its
tokens under a session identifier the application chooses. Asking for
that session’s access token returns the cached one while it has more
than 30 seconds left, and otherwise refreshes it, with a DPoP proof
when DPoP is on. A failed refresh removes the session. So does a CAEP
session-revokedevent for that person, and so does the application signing the person out. The cache is in memory by default; an application that runs several processes can replace it with a shared store. Each library’s README names the calls in that language.
Changes for an application upgrading from an earlier version. A
provider that does not advertise RS256 needs idTokenSigningAlgs set, and
a provider that leaves out typ or at_hash needs
requireIdTokenTypAndAtHash: false. allowInsecure no longer allows a
plain http redirect URI outside loopback. Each repository’s install
script registers its demo at iya-sts with RS256 as the ID token
algorithm.
Node.js (TypeScript and JavaScript)
Six modules, published on npm by
rcbj. Each is written in TypeScript and can
be required from JavaScript. Install one with npm install <name>. The
latest tag is the release from main; the next tag is the
pre-release from develop.
| Module | Description | Repository | Documentation |
|---|---|---|---|
oidc-caep-client |
In-browser OpenID Connect public client (PKCE, PAR, DPoP, RFC 9207) with token caching and auto-refresh, and a Shared Signals (SSF) / CAEP event receiver | rcbj/oidc-caep-client | documentation |
oidc-caep-risc-nodejs |
Server-side OpenID Connect confidential client: Authorization Code with PKCE, PAR and DPoP, client authentication, a per-session token cache with auto-refresh, and a CAEP and RISC Shared Signals receiver (what it checks) | rcbj/oidc-caep-risc-nodejs | documentation |
gnap-caep-client |
In-browser GNAP (RFC 9635) client: HTTP message signature key proofs, redirect interaction, subject information for user sign-in, key-bound token caching and rotation, and a Shared Signals (SSF) / CAEP event receiver | rcbj/gnap-caep-js | documentation |
gnap-caep-risc-nodejs |
Server-side GNAP (RFC 9635) client for traditional web applications: a registered key proved by mutual TLS, HTTP message signatures or detached JWS, key-bound tokens, redirect and push interaction finish, and a CAEP and RISC Shared Signals receiver | rcbj/gnap-caep-risc-nodejs | documentation |
saml2-sp-nodejs |
Server-side SAML 2.0 service provider: signed AuthnRequests on HTTP-Redirect or HTTP-POST, and Responses on HTTP-POST, HTTP-Redirect or HTTP-Artifact (with SOAP artifact resolution), validated strictly | rcbj/saml2-sp-nodejs | documentation |
wsfed-caep-nodejs |
Server-side WS-Federation relying party: the passive requestor profile (wsignin1.0, wsignout1.0, wsignoutcleanup1.0) with SAML 2.0 assertions validated strictly, and a CAEP and RISC receiver that ends sessions |
rcbj/wsfed-caep-nodejs | documentation |
Python, Java, Rust, Go, C#, and C and C++
The four server-side libraries in the Node.js table also exist in these languages. The two in-browser clients stay in that table. The Swift client for native macOS apps is below.
Each library follows its Node.js module: the same protocol behaviour and
the same JSON configuration keys. signals omitted or true keeps the CAEP
and RISC receiver. false does not start that receiver and does not
require transmitter metadata, so the library can sign people in at a
provider that does not implement Shared Signals. OpenID Connect and GNAP
also leave ssf.read and ssf.manage out of the request when signals
is false. SAML 2.0 and WS-Federation do not send OAuth scopes, so the flag
only gates the receiver.
The package column is the name in that language, linked to its page on the registry where it is published. The documentation link is the repository README.
Python
Install with pip install <package>. Import gnap_caep_risc,
oidc_caep_risc, wsfed_caep, or saml2_sp.
| Package | Protocol | Repository | Documentation |
|---|---|---|---|
gnap-caep-risc |
GNAP | rcbj/gnap-caep-risc-python | README |
oidc-caep-risc |
OpenID Connect | rcbj/oidc-caep-risc-python | README |
saml2-sp |
SAML 2.0 | rcbj/saml2-sp-python | README |
wsfed-caep |
WS-Federation | rcbj/wsfed-caep-python | README |
Java
Java 17. The Maven group is com.iyasec, and each artifact is on Maven
Central. Add one to a Maven build:
<dependency>
<groupId>com.iyasec</groupId>
<artifactId>gnap-caep-risc</artifactId>
<version>0.1.0</version>
</dependency>
or to a Gradle build with implementation("com.iyasec:gnap-caep-risc:0.1.0").
Each repository builds the library module (library/), which is the
published artifact, and the demo module (demo/), which is not published.
| Artifact | Protocol | Repository | Documentation |
|---|---|---|---|
gnap-caep-risc |
GNAP | rcbj/gnap-caep-risc-java | README |
oidc-caep-risc |
OpenID Connect | rcbj/oidc-caep-risc-java | README |
saml2-sp |
SAML 2.0 | rcbj/saml2-sp-java | README |
wsfed-caep |
WS-Federation | rcbj/wsfed-caep-java | README |
Rust
Add one with cargo add <crate>.
| Crate | Protocol | Repository | Documentation |
|---|---|---|---|
gnap-caep-risc |
GNAP | rcbj/gnap-caep-risc-rust | docs.rs, README |
oidc-caep-risc |
OpenID Connect | rcbj/oidc-caep-risc-rust | docs.rs, README |
saml2-sp |
SAML 2.0 | rcbj/saml2-sp-rust | docs.rs, README |
wsfed-caep |
WS-Federation | rcbj/wsfed-caep-rust | docs.rs, README |
Go
The module path is github.com/rcbj/ plus the repository name. The
repositories require Go 1.27. Each release is a v<version> git tag, so
go get github.com/rcbj/<repository>@latest resolves the latest release
through the Go module proxy, and @v<version> pins one.
| Module | Protocol | Repository | Documentation |
|---|---|---|---|
github.com/rcbj/gnap-caep-risc-go |
GNAP | rcbj/gnap-caep-risc-go | README |
github.com/rcbj/oidc-caep-risc-go |
OpenID Connect | rcbj/oidc-caep-risc-go | README |
github.com/rcbj/saml2-sp-go |
SAML 2.0 | rcbj/saml2-sp-go | README |
github.com/rcbj/wsfed-caep-go |
WS-Federation | rcbj/wsfed-caep-go | README |
C#
The packages target net8.0. Add one with dotnet add package <package>.
| Package | Namespace | Protocol | Repository | Documentation |
|---|---|---|---|---|
IyaSec.GnapCaepRisc |
IyaSec.Gnap |
GNAP | rcbj/gnap-caep-risc-csharp | README |
IyaSec.OidcCaepRisc |
IyaSec.Oidc |
OpenID Connect | rcbj/oidc-caep-risc-csharp | README |
IyaSec.Saml2Sp |
IyaSec.Saml |
SAML 2.0 | rcbj/saml2-sp-csharp | README |
IyaSec.WsFedCaep |
IyaSec.WsFed |
WS-Federation | rcbj/wsfed-caep-csharp | README |
C and C++
One implementation per protocol, written in C++17. A C program calls it
through the C header, which is an extern "C" interface; a C++ program
can use the C++ header’s classes. Both link the same library. OpenSSL
provides the cryptography. The libraries are not published to a package
manager; the README says how to build one with CMake.
Each repository also has a conanfile.py at its root, so a
Conan 2 user can clone a release tag and create the
package in their own local cache, then require it as usual. For example:
git clone --branch v0.1.2 https://github.com/rcbj/saml2-sp-c.git
conan create saml2-sp-c --version=0.1.2 --build=missing
That gives iya-saml2-sp/0.1.2. The packages are iya-gnap-caep-risc,
iya-oidc-caep-risc, iya-saml2-sp and iya-wsfed-caep; each README’s
Using it from Conan has its own command and version. They are not on
ConanCenter.
| Library | Protocol | Repository | Documentation |
|---|---|---|---|
gnap-caep-risc |
GNAP | rcbj/gnap-caep-risc-c | README |
oidc-caep-risc |
OpenID Connect | rcbj/oidc-caep-risc-c | README |
saml2-sp |
SAML 2.0 | rcbj/saml2-sp-c | README |
wsfed-caep |
WS-Federation | rcbj/wsfed-caep-c | README |
Swift
OIDCCAEPClient is an OpenID Connect public client (PKCE, PAR, DPoP) and
a CAEP receiver for native macOS apps, the native counterpart of
oidc-caep-client. Releases are tagged on GitHub; the first is
0.1.0.
Add https://github.com/rcbj/swift-oidc-caep-native-app to Swift Package
Manager, for example
.package(url: "https://github.com/rcbj/swift-oidc-caep-native-app", from: "0.1.0"),
and depend on the OIDCCAEPClient product. The detailed guide is
OpenID Connect and CAEP clients.
| Product | Platform | Repository | Documentation |
|---|---|---|---|
OIDCCAEPClient |
macOS 13 or later; Linux desktops too | rcbj/swift-oidc-caep-native-app | documentation |