Upgrading to 3.0
Version 3.0 runs on .NET 11 and serves every issuer as a tenant. A 2.x server that serves one issuer declares that issuer as one tenant. The compiler and the first start show only part of the upgrade: a changed type or member fails the build, and a missing registration or a refused setting stops the server.
The rest is silent. A configuration key under its 2.x name is ignored. A host that does not map the endpoints starts and answers 404, and one that registers no logout channel starts and tells no client about a logout. The data the server stored is not read by 3.0 at all.
This page covers both kinds: every type and member a host meets at compile time, the settings that 3.0 renamed or removed, the behavior a client or a deployment notices, and the step that keeps your signing keys. Before the first 3.0 instance starts lists the steps in the order they are taken. What's new in 3.0 describes what the release adds, and the 3.0 release notes summarize it.
Before the first 3.0 instance starts
Most of these steps fail silently when they are skipped, so take them in this order. Each links to the section that explains it.
- Rename or remove every setting 3.0 renamed, in code and in configuration files: a configuration key under its 2.x name is ignored without an error (settings renamed or removed).
- Convert the records of a client store of your own: the registration access token's identifier,
OfflineAccessandReusePolicy(what the first 3.0 start does not carry over). - On 2.x, replace every signing key smaller than RFC 7518 allows, early enough that relying parties have fetched the new key set before 3.0 refuses the short key (keys and encryption).
- On a server configured with SHA1 as its pairwise hash, choose another hash and tell the owners of its relying parties (the pairwise hash).
- On a server that mints its own keys, shorten the access token lifetime on 2.x ahead of the cut-over, and copy the key ring entries into the tenant's partition (keeping the signing keys).
- Reissue the initial access tokens you handed out on 2.x (registering the server).
- With Shared Signals, let the event queues drain and stop every 2.x instance (Shared Signals).
- Ask the owners of relying parties what their client assertions put in
aud, and, for a client that cannot change yet, grant its current form for the migration (clients and registration). - Tell the owners of relying parties the cut-over date. Their users sign in again, and because refresh tokens issued by 2.x are refused, a client renewing tokens in the background with no user present fails until its user signs in (what the first 3.0 start does not carry over).
- Register what the server does not check at startup:
app.MapOidcControllers()on an MVC host and the logout channels your clients use. The server starts without either, but without the call every OpenID endpoint answers 404, and without the channels no client is told about a logout, so check both on a test instance (registering the server). The consent choice is checked: without it the server does not start. - Back up the key ring, then plan a cut-over rather than a rolling upgrade (running 2.x and 3.0 side by side).
Running 2.x and 3.0 side by side, and rolling back
3.0 keeps what it stores under the tenant, and 2.x keeps the same entries under names without a tenant. Neither version therefore finds the entries the other stored: codes and pushed requests, the records of revoked and rotated tokens, DPoP nonce secrets, replay reservations and Shared Signals queues. A 3.0 instance also reads a 2.x session as no session and refuses a 2.x refresh token.
Instances of both versions behind one load balancer therefore split the users and flows between them: a code issued by one is unknown to the other, and a user signed in on 2.x is asked to sign in again on 3.0. Move every instance at once: stop the 2.x instances as the first 3.0 instance takes traffic.
Where both versions answer for a while:
- A DPoP nonce one version issued is refused by the other, which answers with a fresh nonce, so a DPoP client retries its request with that one.
- A replay reservation one version made is not seen by the other until it expires, so a single-use value one version accepted can be accepted once more by the other.
Rolling back to 2.x once 3.0 has written its key ring is not supported. A 2.x server reads every entry of the ring, including those 3.0 wrote for each tenant, publishes them as one key set and may sign with any of them. It cannot read a key 3.0 stored with a certificate chain, and then does not start. It also misses the records 3.0 keeps of used and revoked tokens, so a rotated refresh token presented again is accepted. A rollback therefore restores the key ring saved before the first 3.0 start, and loses what 3.0 stored: its codes, pushed requests, revocation records and Shared Signals queues.
Registering the server
Everything that belongs to an issuer moves from OidcOptions into a TenantDefinition: the issuer itself, the clients, scopes and resources, the sign-in, consent and other pages, the security profile, the pairwise subject settings, the signing and encryption keys, the custodian key names, and the mutual-TLS addresses. The server-wide settings, such as lifetimes, the enabled endpoints and the license, stay on OidcOptions. A 2.x registration like
builder.Services.AddOidcServices(options =>
{
options.Issuer = "https://auth.example.com";
options.LoginUri = new Uri("/Auth/Login", UriKind.Relative);
options.SigningKeys = [signingKey];
});becomes one tenant:
// Grants every client everything it asks for, including prompt=consent, which suits only
// clients of your own; to ask the end user for consent, register your own IUserConsentsProvider
builder.Services.AddConsentGrantedForEveryClient();
builder.Services.AddOidcServices(options => options.Tenants.Add(new TenantDefinition
{
Id = "main",
Issuer = new Uri("https://auth.example.com"),
LoginUri = new Uri("/Auth/Login", UriKind.Relative),
SigningKeys = [signingKey],
}));Keep the issuer exactly as 2.x had it. A 2.x server that set no issuer took it from the address of each request; write that address exactly as its tokens carry it in iss. The tokens already out there name it, and the keys section below only helps a tenant at the same address.
The tenant id holds only ASCII letters, digits, - and _, and it becomes part of the names 3.0 stores data under, so pick it once.
A host meets these changes as well:
- The packages target .NET 11 alone. They also require newer minimum versions of the libraries they depend on: Google.Protobuf (
Abblix.OIDC.Server), StackExchange.Redis (Abblix.SharedSignals.Redis), Azure.Identity, Azure.Security.KeyVault.Keys and Azure.Storage.Blobs (Abblix.JWT.Azure), and the Microsoft.Extensions packages of .NET 11. A host that pins a lower version fails restore with a package downgrade error. - A server needs nothing in its pipeline to find the tenant of a request when all of these hold: it serves the one tenant its settings declare, that tenant's issuer has no path, and it registers no tenant store, catalog or store writer of its own. Such a server serves that tenant at whatever host name a request arrives with, except under a path base the host sets. A host that finds the tenant through a tenant accessor of its own needs nothing either. Every other server, such as one with several tenants or one whose tenant's issuer has a path, calls
app.UseMultiTenancy()before its own routing and authentication. Without the call the server stops as soon as it starts listening, and the error names the call and why it is needed; the multi-tenancy article describes both cases. - An MVC host maps the endpoints with
app.MapOidcControllers(), as a Minimal API host callsapp.MapOidcEndpoints(). The library's controllers carry no routes of their own, soMapControllers()and conventional routes do not reach them: without the call the server starts, and every OpenID endpoint answers 404. - A registry or a key provider of your own (
IClientInfoProvider,IClientInfoManager,IScopeManager,IResourceManager,ISubjectTypeConverter,IAuthServiceKeysProvider) receives the tenant as its first parameter. Your own entity storage, replay cache or rate limiter is registered under the keysTenantServiceKeysnames. - The interfaces your host implements for its users and their sign-in, such as
IUserInfoProvider,IUserConsentsProvider,IUserCredentialsAuthenticator,IUserDeviceAuthenticationHandler,IAuthorizationDetailsPolicy, and the issuer and key methods ofIJwtBearerIssuerProvider, take the tenant as their first parameter too. So do the services your host calls itself:ITokenRevoker,IUserCodeVerificationServiceandIAuthenticationCompletionHandler. Outside a request, pass them the definitionITenantCatalogreturns. - Neither logout channel is served until you register it; 2.x registered both with the server. Call
builder.Services.AddFrontChannelLogout()andbuilder.Services.AddBackChannelLogout()(namespaceAbblix.Oidc.Server.Features) for the channels your clients use. Without them the server starts and ends sessions, but tells no client about a logout. - An initial access token carries a
jtiand an expiry, and one that lacks either registers no client, so reissue the tokens you handed out on 2.x;IInitialAccessTokenService.IssueTokenAsynctakes the lifetime. Revoke a token by recording itsjtias revoked inITokenRegistryat the tenant that issued it.OidcOptions.RevokedInitialAccessTokenSubjectsis kept, marked obsolete, so that a configuration still listing subjects stops the server at startup instead of being ignored: remove the subjects once their tokens are revoked byjti. - Every tenant's issuer is an https address with no query, fragment, user name or password and no empty segment in its path, or the server does not start. A 2.x server run locally on an http issuer sets
OidcOptions.AllowHttpIssuer = true, which applies to every tenant and does not belong in production. - A token request that names a resource its grant does not hold is refused with
invalid_target, also when the grant holds no resource. A client redeeming an authorization code or a refresh token names only resources it was granted. - An access token carries the scopes of the resources it is addressed to, and the scopes no resource declares, rather than every scope of its grant. A resource server that read another resource's scope from a token addressed to it no longer finds it there.
- A dynamically registered client may name only the token exchange audiences
NewClientOptions.TokenExchangeAudiencesgrants, and is given those when it names none; with the option unset, it names none. 2.x let the client write its own list. - The server's
AuthServiceJwtFormatterwrites into every refresh token it signs the tenant the token was issued at, and the server refuses a refresh token that names none. A token formatter of your own (IAuthServiceJwtFormatter) therefore hands refresh tokens toAuthServiceJwtFormatterto sign, and a refresh token service of your own signs through it too. - The server does not start until the host chooses how consent is obtained. Register your own
IUserConsentsProvider, or callbuilder.Services.AddConsentGrantedForEveryClient()(namespaceAbblix.Oidc.Server.Features.Consents), which grants every client everything it asks for and suits only clients of your own. 2.x granted everything by default too, but sent a request carryingprompt=consentto the consent page; withAddConsentGrantedForEveryClientsuch a request completes without a consent page. - A Shared Signals transmitter registered as it was on 2.x does not start. Register the transmitter first, then chain
AddSharedSignals()(packageAbblix.OIDC.Server.SharedSignals) onto whatAddOidcServicesreturns, so each tenant transmits as itself and signs its events with its own keys, and leaveSecurityEventsOptions.SigningKeySourceunset. Declare each tenant's streams withAddConfiguredStreams(tenantId, streams)on the same chain instead of streams for the whole server. - The Shared Signals transmitter's own issuer names the host alone, with no path, and its key set address is absolute and on that host, because each tenant's addresses are put under the tenant's own issuer.
- Every part of the transmitter a host takes from the container, the event dispatcher among them, belongs to the tenant served at that moment, so take it in the request or tenant scope of the tenant the event belongs to: one kept in a singleton throws once it is used where its tenant is not served. A subject identifier member that RFC 9493 defines as a URI and that is not an absolute URI is refused.
The multi-tenancy article describes all of it, and the getting started guide shows a complete host.
Log records
A deployment whose alerts or log filters key on a category or a message checks these:
- When a JWS signature check finds no signing key, no key that matches the token's header, or only a key below the size floor, the record is written under the category
Abblix.Jwt.JwsSignatureVerifierinstead ofAbblix.Jwt.JsonWebTokenSigner. The event ids of these records stay the same. - The Vault package (
Abblix.JWT.Vault), the Azure package (Abblix.JWT.Azure), the security events package (Abblix.SecurityEvents) and the Shared Signals package (Abblix.SharedSignals) log under new event id ranges, each event keeping its offset within its range. An alert keyed on an event id of one of them is rewritten to the new id. - An inbound encrypted token that no key of the server opens is recorded as a warning under
Abblix.Jwt.Encryption.JweDecryptionLog: one event for a token no key is available for, one for a token whose candidate keys cannot be used with its algorithm, and one for a token none of the candidate keys opened. - Log records name a device code, a user code or a CIBA request id by a fingerprint. On several instances, set
OidcOptions.FingerprintKeyto the same secret everywhere, so the records of one flow match across instances and restarts; left unset, each process draws its own key. The production hardening checklist describes the key and how to keep it.
Types a host implements or constructs
A host that only registers the server and implements the interfaces listed above meets few of these: UserConsents.GivenAt in a consent provider of its own, IAuthorizationDetailsPolicy.ApplyGrantedAsync, and IAcrMetadataProvider, whose supported values take the tenant. A host that implements, derives from or constructs one of these types meets them, most as a compile error and some as a contract its code still compiles against and now has to keep:
ICertificateProviderandCertificateIdare gone fromAbblix.Utils, which neither used nor implemented them. A host that implements the interface declares it in its own code.- The CIBA
CompositeRequestFetcher(namespaceAbblix.Oidc.Server.Endpoints.BackChannelAuthentication.RequestFetching) is gone: the server registers a singleIBackChannelAuthenticationRequestFetcherand never used the composite. A host that chained fetchers of its own through it chains them in its own code. - The device authorization and CIBA components take
CredentialFingerprints(namespaceAbblix.Oidc.Server.Common), the source of the fingerprints in their log records:DeviceAuthorizationStorage,UserCodeRateLimiter,InMemoryLongPollingService,AuthenticationCompletionRouterand the completion handlers below. A host that constructs one of them itself passes it.AuthenticationCompletionRouteralso takes theIBackChannelRequestStorage, which a host constructing the router passes too. - The CIBA completion handlers,
PollModeCompletionHandler,PingModeCompletionHandler,PushModeCompletionHandlerand their baseAuthenticationCompletionHandler, take aTimeProvider, the clock that records when the end user approved the request.PushModeCompletionHandleralso takes theIRevocationCutoffCheckerit asks before it mints tokens. A host that constructs or derives from these handlers passes them. JsonWebKeyConverteris sealed. A host that derived its own converter from it writes that converter as a separateJsonConverter<JsonWebKey>and registers it.- The helpers for JSON Web Keys in
Abblix.Jwtlive in one class per subject:CertificateJsonWebKeyExtensionsfor a certificate,RsaJsonWebKeyExtensionsfor an RSA key,EllipticCurveJsonWebKeyExtensionsfor an elliptic-curve key, andKeySizeFloorsfor the key size floors (MinimumRsaKeyBits,RsaSectionFor,RsaSectionForOrNothing). - A call to these JSON Web Key helpers written as an extension method compiles unchanged. Code that reaches a moved member through the old class, such as
JsonWebKeyExtensions.MinimumRsaKeyBitsorJsonWebKeyExtensions.RsaSectionFor, names the new one;JsonWebKeyExtensionsnow holdsFirstByAlgorithmAsyncandComputeJwkThumbprintBase64Url. An assembly compiled against 2.x that calls these helpers is rebuilt against 3.0. IScopesAndClaimsProviderkeeps onlyGrantTypesSupportedandSubjectTypesSupported: discovery reads the supported scopes and claims fromIScopeClaimsProvider. A host that advertised scopes or claims through the first moves them to the second.IJwtBearerIssuerProvider.IsReplayedAsyncis gone: the JWT bearer grant asks the replay cache itself.IAuthServiceKeysStore,AuthServiceKeyDescriptorandKeyLifecycleStatusare gone too; the key ring store keeps the keys the server mints.- The constructor of
JwtBearerGrantHandlertakesProfiledJwtValidatorin place ofIJsonWebTokenValidator, andJwtBearerAssertionPolicy, whichAddJwtBearerGrantregisters, in place ofIOptions<OidcOptions>. This touches only a host that constructs or derives from the handler. IAuthorizationDetailsPolicy.ApplyGrantedAsyncandIAuthorizationDetailValidator.ValidateGrantedAsynchave no default body, so an implementation declares both.JwtBearerOptions.ResolveClockSkew(ClientSecurityProfile)is gone; the form takingSecurityProfileRequirementsis the extension methodJwtBearerOptionsExtensions.ResolveClockSkew.JsonWebKey.ComputeJwkThumbprintBase64Url,JsonWebTokenPayload.TryReadTimestamps, the typedWithEventandSignAsyncofSecurityEventTokenBuilderandTransmitterConfigurationClient.GetAsync(issuer)are extension methods now: a call compiles unchanged, and an assembly compiled against 2.x is rebuilt.SecureUriValidatorrequires its logger and no longer hasIsInternalHostnameorIsPrivateOrReservedAddress. The CIBA completion handlers require their long-poll notifier.- Each response formatter contract is one generic interface in
Abblix.Oidc.Server.AspNetCore.Formatters,I*ResponseFormatter<TResult>, closed overActionResulton an MVC host andIResulton a Minimal API host. A decorator written for the non-generic form names the closed one, such asIEndSessionResponseFormatter<ActionResult>. AuthServiceJwtFormatter,ProfiledJwtIssuer,ClientEncryptionKeyResolver,JwtAlgorithmsProviderandConfigurationHandlertake anEncryptionAlgorithmsProvider(namespaceAbblix.Jwt). A host that constructs one of them passes it.AuthServiceJwtFormatter,ClientJwtFormatterandSignedMetadataProvideralso take aSigningAlgorithmsProvider(namespaceAbblix.Jwt), and aProfiledJwtIssuerin place ofIJsonWebTokenCreator.AuthServiceJwtFormatterandClientJwtFormatterno longer takeIOptions<OidcOptions>, andClientJwtFormattertakes its logger and aClientEncryptionKeyResolverin place ofIClientKeysProvider. A host that constructs or derives from one of them passes them.IEntityStoragehasTrySetIfAbsentAsync, and the server's replay reservations go through the entity storage. An entity storage of your own implements it so that exactly one of concurrent callers wins, in a single operation of its store.- The server's stores, token services, client authenticators and endpoint handlers take the tenant as their first parameter, like the interfaces above: among them
IEntityStorageKeyFactory,ITokenRegistry,IRevocationCutoffRegistry,IAuthorizationRequestStorage,IDeviceAuthorizationStorage,IAccessTokenService,IRefreshTokenService,IAuthServiceJwtFormatter,IClientJwtFormatter,IClientAuthenticator,IAuthorizationHandlerandITokenHandler, and the host interfaceIAcrMetadataProvider, whoseAcrValuesSupportedis a method taking the tenant. A store of your own keeps each record in the space of the tenant it is handed. JsonWebTokenPayloadno longer has the OpenID Connect claim properties, such asSessionId,ClientId,Scope,Nonce,AuthenticationTimeand the DPoP claims: they are extension properties in theAbblix.OIDCpackage, and code reading them imports theAbblix.Oidcnamespace.DPoPHttpUriis aUri.ComputeJwkThumbprintBase64UrlandTryReadTimestampsare extension methods inAbblix.Jwt, so a file calling them imports that namespace.IIssuerProvideris gone: a service of the host's own reads the issuer and the other settings of a tenant offTenantDefinition, whichITenantAccessorgives for the request.LicenseChecker.CheckIssuertakes the tenant and theITenantCatalogafter the issuer.- The
Abblix.Oidc.Server.Mvc.Pathconstants and the MVCIEndpointResolverare gone, since the endpoints carry no route templates of their own. A host that builds an endpoint's address, such as a callback pointing at the authorization endpoint, asksIOidcEndpointResolver.Resolve, which answers with the absolute address the endpoint is mapped at, including a moved path and a prefix.
Sessions and sign-in
IAuthSessionService.SignInAsyncreturns anAuthSessionSignInResult, naming the session it wrote and the sessions it ended. A session service of your own ends each replaced session throughIAuthSessionTerminator, which is registered per request, and drops any notification of its own: a host that notified the clients of a replaced session from its sign-in code notifies them twice.AuthSession.AffectedClientIdsis gone, since the server records the clients of a session itself.- A session service of your own fills
AuthSession.SignedInAt, the moment the session it reports was signed in, and a consent provider of your own fillsUserConsents.GivenAt, the moment consent was given; without it, the consent page is shown again every time the end user returns from it. ISessionManagementService.GetSessionCookietakes the tenant and aSessionPersistence, so the check-session cookie lasts as long as a session that survives a browser restart. A host that buildsSuccessfullyAuthenticateditself, such as in its own decorator of the authorization processor, sets its requiredSessionPersistence, taking it fromAuthSession.Persistence.
Tokens and revocation
- A token this server issued is checked for revocation, rotation and revocation cutoffs by
IAuthServiceJwtValidator, against the tenant it validates the token for.TokenStatusValidatorDecoratoris gone, so the generalIJsonWebTokenValidatorno longer makes this check: a host that validates this server's tokens through it validates them throughIAuthServiceJwtValidatorinstead. - Registered on its own,
AddAuthServiceJwtbrings the revocation records, which needIEntityStorage,IClientInfoProviderandISubjectTypeConverter; a host composing the registrations one by one registers those too. IAccessTokenService.CreateAccessTokenAsynctakes the grant identifier and the latest moment the token may expire, and an implementation of your own writes both into the token it issues and sets its issue time and expiry, which the token response reads its lifetime from.ITokenRegistryhasTrySetStatusAsync, which records a token's status only when nothing is recorded for it yet and decides that in one step.IRefreshTokenServicehasTrySpendAsync, which answers false for a refresh token already spent, andCreateRefreshTokenAsynctakes the grant identifier.- An
IRevocationCutoffRegistryof your own keeps, inSetCutoffAsync, the later of the recorded cutoff and the one it is given, and the later of their expiries. IIdentityTokenService.CreateIdentityTokenAsynctakes anIdentityTokenRequest, which carries the authorization request's state, and returns a result that may carry an error.ISubjectTokenResolver.ResolveAsynctakes the tenant, the client and the token type. A resolver of your own answers a null scope for a token carrying no scope claim: an empty scope bounds the scope a token exchange may ask for, as the scope of any other token does.- A grant handler of your own (
IAuthorizationGrantHandler) puts the resources of the token request, including a resource inferred from the scope, into theResourcesof the grant's context, or every token request naming one is refused. - A token endpoint validator list built by the host includes
DPoPBindingValidator, which checks the key or certificate a grant was bound to, afterAuthorizationGrantValidator, or those checks do not run;GrantNarrowingValidator,SingleResourceValidatorandAllowedResourceValidatorare new steps of the same list.ITokenAuthorizationContextEvaluatortakes the tenant. - The interfaces that validate or format the server's own tokens and DPoP proofs, parse
id_token_hintand validate pushed requests take the client or its security profile:IAuthServiceJwtValidator,IClientJwtValidator,IClientJwtFormatter,IProofValidator,IDPoPUserInfoValidator,IIdTokenHintParserandIPushedAuthorizationRequestValidator.UserInfoRequestcarries the access token from the query and the one from the form separately, asAccessTokenInQueryandAccessTokenInForm. IAuthorizationDetailsPolicy.ApplyAsyncanswers with a set, never null, and an empty set for a request carrying entries raises an error.
Storage
- An entity storage of your own implements
TryReplaceAsync, which replaces an entry only while it still holds the value the caller read, andTryExtendAsync, which gives an entry still stored a later expiry and never writes back an entry the key has stopped holding. Each decides between concurrent callers, asTrySetIfAbsentAsyncdoes.TryReplaceAsynccompares values, not stored bytes, and reports a write to a caller whose value is still there. A store that never reports one fails every revocation of a principal that already has a revocation. IEntityStorageKeyFactoryof your own names the new keys, among themSessionClientsRenewalKey(the note that a session's list of clients was renewed), the per-client session records, the logout confirmation and the poll and rate limit keys of the device and CIBA flows.- A replay cache of your own (
IReplayCache) implementsReleaseAsync, which gives a reservation back. - The registration method
AddDistributedReplayCacheis in the JWT package (Abblix.Jwt), and the server and the security events receiver keep single-use values in one replay cache, whichever package a host registers first. The server's own store writes its entries under the server's key prefix; a replay cache the host registers itself is kept as the shared store, without that prefix, and the server reserves in it too.IJwtReplayCacheandDistributedJwtReplayCacheare gone. IAuthorizationValueReuseDetector, the reuse detector of PKCE code challenges and nonces, answers throughTryReserveAsyncwhether the caller was first, instead of only recording a value. Ended pushed authorization flows are recorded by a newIConsumedRequestUriRegistry, whoseTryConsumeAsyncanswers whether the caller was first.
Client authentication and requests
IClientAuthenticator.TryAuthenticateClientAsyncreturns one of these outcomes: the client is authenticated, a credential was presented and refused, or no credential was presented at all (ClientAuthenticationFailures). An empty answer is not valid. An authentication method of your own also implementsFindPresentedCredentialsAsync, reporting where in the request it finds its credential.ClientRequestandClientRegistrationRequestcarryAuthorizationHeaderLines, from whichAuthorizationHeaderis computed, andClientManagementController.RegisterClientAsynctakes the lines.SecurityProfileRequirements.RequireIssuerAudienceInClientAssertionis gone, since every client names the issuer as its audience;RequireStringAudienceInClientAssertionis the profile's demand that the audience be a string. A host lets a client keep another form of audience throughClientInfo.ClientAssertionAudiences, or every new client throughNewClientOptions.ClientAssertionAudiences.IRequestObjectFetcher.FetchAsynctakes the tenant, the client, the members a caller forbids, the required signing algorithm, which has no default, and a rule the endpoint applies to the validated token.IBackChannelAuthenticationRequestFetcherandIBackChannelAuthenticationRequestValidatortake the authenticated client.- The step that checks the initial access token is
IInitialAccessTokenValidator, and a host that replaced or decorated it implements that interface. A host that replacedUpdateClientRegistrationValidatorreplaces a step of the metadata validation pipeline (IClientRegistrationContextValidator) instead. - A user code rate limiter of your own (
IUserCodeRateLimiter) receives null when there is no address, and counts those attempts together under a name no address can take.CheckAsyncanswers an allowed attempt with null and a refused one with aUserCodeRateLimited, andRecordUnknownCodeAsynccounts a value no code carries.
Keys and JOSE
JsonWebTokenHeaderreads and writes the parameters that can be malformed through methods:TryReadCriticalandSetCritical,TryReadVerificationKeyandSetVerificationKey,TryReadCertificatesandSetCertificates,TryReadEphemeralPublicKeyandSetEphemeralPublicKey. A read reports a malformed value without throwing.- A key custodian of your own (
IKeyCustodian) implementsServesKeyManagement, answering whether it serves a given key management algorithm, and returns null fromAgreeKeyAsyncwhen it cannot agree with the key and fromUnwrapKeyAsyncwhen it does not serve the algorithm, without throwing. An exception it throws from key agreement reaches the caller, and a condition that may clear is reported withKeyCustodianUnavailableException. - With keys in an external custodian, the startup check of each tenant's custodian keys runs no matter who serves the keys, so a host that wraps
IAuthServiceKeysProviderin a cache keeps it. A host that replaced the provider and picks keys itself, with tenants naming none, chooses another key placement. ISecureHttpFetcher.FetchAsync,IClientKeysProvider.GetSigningKeysandIJwtBearerIssuerProvider.GetSigningKeysAsynctake arefetchargument that asks to read a key set again instead of using any copy held. The key sets the server fetches go through the library's own fetcher, so a fetcher of the host's own registered before the server is not used there.IJsonWebTokenCreatorhasEncryptClaimsAsync, which encrypts a claims set, andEncryptedResponseMethodsSupported.IJsonWebTokenEncryptor.EncryptAsynctakes the content type.- A
JsonWebKeytype of your own writes its thumbprint input throughWriteCanonicalMembers(Utf8JsonWriter). - The
SupportsAlgorithmextension ofJsonWebKeyis gone. Whether a key can sign with an algorithm is answered bySigningAlgorithmsProvider.CanSign(key, alg), and whether it can encrypt with one byEncryptionAlgorithmsProvider.CanEncrypt(key, alg). Both providers are public now and come from dependency injection;SigningAlgorithmsProvider.FirstSignedWith(key, algorithms)names the first of several algorithms a key can sign with. FirstByAlgorithmAsynchas one form, inAbblix.Jwt:FirstByAlgorithmAsync(alg, kid, canPerform), wherecanPerformisCanSignorCanEncryptof those providers. The forms inAbblix.Oidc.Server.Commontaking an algorithm, or an algorithm and a key id, are gone. A null algorithm no longer answers null: with no key id either, the first key is returned, so code that relied on null meaning unsigned checks the algorithm itself.ISignatureAlgorithm<TKey>andIKeyManagementAlgorithm<TKey>haveAccepts(key), which accepts every key unless overridden. An algorithm of your own compiles unchanged, and overridingAcceptslets it refuse a key by its material.IAuthorizationResponseBuilder.BuildResponseAsyncandIResponseJwtBuilder.BuildAsyncreturn the refusal they meet, andIAuthorizationResponseEncoder.EncodeAsyncreturns the response the caller delivers.IAudienceKeyResolver.FindEncryptionKeyAsynctakes the security profile and the default algorithm, and returns anAudienceEncryptionKey, the key with its algorithm.
Device flow
IDeviceAuthorizationStorageof your own answers a user code lookup with aDeviceAuthorizationReferenceto the stored record, not with its device code, and reads and updates the record by that reference.- A device authorization processor of your own fills both
VerificationUriandVerificationUriComplete: the formatters send the response the processor completed.
Response formatters
A host that constructs or decorates a formatter of either web adapter passes the new arguments:
- The device authorization, pushed authorization and client management formatters take
ITenantAccessor. - The introspection formatters take
IIntrospectionResponseJwtBuilder. - The UserInfo formatters take
IFapiInteractionIdResolver, and anOidcErrorcarries theSecurityProfileit was judged under.
Shared Signals
EventDispatcher.DispatchAsyncreturns aDispatchResult, naming which streams the event could not be queued for and how many took it (Reached).PollEndpointLocatoris built from the transmitter identity it mints addresses for and theTransmitterRoutesthe endpoints were mapped at.- A host that builds the push sender or the poll endpoint handler itself hands it the transmitter's signer.
Dependency injection
DecorateKeyedunder a key with no registration wraps the last registration of the service, the one the container resolves: of two implementations a host registers, the one registered last is decorated.- An implementation of
ICompositionimplementsAddFirst,AddLast,AddBefore,AddAfter,RemoveandReplace, which no longer have default bodies.
Settings renamed or removed
In code the old names no longer compile, but a configuration file that still names a 2.x key is not refused: the key is ignored without an error, and the setting takes its default. Rename or remove each one before the first 3.0 start:
- A client's
OfflineAccessAllowedbecomesOfflineAccess:Disabled(the default),ConsentRequiredorAllowed. Left as it was, every client isDisabledand receives no refresh token.OfflineAccessAllowed: truecorresponds toAllowed, which keeps what 2.x did, since 2.x checked only the flag; setConsentRequiredinstead for a client that should ask for consent from now on. - Dynamic client registration reads
offline_accessin place ofoffline_access_allowed, as a string:"disabled", or"consent_required", which is also what a client that sends none gets. A boolean is not accepted, and a client registering itself cannot ask for"allowed". - A client's
RefreshToken.AllowReusebecomesRefreshToken.ReusePolicy:WhenSenderConstrained(the default),RotateorReuse.AllowReuse: truecorresponds toReuse, andfalsetoRotate. Left as it was, the client takesWhenSenderConstrained, which reuses the refresh tokens of a client whose access tokens are all bound to a key it proves and rotates every other client's; a client registered for CIBA push delivery, or for a response type that returns an access token from the authorization endpoint, rotates under it. - 2.x rotated the refresh tokens of every client that did not set
AllowReuse, outside FAPI 2.0, so a sender-constrained client that never set it stops rotating on 3.0. SetRotateto keep the 2.x behavior for such a client; a client held to FAPI 2.0 reuses its refresh tokens whatever its policy, as on 2.x. OidcOptions.LoginSessionExpiresInbecomesOidcOptions.AuthenticationRequestExpiresIn. Left as it was, an authorization request waits on the login, consent and account selection pages for the default time.- Under
OidcOptions.DeviceAuthorization, the user code limiter'sMaxIpFailuresPerMinutebecomesMaxAddressFailuresPerWindow,RateLimitSlidingWindowbecomesRateLimitWindow, andIpRateLimitStateExpirationbecomesRateLimitRetention. Left as they were, the limiter counts with its defaults. OidcOptions.RevocationCutoffSkewbecomesOidcOptions.ReplicaClockSkew, and it now names the largest difference between the clocks of the server's own replicas. It still widens a revocation cutoff, and it also lets an instance whose clock lags accept a token another instance issued withnbfandiatup to that far ahead;expis never extended.- Left as it was,
ReplicaClockSkewtakes its default, and where the instances drift further than that, a refresh token issued on an instance running ahead escapes a revocation. A tenant held to FAPI 2.0 is refused while the value is above the ceiling that profile allows.OidcOptions.JwtBearer.ClockSkew, the tolerance for assertions other parties sign, keeps its name and meaning. DiscoveryOptions.MtlsEndpointAliasesandDiscoveryOptions.MtlsBaseUriare removed, and the mutual TLS endpoint aliases are no longer named endpoint by endpoint. A tenant names the host they are served at inTenantDefinition.MtlsBaseUri, where a 2.xDiscovery:MtlsBaseUrivalue moves, and the aliases cover the pushed authorization request, backchannel authentication and device authorization endpoints as well, which a client authenticating with its certificate calls too.- A setup with its mutual TLS aliases on a dedicated host declares that host there. A tenant whose mutual TLS host differs from its ordinary one only by port names the ordinary endpoints on the issuer's host, whichever of the two the discovery document is fetched on.
OidcOptions.DefaultAuthorizationResponseEncryptionAlgorithmis removed. A token or response for a client that registered only the key management algorithm is encrypted with A128CBC-HS256, the default the specifications name, and no setting changes it: an ID token, a userinfo response, a JWT introspection response and an authorization response alike.OidcOptions.DefaultContentEncryptionAlgorithmremains, and applies only to the server's own tokens (access, refresh, registration access and initial access tokens); 2.x also used it for an ID token, a userinfo response or an introspection response to a client that registered no content encryption algorithm, so such a client now receives A128CBC-HS256.
Behavior that changes
Most of these need no code change, but a client or a deployment notices them. Some ask for a step of their own before the upgrade: short signing keys, stopping 2.x instances that transmit Shared Signals, the algorithms a Shared Signals receiver accepts, the redirect addresses of native clients, the CIBA expiry settings and the audience of client assertions.
Clients and registration
- A request that names a public client (
none) and also presents a credential is answeredinvalid_client. A request that authenticates the client by more than one method at once, such as anAuthorizationheader together with a client secret in the body, is answeredinvalid_requestwith a 400 before any credential is checked, at every endpoint that authenticates a client. A TLS client certificate counts as a method only for a client registered for mutual TLS authentication, so a certificate that only binds tokens keeps working. - A request carrying the
Authorizationheader more than once, counting an empty one, is refused withinvalid_requestand a 400 at every endpoint that reads the header. - Introspection answers 400 with no challenge when no authentication method finds a credential, and 401 when one is refused, so a resource server that sends its credentials only after a challenge does not retry.
- Failed client authentication at the backchannel authentication, device authorization and pushed authorization request endpoints is answered
invalid_client, with a 401 and a challenge when the client used theAuthorizationheader, as at the token endpoint. - A client authenticating with a JWT it signs, with its private key or its client secret, names the tenant's issuer as the only audience of that JWT, as a string, at every endpoint that authenticates a client, as RFC 10070 section 4 requires. A JWT naming the token endpoint, the pushed authorization request endpoint, the backchannel authentication endpoint, or the issuer inside an array is refused.
- While a client changes, the host lets it keep its form through
ClientInfo.ClientAssertionAudiences, withTokenEndpoint,PushedAuthorizationRequestEndpoint,BackChannelAuthenticationEndpointorAllowArraybesideIssuer, and lets every dynamically registered client do so throughNewClientOptions.ClientAssertionAudiences; where an endpoint is granted, the same path at the tenant's mutual TLS address is accepted too. Remove the grant once the client sends only the issuer. A client held to FAPI 2.0 cannot be granted any of them, and a server configured with one does not start. - Under the default strict audience validation (
OidcOptions.JwtBearer.StrictAudienceValidation), a JWT bearer grant assertion names the issuer or the token endpoint among its audiences, each compared exactly as written. An assertion or a software statement whose issuer is a tenant of this server is refused. - A native client registers an http redirect or post-logout redirect address only with
localhost,127.0.0.1or[::1]as the host, as OpenID Connect Dynamic Client Registration 1.0 requires. Another loopback address, such as127.0.0.2, is refused, and a client registered with one before 3.0 is refused on its next update until it replaces the address. A web client is refused other spellings oflocalhostand of a loopback address, such as a trailing dot or full-width letters, as it is refusedlocalhost. - A redirect or post-logout redirect address carrying a fragment or user information that its registered address lacks is refused, at authorization and at logout.
- Registration refuses
authorization_codewithout a response type carryingcode, andimplicitwithout one carryingtokenorid_token. An RFC 7592 update that moves a client to an authentication method its stored secret cannot serve is refused. A refused software statement is answeredunapproved_software_statementorinvalid_software_statement, and an empty scope or an empty response type is refused at registration. - Dynamic client registration and update answer an unsupported or invalid metadata value with
invalid_client_metadata, including a post-logout redirect URI, rather thaninvalid_requestorinvalid_redirect_uri. Aresponse_types,grant_types,application_type,token_endpoint_auth_methodorpost_logout_redirect_urismember sent as null is read as omitted and given its default. A token type to exchange that is not an absolute URI is refused. A registration request refused for the size of its body is answered with the status alone. - Registration refuses a content encryption algorithm without its key management algorithm, and accepts a request object encryption algorithm only when one of the tenant's published encryption keys can decrypt it.
- A registration update keeps the settings the host made on the client that registration metadata cannot carry, including relaxations, and is validated under the security profile the client is held to. An update that would change the client's subject type or its pairwise sector is refused. The maximum authentication age is read and returned as a number of seconds.
- A server without a pairwise key advertises only public subject identifiers and refuses a registration asking for pairwise identifiers. A client configured for pairwise identifiers with no key stops the server at startup, and so do two configured clients whose identifiers differ in case alone, a resource named by a relative address, and two resources under one address.
Authorization and tokens
- A client that authenticates with mutual TLS gets certificate-bound access tokens only when it is registered for them (
TlsClientCertificateBoundAccessTokens) or held to a security profile that issues no other kind. Under the default refresh token policy,WhenSenderConstrained, such a client that is not registered for them rotates its refresh tokens. - Under a security profile that demands sender-constrained tokens, a token request without a DPoP proof passes only for a client that presents its certificate and receives certificate-bound access tokens. A DPoP proof is validated on every device code and CIBA poll, so each poll carries a proof of its own.
- A refresh token revoked at the revocation endpoint, or presented again after it was rotated, revokes its whole grant, and the access tokens of the grant are refused wherever this server checks them. 2.x revoked the grant's refresh tokens on a second presentation but left its access tokens alone, and a revocation at the endpoint revoked the one token. A resource server that validates access tokens on its own accepts them until they expire.
- A token request whose named scopes all fall outside its grant is refused with
invalid_scope. - The device flow limits guessing a user code with settings 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 forMaxUserCodeAttemptsattempts, and after that like any unknown value. While the server's budget of failed verifications,MaxFailedAttemptsPerWindowwithinRateLimitWindow, is spent, every verification is refused, including a legitimate one. - An ID token is issued only to a request whose scope names
openid, and the authorization response carriesscopeonly beside an access token. - A request asking to select an account, to give consent, to log in or to create an account is answered once: the end user is sent to the page, and the request proceeds when they come back with an answer given there. A request asking to select an account while nobody is signed in goes to the account selection page.
- A request whose claims parameter requires an authentication level of the ID token selects only sessions at an accepted level; one left with no such session sends the end user to the login page, and one forbidding interaction is refused with the unmet authentication requirements error.
- Once a flow begun by a pushed authorization request issues a code or a token, the address the client pushed and every page address the flow was given are refused, and the address a request comes back with from a page is spent however the page answered it.
- Where pushed authorization requests are required, a request to the authorization endpoint without one is refused with
invalid_requestrather thaninvalid_request_object, and a pushed request carryingrequest_uriis refused withinvalid_requestrather thaninvalid_request_uri. - A request object sent beside a
client_idcarries the sameclient_idclaim, at the authorization endpoint and at the pushed authorization request endpoint, and arequest_uriwithout aclient_idis answeredinvalid_request. A request object that includesrequestorrequest_uriis refused withinvalid_request_object. Under strict request object processing, a request object that names no scope is refused withinvalid_request_object, orinvalid_requestat the backchannel authentication endpoint, instead of being given the client's default scope. - Every validation of a JWT states the token types it accepts. An ID token carrying the type that versions 2.2 and 2.3 gave their ID tokens is refused as a hint at the authorization endpoint, including a silent renewal, at logout and in a CIBA request.
- In token exchange, a token without a type is refused under the access token type, and a refresh, registration or initial access token under the generic JWT type. A software statement or a login hint token typed as another kind of token this server names is refused, and so is a typed JWT bearer assertion when the deployment lists no accepted types.
- An access token carries the email address and its verification from the sign-in session only when the client was granted the email claim, by a scope that includes it or by naming it for the user information endpoint. For any other access token, a resource server gets the address from the user information endpoint or from the client.
- The userinfo endpoint answers
invalid_requestwhen the token is sent more than one way or a scheme carries no token. It answers an access token granted without theopenidscope with 403insufficient_scope, which names the scope it needs, for every client and not only under a FAPI profile. It omits claims that have no value. - The error of a refused request is put on the
WWW-Authenticatechallenge of the scheme the client used, and on both challenges when the scheme cannot be told. A host that formats its own resource server errors through the library's challenge-building helpers gets an error that records no scheme on both challenges. - A token or response the server cannot sign or encrypt for a client is answered as a protocol error instead of failing the request:
unauthorized_clientat the token and authorization endpoints,invalid_tokenat UserInfo. - At JWT introspection, a client whose registration the server cannot serve, such as a signing algorithm outside its profile or an encryption it registered with no key to encrypt to, is answered 400; when no signing key of the tenant produces the JWT, a caller that also accepts JSON gets the JSON response, and any other caller 406. A logout token or a CIBA push result is not sent. The refusal is logged once, as an error when the tenant has no key for the algorithm and as a warning when the cause is in the client's registration.
- A token for a resource or a client is encrypted to the first key of its set the server can encrypt to. A resource with no usable key is refused with
invalid_targetat the token endpoint and in the implicit flow, and an ID token or JARM response that cannot be encrypted is answeredunauthorized_clienton the redirect. - The introspection and revocation endpoints limit how many requests one client may make, counted on each instance, and answer a client that has spent its budget with status 429 and how long to wait. The limit is
OidcOptions.CallerRateLimit, on by default and far above what a working deployment reaches; a limit that would turn every client away stops the server at startup. Before the upgrade, check the limit against any resource server that introspects every request without caching the answer.
Security profiles
- FAPI 2.0 forbids RSA1_5 key management and requires an https
jwks_uri. It refuses the response type that returns nothing and the password grant, and a client configured for either stops the server at startup. - A tenant held to a FAPI profile lists in its discovery document only what its profile admits, and a FAPI profile refuses the CIBA push mode.
- A client's ID token and authorization response signing algorithms are judged against its security profile and the tenant's keys only where the client can be issued that token, so a machine client or resource server under FAPI is no longer refused for defaults it never uses.
- A tenant held to a FAPI profile signs its security event tokens with PS256 or ES256. A Shared Signals receiver built with this library's defaults accepts RS256 only, so a receiver verifying the events of such a tenant lists PS256 or ES256 among its accepted algorithms,
SecurityEventsOptions.AllowedSigningAlgorithms. With Shared Signals added, a tenant whose signing keys perform none of the algorithms its events may be signed with stops the server at startup.
Keys and encryption
- A tenant whose custodian encryption key names a key management algorithm the host has not registered stops the server at startup.
- A signing key in
TenantDefinition.SigningKeyssmaller than RFC 7518 allows stops the server at startup: an RSA key shorter than its algorithm requires, or a symmetric key shorter than the hash of its algorithm. The refusal names the key id, its size and the size required. A tenant read from a tenant store with such a key is left out instead, and the others are served. - Remove or replace such keys before upgrading; a short key cannot stay behind to verify old tokens.
- A key of that size from another source, a custodian or a key provider of the host, is passed over when a signing key is chosen; where no other key signs with the algorithm, the token is not issued, and the error or the log names the key and its size.
- A key whose declared algorithm its material cannot perform, such as an elliptic-curve key declaring
PS256, is not chosen for that algorithm. A key that declares a key management algorithm encrypts and decrypts only under that algorithm. - A token whose compact parts carry base64 padding, whitespace or line breaks is refused. JSON Web Keys are read with the library's own JSON options, whatever options the host serializes under, so member names match exactly:
KIDis not read askid. - 2.x encrypted an ID token, a userinfo response or an introspection response for any client that published an encryption key. 3.0 encrypts one only for a client that registered its key management algorithm, and only under that algorithm, with no fallback to another; a client whose keys cannot serve it is refused.
- A failure of a key custodian is answered by the library, outside the host's own exception handling. A custodian that does not serve the key management algorithm of a tenant's encryption key stops the server at startup.
- A minted key starts signing once
OidcOptions.KeyRolloverPropagationhas passed, and the server sets the key ring's ownKeyRolloverPropagationfrom that value, overriding one the host set. A minted key ring with no store to keep it, and a Vault or OpenBao address that is not an absolute URI, stop the server. - A symmetric key for AES Key Wrap or AES-GCM key wrapping (
A128KW,A128GCMKWand their siblings) is chosen only at the exact length its algorithm needs. A key whose bytes a custodian holds is chosen as before. - A key ring refuses a rotation period that is not positive and a negative time to keep a retired key, when it is registered. A key ring kept in memory also refuses a time to keep a retired key shorter than the announcement of a new key, when the host starts.
- A key set member of an unknown type, malformed or out of the supported ranges, is left out of the set rather than failing it, including a client's key set at registration; a single key still fails. A verification key the platform cannot import, or one without its public half, answers an invalid signature.
- A DPoP proof whose
jwkheader holds private material is refused asinvalid_dpop_proof. - The discovery document lists for request object encryption only the algorithms each tenant's own published encryption keys can open, and omits both request object encryption lists when the tenant has none. A request object, an encrypted private key JWT assertion or a backchannel login hint token is decrypted only with those keys.
- Symmetric encryption of responses to a client uses a key derived from the client secret, as OpenID Connect Core describes, and only for a client whose secret the server keeps in readable form. The discovery lists for encrypting authorization and introspection responses no longer name PBES2.
Sessions and logout
- The clients that signed in to a session are recorded by the server, one record per client, and kept for
OidcOptions.SessionClientsRetentionafter the session's last authorization of a client. Set it to at least the lifetime of the host's authentication cookie: a session that ends after its record expired tells none of the clients recorded before. With a session service of your own that carries 2.x sessions over, the first logout of such a session notifies only the clients that signed in to it on 3.0. - An authorization leaves the session cookie as it is. 2.x wrote the cookie again when a client first signed in to the session; on 3.0 only the sliding expiration of the host's authentication cookie extends a session with activity.
- The answer to the logout question carries back a value the server issues for the session, so a logout page of your own puts that value into its form. An ID token hint naming another end user or session asks the end user to confirm, so a host without a confirmation page adds one.
- A logout request whose ID token hint names a client nobody registered, and which names no client, is refused as an unauthorized client.
- The cookie session adapter refuses to sign in a session without a subject or a session identifier. Signing in again as the person the cookie already names continues that session under its identifier.
- A request outside every tenant has no session, and signing in there is refused.
- An additional claim of the session is left out of a token that carries a claim of the same name itself or reserves it as a standard claim, so it no longer overwrites
iss,expor the grant id of an access or refresh token. - An additional claim of the cookie session holding a date without a time is kept as that date, and one holding an instant is kept with its offset. A date and time value with no offset of its own, including a UTC one, is kept as the text it was written as.
Backchannel authentication (CIBA)
- A backchannel authentication request is read after the client authenticates, so a caller failing authentication is answered
invalid_clientbefore its request object is read. A signed request is signed with an asymmetric algorithm by the authenticated client and carriesaudnaming the issuer,exp,iat,nbfandjti; a refused one is answeredinvalid_requestrather thaninvalid_request_object. - A client registered without client authentication is refused backchannel authentication, and a configured one stops the server at startup.
- A request from a client the flow is not open to is refused before validation, so telemetry counting refusals of the validation stage no longer sees it.
BackChannelAuthentication.MaximumExpirymust be positive and within the ceiling the server sets, andDefaultExpirypositive and no longer than it, or the server does not start. Anauth_req_idpolled after its expiry is answeredexpired_token, whether the request is pending or approved, and an approved request no longer issues tokens after it. Completing or denying a request after its expiry throws. A host store keeps each record for the full time it is given.
Hosting
- On an MVC host, a request for an OIDC endpoint that reaches no tenant is answered 404 with no body, as on the Minimal API host.
- The endpoint paths and an optional prefix are set the same way on both hosts, and a configuration section keyed as in 2.4 still sets the paths of an MVC host. A host whose own controllers carry route tokens calls the same configuration method, with an empty section if it sets no value. A route token ends at its own closing bracket, so a route with more after a token, or with two tokens, answers on the whole path its template spells out.
- The endpoints of an MVC host appear in the host's API description, and so in an OpenAPI document built from it.
- A host that adds both web adapters, MVC and Minimal API, does not start.
- A request without a host is answered 400
invalid_requeston both web adapters. - A tenant whose issuer lies under the path of another tenant's issuer on the same host stops the server, and so does a key that two tenants declare: one key serves one tenant.
- A server whose settings declare a tenant at an issuer the license does not name, or more tenants than the license's issuer limit allows, does not start. A client beyond the license's client limit by more than its margin is refused when a token would be issued to it.
- With the built-in storage over a distributed cache, a single-use decision, such as spending a rotated refresh token, 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.
- A parameter that takes one value and is repeated, a duration given as a negative number of seconds, and a locale that names no language are refused as an invalid request.
Shared Signals
- A queued event is signed when it is delivered, so it waits in the event outbox unsigned. A host whose own outbox or tooling read the signed token of a queued event has it signed by the transmitter.
- Each tenant's queues are kept under the tenant, so 3.0 does not deliver an event a 2.4 transmitter left queued, and a 2.4 transmitter does not deliver an event 3.0 queued: 2.4 and 3.0 instances do not share an event outbox.
- A host running a transmitter lets the 2.4 queues drain and stops every 2.4 instance before the first 3.0 one starts, and rolls back below 3.0 only once the 3.0 queues are empty.
The pairwise hash
The hash that derives a tenant's pairwise key is the one PairwiseSubjectSettings.HashAlgorithm names: SHA256 (the default), SHA384 or SHA512. It is a string in code too, so HashAlgorithm = "SHA384" replaces HashAlgorithmName.SHA384. Any other name, including SHA1, stops the server at startup, and the error names the tenant and the setting.
A server that has to choose another hash, including one configured with SHA1, derives another key: every pairwise identifier it issued changes, and its relying parties meet their users as new ones. Tell their owners before the upgrade.
What the first 3.0 start does not carry over
3.0 keeps everything it stores under the tenant. The server's own storage key factory (EntityStorageKeyFactory) writes an entry as tenant:<tenant id>: followed by the entry's own key (with ~<generation> after the id for a tenant that has a generation), and the replay cache puts its own prefix in front of that; a key factory of your own (IEntityStorageKeyFactory) names the entries in the tenant's space as it chooses. 3.0 reads nothing 2.x stored, so on the first start:
- Signed-in users sign in again. With the server's own session service (
AuthenticationSchemeAdapter), the authentication cookie names its tenant, and a 2.x session reads as no session; a session service of your own decides for itself. - The check-session cookie carries the tenant's id after its configured name,
OidcOptions.CheckSessionCookie.Name: with the default name it isAbblix.SessionId.<tenant id>, and a check-session page or proxy rule of your own that reads the cookie by its 2.x name reads that form. - Flows in progress end, and their clients start them again: authorization codes, pushed and interaction requests, back-channel authentication requests, device codes, and logout confirmations.
- Refresh tokens issued by 2.x are refused with
invalid_grantand cannot be carried over, so a client renews by signing the user in again. A client that refreshes in the background with no user present fails until its user signs in, so warn its owners of the date. - Shared Signals events a 2.4 transmitter left queued are not delivered.
- Revocations recorded on 2.x are not carried over: the records of revoked and rotated tokens, and the revocation cutoffs.
- Shared Signals streams that receivers created through the management API are gone, and the receivers create them again. Streams a tenant declares in its configuration are written again on their own.
- Signing keys the 2.x server minted are replaced by new ones, unless you keep them as the next section describes. Without that step, every relying party meets tokens signed by a key its cached key set does not hold, and the tokens signed before the upgrade stop verifying.
Users and consents your host keeps itself are untouched. Clients in a client store of your own are kept too, but a record 2.x wrote needs these changes before 3.0 serves it correctly. The registration access token's identifier, which 2.x kept apart from the client, is copied into the record, or the client cannot be managed with its registration access token. A stored OfflineAccessAllowed is converted to OfflineAccess, or the client comes back Disabled and gets no refresh token. A stored RefreshToken.AllowReuse is converted to ReusePolicy, or the client takes the default policy whatever the old value was. Moving a store from version 2 describes each of them. The default client store keeps dynamically registered clients in process memory, so those never outlived a restart in 2.x either.
Keeping the signing keys the server minted
This applies to a server that mints its own keys (UseKeysInProcess). Keys from the settings, or keys a custodian holds, are the same keys after the upgrade, because the tenant declares them.
A 2.x key ring keeps each entry under its bare id. 3.0 keeps a partition of the ring for each tenant and stores an entry as <partition>.<id>, where the partition is the tenant id. A tenant moved from 2.x is declared in the settings and has no generation, so its partition is just its id. The sealed key inside an entry does not depend on the entry's name, so a copy with the same content opens under the new one.
Before the first 3.0 instance starts:
- Declare the tenant with the same issuer the 2.x server used. Tokens signed before the move fail on their
issotherwise, whatever key verifies them. - Copy every entry whose id has no dot,
<id>, to<tenant id>.<id>, unchanged, and create only targets that do not exist yet.- OpenBao or Vault KV version 2, with
<mount>and<path>fromVaultKeyValueOptions.MountandVaultKeyValueOptions.Path: read<mount>/data/<path>/<id>and write its fieldsjweandcreatedAtto<mount>/data/<path>/<tenant id>.<id>withcas=0. - Azure Blob Storage: copy the blob
<id>to<tenant id>.<id>in the same container,AzureBlobKeyRingOptions.Container, if it is not there yet.
- OpenBao or Vault KV version 2, with
A 2.x instance that is still running can mint the next period's key, so run the copy again until the last 2.x instance has stopped. 3.0 never reads the original entries, those whose ids have no dot, and never deletes them; delete them once the upgrade is settled. Back up the whole ring before the first 3.0 start: it is what a rollback to 2.x restores.
What you keep, and what you do not:
- The published key set stays the same, and every ID token and access token signed before the upgrade keeps verifying.
- An access token revoked on 2.x is accepted again at introspection and userinfo until it expires, because the revocation record is not carried over. To narrow that window, shorten the access token lifetime on 2.x ahead of the upgrade, so the tokens alive at the cut-over expire sooner. Skipping the copy closes the window too, but then every token signed before the upgrade stops verifying.
- Refresh tokens issued by 2.x are refused either way.
AdoptExistingKeys(partition, keys) is a different step. It takes keys that a host signed with outside the ring, such as certificates or static keys from its settings, into a tenant's partition when the host switches to minted keys. A host whose keys the 2.x ring minted needs only the copy above.