Skip to content

What's new in 3.0

Version 3.0 runs on .NET 11 and serves every issuer as a tenant. This page describes what the release adds and what it does differently. What a 2.x deployment has to change to move to 3.0 is in Upgrading to 3.0.

Multi-tenancy

One server serves several issuers, each of them a tenant. The tenant of a request is resolved from the issuer it names, by host and path. A tenant declares what is its own: its clients, scopes, resources and default resource, the pages the end user sees, its security profile, its pairwise key, its signing and decryption keys, and the host its mutual TLS aliases are served at. A deployment that serves one issuer declares one tenant.

What the server stores for a tenant (its codes, tokens, minted keys and budgets) is kept under the tenant's identifier and generation, so a tenant created again under the identifier of a removed one takes over none of it. An identifier and a generation hold only ASCII letters, digits, hyphens and underscores, and a tenant with any other character is refused wherever it arrives: in the settings, from a store, or through the tenant manager. A tenant the settings declare that the server's own startup checks would refuse stops the server at startup.

The users and their consents stay the host's. A host that keeps them apart per tenant reads the tenant of the request from the tenant accessor. The multi-tenancy article shows a server with several tenants from start to finish.

Tenants managed at run time

The tenants are read from a store at startup and again every period, so a tenant a host creates, changes or removes reaches every instance without a restart. The tenants the settings declare are the default store. A host changes tenants through the tenant manager. It judges each change by the startup checks, refuses with a reason the host can act on, and also refuses a change made against an earlier version of the tenant.

A change refused for a conflict with another tenant, such as a shared key or address, is reported without naming that tenant, so the host can pass the refusal on to whoever is changing their own tenant; the host's log names both.

A tenant in the store that the checks refuse is left out and logged while the others are served. What the server keeps for a tenant the store stops listing (its keys, budgets and cached pages) is released one refresh period later, and its minted keys are deleted from the key store. A host registers an ITenantClosing to release what it keeps outside the server for a released tenant.

Security profiles

A security profile holds a client, or every client of a tenant, to the requirements of a FAPI specification that the server can enforce. Every release is tested against the OpenID Foundation conformance test plans for the OpenID Connect profiles, FAPI 2.0, FAPI 2.0 Message Signing, FAPI 1.0 Advanced and FAPI-CIBA, on both the MVC and the Minimal API adapter, and is not published unless they pass. The test suite of version 3.0 covers over 90% of the lines and branches of the hand-written code its packages ship.

  • FAPI 1.0 Advanced holds a client to the requirements of FAPI 1.0 Part 1 and Part 2. Its access tokens are bound to the client's mutual TLS certificate, and a token request carrying a DPoP proof is refused. A request object's nbf and exp are bounded, and a request object without them is refused. Under it, UserInfo returns the FAPI interaction identifier the client sent, or a new one, and logs it, without any code from the host.
  • FAPI 2.0 Message Signing comes as profiles for signed authorization requests, signed authorization responses, or both. Under signed requests, plain parameters pushed to the pushed authorization request endpoint are refused, and a request object's aud, nbf and exp are bounded, and a request object without nbf or exp is refused. FAPI 2.0 alone does not constrain them. Under signed responses, a code request without a JARM response mode is refused.
  • FAPI-CIBA: under FAPI 1.0 Advanced the backchannel authentication endpoint takes only signed requests and refuses the push mode.

Every token the server signs, encrypts or accepts is held to the algorithms of the security profile in force for the client involved, and discovery advertises only those. A registration that names no signing algorithm is given one the tenant's keys can produce under its profile.

Tokens

JWT introspection responses

A JWT introspection response, as RFC 9701 defines it, no longer needs a signing algorithm registered for the client. A caller asking for the JWT representation gets one signed with the algorithm the client registered (IntrospectionSignedResponseAlgorithm), or by default with RS256, or with PS256 or ES256 under a FAPI profile. The response is encrypted only when the client registered for it. The weights in the Accept header decide between the JWT and JSON. When no signing key of the tenant produces the JWT, a caller that accepts JSON gets JSON, and any other gets 406 Not Acceptable. A client whose registration the server cannot serve, such as an algorithm outside its profile or an encryption with no key to encrypt to, is answered 400.

