Gatekeeper

An independent authentication and authorization microservice implementing passkey-only authentication (WebAuthn/FIDO2) and fine-grained role-based access control with record-level permissions.

NOTE: There seems to be a mistake here. ABAC was not supposed to be part of this technology but was implemented anyway. We will need to remove this.

Overview

Gatekeeper provides:

• Passwordless authentication - WebAuthn/FIDO2 passkeys only, no passwords
• Role-based access control (RBAC) - Hierarchical roles with permission inheritance
• Record-level permissions - Fine-grained access to specific resources
• JWT sessions - Stateless session management with refresh tokens
• Framework-agnostic - REST API for integration with any system

Projects

Getting Started

Prerequisites

• .NET 9.0 SDK
• SQLite (default) or PostgreSQL

Run the API

cd Gatekeeper/Gatekeeper.Api
dotnet run

The API starts on http://localhost:5002.

Database Setup

The database is automatically created on first run. To reset:

rm gatekeeper.db
dotnet run

API Endpoints

Authentication

Authorization

Admin (requires admin role)

Usage Examples

Register a Passkey

# 1. Begin registration
curl -X POST http://localhost:5002/auth/register/begin \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "displayName": "John Doe"}'

# Response contains WebAuthn options for the browser
# 2. Browser calls navigator.credentials.create() with options
# 3. Complete registration with authenticator response
curl -X POST http://localhost:5002/auth/register/complete \
  -H "Content-Type: application/json" \
  -d '{"challengeId": "...", "response": {...}}'

Authenticate

# 1. Begin login
curl -X POST http://localhost:5002/auth/login/begin \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# 2. Browser calls navigator.credentials.get() with options
# 3. Complete login
curl -X POST http://localhost:5002/auth/login/complete \
  -H "Content-Type: application/json" \
  -d '{"challengeId": "...", "response": {...}}'

# Response: {"token": "eyJ...", "expiresAt": "..."}

Check Permission

curl "http://localhost:5002/authz/check?resource=patient&action=read&resourceId=123" \
  -H "Authorization: Bearer eyJ..."

# Response: {"allowed": true, "reason": "Role: physician"}

Database Schema

gk_user ──┬── gk_credential (passkeys)
          ├── gk_session (active sessions)
          ├── gk_user_role ── gk_role ── gk_role_permission
          ├── gk_user_permission (direct grants)
          └── gk_resource_grant (record-level access)
                                    │
                                    ▼
                              gk_permission

Key Tables

Permission Model

RBAC

admin (role)
  └── user:manage (permission)
  └── role:manage (permission)

physician (role)
  └── patient:read (permission)
  └── patient:write (permission)

Record-Level

User "dr.smith" has "patient:read" on Patient "patient-123"

Configuration

Environment variables:

Testing

# Run all Gatekeeper tests
dotnet test --filter "FullyQualifiedName~Gatekeeper"

# Specific test class
dotnet test --filter "FullyQualifiedName~AuthorizationTests"

Design Principles

Following the repository's coding rules:

• No exceptions - Returns Result<T, GatekeeperError> types
• No classes - Uses records and static methods
• No interfaces - Uses Func<T> for abstractions
• Integration tests - Real database, no mocks
• DataProvider - All SQL via generated extension methods

References

WebAuthn/FIDO2

• W3C WebAuthn Specification
• fido2-net-lib
• SimpleWebAuthn

Access Control

• NocoBase RBAC Guide
• Permify Fine-Grained Access

License

See repository root for license information.