AddTraxJwtDispatcher
Package Trax.Api.Auth.JwtNamespace Trax.Api.Auth.JwtSource JwtAuthServiceCollectionExtensions.cs, JwtDispatcherBuilder.cs, JwtDispatcherRuntime.cs, TraxJwtRejectAuthenticationHandler.cs
NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.
Extension method on IServiceCollection, declared on JwtAuthServiceCollectionExtensions, that registers a policy authentication scheme. It reads the iss claim of the request's Bearer token and forwards authentication to the JWT scheme, registered with AddTraxJwtAuth, that the issuer maps to.
Signature
public static AuthenticationBuilder AddTraxJwtDispatcher(
this IServiceCollection services,
Action<JwtDispatcherBuilder> configure);public sealed class JwtDispatcherBuilder
{
public JwtDispatcherBuilder MapIssuer(string issuer, string schemeName);
public JwtDispatcherBuilder WithSchemeName(string schemeName);
public JwtDispatcherBuilder FallbackToScheme(string schemeName);
}
public sealed class JwtDispatcherRuntime
{
public IReadOnlyDictionary<string, string> IssuerToScheme { get; }
public string? ResolveSchemeForToken(string token);
public ITraxPrincipalResolver<JwtTokenInput>? ResolvePrincipalResolver(string schemeName, IServiceProvider services);
}Parameters
| Parameter | Type | Description |
|---|---|---|
configure | Action<JwtDispatcherBuilder> | Maps issuers to schemes. At least one MapIssuer is required. |
Members
JwtDispatcherBuilder, passed to configure:
| Member | Description |
|---|---|
MapIssuer(issuer, schemeName) | Routes tokens whose iss is issuer to schemeName. Mapping an issuer twice throws InvalidOperationException. |
WithSchemeName(schemeName) | The dispatcher's own scheme name. Defaults to JwtDefaults.DispatcherSchemeName. |
FallbackToScheme(schemeName) | Routes tokens with an unmapped issuer, and requests with no readable token, to schemeName instead of the reject scheme. That scheme runs its own issuer validation. |
JwtDispatcherRuntime, a singleton the dispatcher registers so the GraphQL socket path can route the same way:
| Member | Description |
|---|---|
IssuerToScheme | The issuer-to-scheme table. |
ResolveSchemeForToken(token) | The scheme the token's iss maps to, else the fallback scheme, else null (reject). |
ResolvePrincipalResolver(schemeName, services) | The resolver registered for schemeName, or null. Pass a scoped provider so a scoped resolver resolves. |
Returns
The AuthenticationBuilder from services.AddAuthentication().
Behavior
On each request the dispatcher:
- Reads the
Authorizationheader. No Bearer token: forward to the fallback. - Reads the token's
isswithout validating the signature. Unreadable: forward to the fallback. - Looks the issuer up, compared ordinally: case- and trailing-slash-sensitive. A hit forwards to the mapped scheme, a miss to the fallback.
The fallback is the FallbackToScheme scheme, or the reject scheme JwtDefaults.RejectSchemeName, which fails every request with No JWT scheme matched the token's issuer. and answers a challenge with 401. The dispatcher never authenticates a token itself; the scheme it forwards to runs the full JwtBearer validation.
| Request | Result |
|---|---|
No Bearer token, or one whose iss cannot be read | The fallback scheme's result: 401 from the reject scheme unless FallbackToScheme is set. |
iss not mapped | As above. |
iss mapped, validation succeeds | Success from the mapped scheme. |
iss mapped, validation fails | The mapped scheme's failure, 401. |
AddTraxJwtDispatcher throws InvalidOperationException when no issuer is mapped, or when a scheme with the dispatcher's name is already registered (call WithSchemeName).
It registers the policy {dispatcher scheme}-JwtPolicy (TraxJwtDispatcher-JwtPolicy by default), satisfied by a caller any mapped scheme, or the fallback scheme, authenticated, and adds the dispatcher scheme to TraxAuthClaimTypes.TraxAuthPolicy.
Subscriptions
With a dispatcher registered, JWT socket connections go to TraxJwtDispatcherSocketInterceptor. It reads the token from connection_init, routes it through JwtDispatcherRuntime, and authenticates it with the mapped scheme's own handler, events included. An unmapped issuer is rejected unless FallbackToScheme is set. The connection closes when its token expires. See Subscriptions.
Example
var internalKey = Encoding.UTF8.GetBytes(builder.Configuration["Jwt:InternalKey"]!);
services.AddTraxJwtAuth("customers", jwt =>
jwt.UseAuthority("https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC", "mobile-client"));
services.AddTraxJwtAuth("internal", jwt =>
jwt.UseSymmetricKey("billing-service", "trax-api", internalKey));
services.AddTraxJwtDispatcher(d =>
{
d.MapIssuer("https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC", "customers");
d.MapIssuer("billing-service", "internal");
});
services.AddTraxGraphQL(graphql =>
graphql.RequireAuthorization(JwtDefaults.DispatcherSchemeName + "-JwtPolicy"));