Authentication Flow
DevGuard uses a multi-layered authentication system with Ory Kratos for session management, Personal Access Tokens (PAT) for API access, and Casbin for role-based authorization.
Authentication Methods
Cookie Authentication (Web UI)
Users authenticate via Ory Kratos, which issues an ory_kratos_session cookie. Sessions include scan and manage scopes by default.
Personal Access Token (CLI/API)
For programmatic access DevGuard supports two PAT modes. Both grant the same API access; they differ in authentication mechanism.
Asymmetric (ECDSA request signing) — the private key never leaves the client. Every request is individually signed; signatures cover the HTTP method and a SHA-256 digest of the full request body, preventing replay and tampering.
Required headers:
X-Fingerprint: <sha256-of-public-key>
Signature-Input: sig77=(...)
Signature: :base64-signature:
Content-Digest: sha-256=:base64-hash:
Create an asymmetric token:
Symmetric Bearer token (v1.6.0+) — an opaque dvg_-prefixed secret. DevGuard stores only the SHA-256 hash; the cleartext is shown once at creation.
Required header:
Authorization: Bearer dvg_<token>
Create a symmetric token (omit pubKey):
The session middleware tries cookie auth first, then Bearer token, then request signature verification. On success it creates a session scoped to the token's scan/manage scopes.
Authorization (RBAC)
DevGuard uses Casbin for hierarchical role-based access control scoped to organizations (domains).
Role Hierarchy
Roles exist at three levels:
- Organization:
owner,admin,member - Project:
owner,admin,member - Asset:
owner,admin,member
Roles cascade down: organization admins can access all projects, project admins can access all assets within that project.
Permission Model
Permissions follow the pattern: subject → domain → object → action
Example:
Middleware Enforcement
Access control is enforced at each resource level:
Public resources (is_public=true) allow read-only access without authentication.
External Integrations
OAuth2 (GitLab/GitHub)
Users can authenticate via OAuth2 providers. Tokens are stored encrypted and refreshed automatically.
Endpoints:
- Login:
GET /api/v1/session/oauth2/gitlab/{integration}/ - Callback:
GET /api/v1/session/oauth2/gitlab/callback/{integration}/
External Entity Provider RBAC
For projects/assets linked to GitLab/GitHub repositories, DevGuard delegates permission checks to the external provider's API to verify repository access.