Explicit typing of every JWT validation

Every validation of a JWT names the token types it accepts, allows a token that carries none, or states that the caller judges the type. A validation that states nothing fails before the token is read, as RFC 8725 section 3.11 asks. The server names the accepted types wherever it reads one of its own tokens back, so a token it issued for one purpose is refused wherever another is expected.

The introspection and revocation endpoints read access, refresh, registration and initial access tokens. An ID token named in a request, or exchanged as an ID token, may carry no type or the generic JWT type. A JWT bearer assertion without a type is accepted whether or not types are listed, and a listed type matches with or without its media type prefix.

Revocation reaches every token of a grant

As in 2.x, a refresh token presented again after it was rotated revokes its grant, as RFC 9700 section 4.14.2 describes. In 3.0 the access tokens issued for that grant carry its grant family too, so wherever this server checks a token it issued, they are refused as well. Revoking a refresh token at the revocation endpoint revokes the whole grant the same way. A token exchanged from a token of the grant joins that family and expires no later than the token it came from. A resource server that checks access tokens on its own does not learn of the revocation, and those tokens end at their expiry.

A rotated refresh token is spent once: of requests presenting it at the same moment, one is served, and the others are refused and revoke the grant, as a later presentation does. With the built-in storage over a distributed cache, this holds within one server process; a deployment on several nodes registers a storage whose backing store decides the write itself, as choosing a cache backend describes.

Refresh token reuse policy

A client whose access tokens are always bound to a key it proves cannot have a stolen refresh token used elsewhere, so by default its refresh tokens are reused, and every other client rotates them. The policy is one of reuse only for such a client, always reuse, or always rotate. A client registered for CIBA push delivery, or for a response type that returns an access token from the authorization endpoint, rotates under the default, even under a security profile that otherwise forbids rotation.

Revoking one user's tokens at one client

A host revokes every token one client holds for one user, including its refresh tokens, without signing the user out of their other clients or sessions: what withdrawing consent from that client calls for (OpenID Connect Core 1.0 section 16.18). The client stops reaching the user's data on its next request rather than when its tokens expire, and reaches it again only through a new authorization.

A code, a device authorization or a CIBA request approved before the revocation is refused at redemption, and an ID token issued before it cannot be exchanged for a new access token. A token another client obtained by exchanging one of this client's tokens belongs to that other client and is left alone. A host revokes through the token revoker; token inventory and revocation describes it.

The state hash in the ID token

The ID token returned from the authorization endpoint carries the state hash (s_hash) when the request had a state, and an ID token returned beside a code and an access token carries the hash of each (c_hash and at_hash), whatever order the host registered the response builders in.

Clients, scopes and resources

A default scope per client

A client can carry a default scope, used when a request names none: the pre-defined default value RFC 6749 section 3.3 lets a server use. It applies to authorization, pushed authorization, device authorization and backchannel authentication requests, and to token requests of the client credentials, password and JWT bearer grants, and it is held to the client's allowed scopes as a scope the request named would be.

For a client set to require a scope, a request naming none is refused as an invalid scope; without either setting, such a request is served with no scope. A client registering without a scope member may request the scope set the host names for new clients, as RFC 7591 section 2 allows.

The resources each client may get an access token for

A host can list the resources a client may get an access token for, as it lists the scopes the client may ask for. The list is checked against the audience of each access token, whether the resource was named by the request, inferred from the scopes, carried over from an earlier grant, or is the tenant's default resource, at every endpoint that takes a resource. A resource outside the list is refused as an invalid target, and a resource taken off the list is refused at the next use of a grant holding it.

A client with no list may get a token for any registered resource. A dynamically registered client is given the list the host grants new clients, and may narrow it, never widen it.

One resource per access token

