Security Settings

Security settings control refresh-token lifetime, session renewal, refresh replay behavior, and signing-key rotation. Access-token lifetime remains a startup option because it changes JWT generation directly.

Choose an administration path#

• Dashboard: open Auth Server > Security for operator changes.
• Trusted backend: inject SqlOSSettingsService for deployment/setup automation.
• Dashboard HTTP API: use /sqlos/admin/auth/api/settings/security only with an authorized dashboard operator session. It is an implementation API for the bundled dashboard, not an unauthenticated management endpoint.

Current defaults#

Idle timeout is enforced on refresh, not on every already-issued access token. Session-aware access-token validation checks session existence, revocation, and absolute expiry; the JWT's own exp remains the access token's time boundary.

Update through a trusted backend#

SqlOSSettingsService is scoped and operator-trusted. Authorize the caller before exposing any wrapper endpoint:

var updated = await settingsService.UpdateSecuritySettingsAsync(
    new SqlOSUpdateSecuritySettingsRequest(
        RefreshTokenLifetimeMinutes: 43200,
        SessionIdleTimeoutMinutes: 10080,
        SessionAbsoluteLifetimeMinutes: 43200,
        SigningKeyRotationIntervalDays: 90,
        SigningKeyGraceWindowDays: 7,
        SigningKeyRetiredCleanupDays: 30,
        RefreshTokenGraceWindowSeconds: 30),
    ct);

All minute/day values must be positive. Signing-key validation grace must be shorter than the rotation interval. Refresh grace can be 0 to disable it, but cannot exceed the configured access-token lifetime.

Dashboard API payload#

The following assumes the operator cookie jar created by Authenticate operator API calls; a bare curl request is unauthorized.

curl http://localhost:5062/sqlos/admin/auth/api/settings/security \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR"
 
curl -X PUT http://localhost:5062/sqlos/admin/auth/api/settings/security \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshTokenLifetimeMinutes": 43200,
    "sessionIdleTimeoutMinutes": 10080,
    "sessionAbsoluteLifetimeMinutes": 43200,
    "signingKeyRotationIntervalDays": 90,
    "signingKeyGraceWindowDays": 7,
    "signingKeyRetiredCleanupDays": 30,
    "refreshTokenGraceWindowSeconds": 30
  }'

In password dashboard mode, the session cookie is created by POST /sqlos/dashboard-auth/login; in callback mode, your host authorization callback establishes the trusted operator boundary. Prefer the dashboard UI or injected service over scripting a browser cookie when durable automation is required.

Access-token lifetime#

Configure access-token lifetime at startup. The default is 10 minutes:

builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.AccessTokenLifetime = TimeSpan.FromMinutes(15);
});

Keep access tokens short when resource servers use JWKS-only validation because those services cannot see immediate SqlOS session revocation. See Token Validation.

Read resolved settings#

var settings = await settingsService.GetResolvedSecuritySettingsAsync(ct);
 
// settings.RefreshTokenLifetime    -> TimeSpan
// settings.SessionIdleTimeout      -> TimeSpan
// settings.SessionAbsoluteLifetime -> TimeSpan
// settings.RefreshTokenGraceWindow -> TimeSpan

Signing-key timing is available separately through GetKeyRotationSettingsAsync. Review Production Readiness before changing key retention or session policy in a rolling deployment.