Authentication

QvaSoft Gateway supports multiple authentication providers simultaneously. Each provider is identified by a unique Key that routes reference.

Provider Types

Type	Use Case
jwt (HMAC)	Tokens signed with a symmetric secret key
jwt (Certificate)	Tokens signed with an RSA certificate (file or store)
jwt (JWKS)	Tokens verified with remote public keys
oidc	OpenID Connect / IdentityServer integration

Configuration

Providers are configured in appsettings.json under AppSetting.AuthenticationProviders:

{
  "AppSetting": {
    "AuthenticationProviders": [
      { "Key": "JWT", "Type": "jwt", ... },
      { "Key": "IdentityServer", "Type": "oidc", ... }
    ]
  }
}

The first provider in the list becomes the default authentication scheme.

JWT with Symmetric Key (HMAC)

The simplest setup -- tokens are signed and verified with a shared secret:

{
  "Key": "JWT",
  "Type": "jwt",
  "SecretKey": "your-secret-key-at-least-32-chars-long",
  "Issuer": "https://your-app.com/",
  "Audience": "api://default",
  "ValidateLifetime": true
}

warning

Never store SecretKey in plain text in production. Use environment variables:

AppSetting__AuthenticationProviders__0__SecretKey=your-production-secret

JWT with Certificate File (RSA)

For asymmetric signing with a .pfx certificate:

{
  "Key": "JWT_Cert_File",
  "Type": "jwt",
  "CertificatePath": "certs/signing-cert.pfx",
  "CertificatePassword": "cert-password",
  "Issuer": "https://issuer.example.com/",
  "Audience": "api://default",
  "ValidateLifetime": true
}

The certificate must contain the public key for validation. The private key is needed only by the service that issues tokens.

JWT with Certificate Store

Load the certificate from the Windows certificate store by thumbprint:

{
  "Key": "JWT_Cert_Store",
  "Type": "jwt",
  "CertificateThumbprint": "ABCDEF1234567890ABCDEF1234567890ABCDEF12",
  "Issuer": "https://issuer.example.com/",
  "Audience": "api://default",
  "ValidateLifetime": true
}

note

The application must have permission to access the certificate in the LocalMachine\My store.

JWT with JWKS (Remote Public Keys)

Verify tokens using public keys published at a JWKS endpoint. Ideal for external identity providers:

{
  "Key": "JWT_JWKS",
  "Type": "jwt",
  "JwksUri": "https://identity.example.com/.well-known/jwks.json",
  "Issuer": "https://identity.example.com/",
  "Audience": "api://default",
  "ValidateLifetime": true
}

JWKS keys are cached for 1 hour to reduce network calls.

OpenID Connect (OIDC)

Full integration with OIDC providers like IdentityServer, Auth0, or Keycloak:

{
  "Key": "IdentityServer",
  "Type": "oidc",
  "Authority": "https://identity.example.com/",
  "ClientId": "gateway-client",
  "ClientSecret": "client-secret",
  "Issuer": "https://identity.example.com/",
  "Audience": "api",
  "EnableCaching": true,
  "CacheDuration": 60,
  "ServerCertificateValidation": true,
  "ValidateLifetime": true
}

Applying Authentication to Routes

Reference the provider Key in your route configuration:

{
  "UpstreamPathTemplate": "/api/secure/{everything}",
  "DownstreamPathTemplate": "/api/{everything}",
  "AuthenticationOptions": {
    "AuthenticationProviderKeys": ["JWT"],
    "AllowedScopes": []
  }
}

Allow Anonymous Access

{
  "AuthenticationOptions": {
    "AllowAnonymous": true
  }
}

Multiple Providers per Route

A route can accept tokens from multiple providers:

{
  "AuthenticationOptions": {
    "AuthenticationProviderKeys": ["JWT", "JWT_JWKS"]
  }
}

Route Claims Requirement

Require specific claims for access:

{
  "RouteClaimsRequirement": {
    "scope": "api.read",
    "UserType": "registered"
  }
}

All specified claims must be present and match for the request to proceed.

Common Fields Reference

Field	Description
Key	Unique identifier for the provider
Type	jwt or oidc
SecretKey	HMAC signing key
Issuer	Expected token issuer (iss claim)
Audience	Expected token audience (aud claim)
ValidateLifetime	Validate token expiration
Expiration	Token lifetime in seconds (for token generation)
CertificatePath	Path to .pfx certificate file
CertificatePassword	Certificate file password
CertificateThumbprint	Certificate thumbprint (store lookup)
JwksUri	URL to JWKS endpoint
Authority	OIDC provider base URL
ClientId	OIDC client identifier
ClientSecret	OIDC client secret