A client can be held to one resource per access token. Its authorization may still grant several resources, and each token request then names the one its access token is for, as RFC 8707 section 2.2 shows. A token request naming several, or naming none while its grant holds several, is refused as an invalid target, and the authorization code it carried can still be redeemed naming one. Requests with no later token request to name one at (an authorization request returning an access token, a device authorization request and a backchannel authentication request) are refused when they name several.

A resource inferred from the scopes

With scope-based resource inference turned on for a tenant (TenantDefinition.InferResourceFromScope), a request naming no resource is taken to be for the registered resource that declares one of its scopes, and one whose scopes belong to several resources is refused as an invalid scope. At the token endpoint this applies to a grant the request itself authorizes and that names no audience; a code, a refresh token, a device code or a backchannel request keeps the audience its authorization settled. A token's audience is the resource the request names, else the one its scopes belong to, else the default resource, else the issuer.

Dynamic client registration

  • Registration accepts, stores and returns response_modes, judged against what the discovery document publishes.
  • The registration, read and update responses return every metadata value the server stores for the client, as RFC 7591 section 3.2.1 and RFC 7592 section 3 require, each under the name the registration request gives it. The responses are built from one mapping, so they return the same set. The default maximum authentication age is read and returned as a number of seconds, as OpenID Connect Dynamic Client Registration 1.0 section 2 defines it, and the sector identifier URI is kept and returned as it was sent.
  • A client registering for client_secret_jwt authentication does not send a key set, since it signs with its issued secret.
  • Every client names the issuer, as a string, as the only audience of its JWT client authentication, as RFC 10070 requires. A host can grant one client (ClientInfo.ClientAssertionAudiences), or every new client (NewClientOptions.ClientAssertionAudiences), another form while it changes: the token endpoint, the backchannel authentication endpoint, the pushed authorization request endpoint, or an array holding the issuer beside other values. All are off by default, and FAPI 2.0 refuses them. Where an endpoint is granted, its path at the tenant's mutual TLS address is accepted too.
  • A server without a pairwise key refuses a registration asking for pairwise identifiers, advertises only public subject identifiers, and does not start with such a client configured.
  • Two configured clients whose identifiers differ in case alone, a resource named by a relative address, and two resources under one address stop the server at startup, instead of failing a request once it builds the registries.

Any port on a loopback redirect address

A desktop app may listen on whatever port the operating system gives it at sign-in: a registered redirect address on http://127.0.0.1 or http://[::1] accepts any port in the authorization request, as RFC 8252 section 7.3 requires. The path and query still have to match, and an address carrying user information or a fragment is refused. The token request carries the same address as the authorization request, including the port. localhost and every other address keep exact matching, and dynamic registration points native clients to the loopback IP addresses. The native apps guide shows a desktop client.

Offline access beside an access token returned through the browser

A host can let one client, or every client that registers dynamically, receive a refresh token from a hybrid response that also returns an access token through the browser, which OpenID Connect Core 1.0 section 17.4 otherwise rules out. It is off by default, and the client still needs offline access and the consent it requires.

Sign-in, consent and interaction

Keep me signed in

A host states at sign-in whether the session survives a browser restart, and the session management cookie then lasts as long as such a session.

A host step before anything is issued

Once a single session answers an authorization request, and before consent is read, the server asks the host whether the end user must first complete a step of its own, such as accepting a new version of the terms or changing a password. A required step sends the end user to the interaction page with the selected session, and a request forbidding interaction gets the interaction_required error. The host records the completed step itself, and the request coming back from the page proceeds. A host that registers no step sees no change.

Several prompt values in one request

