Authentication, Tenancy, and Access Control

Last validated: 2026-05-11

Auth Modes

K3 HTTP accepts multiple auth modes through middleware:

1. Bearer JWT (Authorization: Bearer <token>)
2. SigV4 header auth (Authorization: AWS4-HMAC-SHA256 ...)
3. SigV4 query auth (X-Amz-* query params)
4. SigV2 query auth (AWSAccessKeyId, Signature, Expires)
5. K3 presigned token query auth (X-K3-Token, X-K3-Expires, X-K3-Org)

When K3_AUTH_ENABLED=false, auth middleware runs in pass-through mode and tenant headers must be supplied by the caller.

Tenant Context Headers

After auth, K3 normalizes tenant identity to headers consumed by service handlers:

• x-organization-id
• x-organization-name
• x-organization-status

These headers drive bucket and service-level authorization behavior.

Suspended Organization Behavior

When org status is suspended, API auth layers can reject requests through org-status permission gating.

Bucket Access Control

Buckets expose access modes:

• PRIVATE
• PUBLIC
• CUSTOM

Custom mode uses S3-style bucket policy statements. Policy evaluation supports action/resource style matching at handler-level authorization checks.

Supported policy management APIs:

• Set bucket policy
• Get bucket policy
• Delete bucket policy

CORS Controls

K3 supports bucket-level CORS configuration APIs:

• Put bucket CORS
• Get bucket CORS
• Delete bucket CORS

Runtime layers include global CORS handling plus per-bucket CORS middleware.

Service Discovery and Identity Dependencies

SigV4 flow relies on service-account secret resolution through Keycloak admin integration when configured.

Key environment requirements for full SigV4 support include:

• KEYCLOAK_BASE_URL
• KEYCLOAK_ACCESS_CLIENT_ID
• KEYCLOAK_ACCESS_CLIENT_SECRET

If not configured, bearer/dev auth can still function while SigV4 flows may fail.

Public and Probe Endpoints

These endpoints are intentionally public/auth-bypassed for health and observability:

• /health
• /healthz
• /ready
• /readyz
• /metrics

gRPC Auth Notes

gRPC server auth layer enforces bearer token validation (when auth enabled), injects tenant metadata, and can apply UMA scope checks for non-bucket-scoped operations.

Practical Caller Guidance

For backend service-to-service callers

Use bearer JWT with org context managed by auth layer.

For S3 ecosystem callers (AWS SDK/CLI style)

Use SigV4 auth and ensure service-account secret resolution path is configured.

For local development

Disable auth or use dev-compatible headers with known org values.

Common Failure Patterns

• Missing org headers in dev mode when auth is disabled.
• SigV4 key is unknown or cannot be resolved through configured identity backend.
• Token exchange success but org is suspended.
• Caller assumes endpoint is public while ACL/auth layer still requires auth for that path.