An authorization request may ask for several prompts at once, such as a login followed by consent, in any order and with repeats, and the end user meets the pages in the server's order, account creation before authentication. Asking for no interaction together with any other value is refused at the client's redirect address, as OpenID Connect Core requires, and a value the server does not support is answered with 400.

  • When a consent grants authorization details, the validator for each type sees the entries of that type the client asked for: at the authorization endpoint, when a backchannel authentication completes or is redeemed, and when a device code is redeemed. A payment type can therefore refuse a granted amount higher than the one requested, or a different account.
  • A consent provider reporting that the end user consented to nothing the request asked for has the server answer the client with access_denied. A request asking for nothing a consent could grant is never refused this way.
  • A server set to grant every client everything it asks for completes a request that asks for consent through the prompt parameter without a consent page.

Claims the request requires

  • A request marking a claim as essential is answered with what the host holds when the host's provider does not return that claim, as OpenID Connect Core 1.0 section 5.5.1 requires. A host that wants its own policy over which claims must be present registers its own claims provider.
  • When a request asks for the authentication context class as an essential claim of the ID token and names the values it accepts, session selection drops every session at another level, or at none, so the end user reaches the login page, and a request forbidding interaction is refused with the unmet authentication requirements error. A decoupled authentication is judged when the host completes it, and the token endpoint judges the level again on the grant it redeems.
  • The claims parameter can name the end user a request accepts, as one value or a choice of several. A request whose qualifiers agree on nobody is answered as an invalid request.

A request passed by reference comes back from the login page

An authorization request sent by reference, through request_uri, comes back from the login page and is answered with a code: the fetched request object takes the place of the reference in the request kept for the page.

Sessions and logout

  • Every client of a session is told when it ends. The server records each client that signs in to a session as a record of its own, so a browser opening two relying parties at once has both of them notified at logout. A client is recorded only when the authorization issues something, and the records are kept for OidcOptions.SessionClientsRetention, which a deployment sets to at least the lifetime of its authentication cookie.
  • A deployment on several nodes keeps the records in a store that decides them across nodes. Notifying the clients of an ended session is a component of its own, which a host ending a session some other way can call.
  • Signing in as somebody else ends the session it replaces, the way a logout ends one: its tokens are revoked when the deployment revokes them on logout, and its clients receive back-channel logout notifications. The sessions are ended only after the new one is written, so a sign-in that fails signs nobody out. Signing in again as the same person, for a re-authentication or a step-up, notifies nobody and keeps the session's identifier.
  • A host names the logout channels it serves, front channel or back channel, and the configuration document describes that deployment. A host that serves neither keeps its end-session endpoint.
  • The answer to the logout question carries a value this server issues, which belongs to one session, is spent when used, and expires with the confirmation lifetime setting. An ID token hint is compared with the session it would end, and a hint naming another end user or session asks the end user, as OpenID Connect RP-Initiated Logout 1.0 section 2 requires.
  • Two overlapping first logout requests for one session receive the same question, so the end user's answer stays valid. With nobody signed in, a logout request is answered with its redirect.
  • A logout request that names a post-logout redirect address but no client is served: the end user confirms, the session ends, and nobody is redirected, since nothing confirms the address.
  • The back-channel logout receiver gives back the replay reservation of a logout token when the application did not end the sessions, so the provider's retransmission reaches the application.

Keys and custodians

  • When an external key custodian cannot be reached or refuses, the library chooses the status, and no response carries text derived from the failure. A temporary failure is answered as service unavailable, with how long to wait when the custodian named an interval (RFC 9110 section 15.6.4). While it lasts, the last key set read from the custodian is published, so relying parties keep verifying tokens already issued. Each failure is logged once with the custodian, the operation and whether waiting will help.
  • When a token names a key that the server's copy of its signer's key set does not hold, the server reads the set again before judging the token, as OpenID Connect Core 1.0 section 10.1.1 describes, for clients, software statement issuers and trusted assertion issuers alike. A signer that rotates its key is accepted on its next request. The server reads one address again at most once per interval, a setting of its own, and a read that fails keeps the keys it held.
  • A key management algorithm the host registers under its own name works end to end: client and server keys declaring it are used for encryption and decryption, as discovery advertises.
  • A minted key ring with no store to keep it is refused at startup, and the refusal names the call that supplies a store.
  • Adopting existing keys into a minted key ring completes a set whose writing stopped partway, and a key that cannot be adopted refuses the whole set before any of it is stored. A host adopting several keys of one role keeps every one of them published until the first minted key has signed for the retention window.
  • The Azure Key Vault custodian releases the cryptography client of a key version nobody has used for a while.

Signing key persistence describes the custodians and the key ring.

Introspection, revocation and the device flow

Per-client budgets on introspection and revocation

Both endpoints verify a signature on every call, so a resource server whose cache broke can make them the most expensive path in a deployment. Each endpoint spends its own budget belonging to the calling client (OidcOptions.CallerRateLimit), charged once the client is authenticated and before the token is read, so a client that has spent its introspection budget can still revoke a token. A public client's revocation is charged to its identifier together with the address it came from.

The budget is the platform's rate limiter registered under a published key, which a deployment counting across nodes replaces. A second budget, off by default, counts failed client authentications per source address at every endpoint that authenticates a client.

Limits on guessing a user code

A code a person types is short, so slowing guesses down does not stop them. Limits of different kinds apply, all under OidcOptions.DeviceAuthorization. A code that can no longer be used, because it was approved, denied or has expired, answers that it was already used for MaxUserCodeAttempts attempts, and after that like any unknown value. One address may fail MaxAddressFailuresPerWindow times within the counting window, RateLimitWindow, as it could in 2.x under the name MaxIpFailuresPerMinute. And the server keeps a budget of failed verifications within the window, MaxFailedAttemptsPerWindow, the only limit that bounds a search spread across addresses. While that budget is spent, every verification is refused, which an attacker can use to keep the device flow unusable. The settings documentation therefore carries the arithmetic for weighing the address limit against the budget, together with the code's length and alphabet.

The device flow

  • The device and user codes are kept through the server's entity storage, so a host that replaced the entity storage holds them there too. The instant a polling client may ask again lives under a key of its own, so an approval or a completion arriving beside a poll is not overwritten by it.
  • A device code carries the instant it expires, so a poll after the server dropped the expired request is answered that it expired.
  • The address the end user enters the code at may be relative, and is then a page under the issuer, so a deployment serving several issuers from one host sends each issuer's users to a page of its own.
  • A device authorization request may ask for a scope only a resource declares, beside that resource, and the host approving the user code receives that scope.

Decoupled authentication (CIBA)

A push client is sent the error payload of CIBA Core 1.0 section 12, access_denied when the end user or the server refused and transaction_failed when tokens could not be issued, and a ping client is pinged after a refusal as after an approval, as section 10.2 asks. A push completion takes the request before it mints, so a completion and a refusal arriving together answer the client once. Every auth_req_id polled after its expiry is answered expired_token.

Shared Signals

  • The server runs a Shared Signals transmitter per tenant, through a separate package. Each tenant's streams, queued events and delivery claims are kept apart, so two tenants may declare streams under the same identifiers. The transmitter answers as the tenant serving the request, with its addresses under that tenant's issuer, follows a tenant that moves to another issuer, and signs with that tenant's keys. A tenant declares the streams of its own receivers in configuration, and a released tenant's streams and queued events are deleted.
  • An event is signed as it is pushed or collected, with the time of that delivery, so an event that waited for its receiver to come back is accepted rather than refused as stale. It keeps its identifier, so a receiver that saw an earlier attempt recognizes it.
  • A receiver that refuses a pushed event and names a wait in the retry header of its answer, in seconds or as a date, is not sent to again before that moment.
  • A transmitter that maps the configuration document without the Stream Management API names no management address in it.
  • A host that maps the back-channel logout or push delivery route of a receiver without registering its handler is told which service is missing.

The Shared Signals guide sets up a transmitter and a receiver.

Tracing and metrics

Each endpoint request runs in a span of the server's activity source, under the host's HTTP server span, named after its endpoint and closed with the status its outcome tells; its stages (validation, processing, client authentication, grant handling, consent, signing and storage access) run in spans of their own. The server records how long each endpoint request takes and how it ended, the tokens it hands out by kind and grant type, signing time by algorithm, dynamic client registrations, requests refused for a spent budget, requests the license refused, and each call to its storage by operation. The Shared Signals transmitter traces and measures each event it queues and each token it pushes.

The request and token measurements name the tenant, and nothing names a client's credentials, an end user, a stream or a receiver's address. A host receives them by adding the source and the meter to its OpenTelemetry configuration, and adds attributes of its own to an endpoint span through an enricher. The observability article lists the names.

The protocol vocabulary package

The OAuth 2.0 and OpenID Connect vocabulary is a package of its own, Abblix.OIDC (namespace Abblix.Oidc), which the server references and a client can reference without the server: grant types, response types and modes, scopes, prompts, display modes, client authentication methods, token types, the token type hints of revocation and introspection requests, error codes and the PKCE code challenge calculation. The protocol claims of a token payload, the authorization detail type and its JSON helpers come from it too, as C# 14 extension properties, which a host pinning an older language version calls as static methods.

Single-use decisions across nodes

One entity storage with an atomic add-if-absent, such as Redis SET NX PX, makes every single-use decision of the server hold across nodes, including token replay detection. Choosing a cache backend describes what such a storage needs.

Hosting

  • The MVC and Minimal API hosts read a request the same way. A parameter that is empty or whitespace alone is absent on both. A typed one that cannot be parsed, such as the claims parameter, the maximum authentication age or an address, is refused with an invalid request error and the same error body on both. A blank entry in a list such as the resources is dropped, and a parameter that takes one value is refused when it repeats.
  • On the MVC host, a request field carrying the name of an action parameter is ignored like any other unrecognized parameter, and a host that nests a library request model inside a model of its own has it bound from the root.
  • A server allowed to run on an http issuer, for local development, answers its endpoints over http on both hosts. A server or tenant whose issuer is https still redirects a request over http, or refuses it when it is not a GET.
  • A host that registers no provider of user information, such as one serving client credentials alone, gets a stand-in that knows no user, so the token endpoint answers rather than failing on every request.

Other fixes

  • A token the server issued, read back at once by another instance whose clock lags the issuing one, is accepted.
  • Absent optional members are left out of the token response and of tokens pushed to a CIBA client, rather than written as null.
  • The scheme of the Authorization header is accepted in any case, and Basic credentials that are not base64 are answered invalid_client.
  • WWW-Authenticate error, error_description and scope values stay within the characters RFC 6750 allows, and an error answered without a Bearer challenge keeps its own status.
  • A UserInfo request whose parameter is refused is answered with the endpoint's authentication challenges.
  • An unsecured request object that names no client of its own is served at the authorization endpoint for the client named beside it, as OpenID Connect Core allows. A signed object, any object pushed to the pushed authorization request endpoint, and one under strict request object processing still name their client.
  • A client required to sign its requests is served under strict request object processing, at the pushed authorization request endpoint and at the authorization endpoint.
  • Under a FAPI 2.0 profile, a client that registers no response type, such as a resource server that only introspects tokens or a client of the client credentials, backchannel authentication or device grant, passes the startup check, dynamic registration and client authentication.
  • A request object member that cannot be read, such as a UI locale no culture has, is refused as an invalid request object. A request object may give the UI and claims locales as a space-separated string as well as an array.
  • An encrypted signed token carries the content type JWT, and a pushed security event token that is malformed is answered 400 invalid_request.
  • A stored authorization, device or backchannel request keeps its redirect address, request address, notification endpoint and resources exactly as the client wrote them.
  • A numeric additional claim kept in the cookie session comes back exactly as it was written.
  • A subject type converter a host builds itself refuses a pairwise salt the server's startup check refuses, and names the settings the salt came from.
  • The library holds every URI, duration and instant as a typed value, each instant with its offset, so each value is parsed once where it arrives and refused there when it is malformed. Values compared with what a client wrote, such as a token type or the audience of an assertion, are compared as written.