Skip to content

Identity Model

This document defines the identity and authorization model for the Oryvin ecosystem.

Oryvin is composed of multiple cooperating services, including WEIC, Orchestrator, DropBoxMini, and supporting infrastructure services. These systems require a consistent identity model so that users, service accounts, and automated workflows can authenticate and operate within clearly defined authorization boundaries.

The identity model is centered on centralized authentication, token-based access, and role-based authorization.

Purpose

The identity model exists to support several goals:

  • provide a single authentication model across the Oryvin platform
  • separate authentication from application-specific business logic
  • support both human users and automated service identities
  • enforce role-based authorization consistently
  • create a secure foundation for API access, workflow execution, artifact delivery, and governance

This model aligns with the broader Oryvin goal of a controlled and traceable operational environment.

Identity principles

The identity model follows several principles.

Centralized authentication

Authentication should be handled by a shared identity provider rather than implemented independently by each service.

Token-based access

Authenticated clients should use tokens to access services rather than session-specific local login models.

Role-based authorization

Services should make authorization decisions based on roles, not on hard-coded user logic.

Support for human and machine identities

The platform must support both interactive users and non-interactive service accounts.

Traceable access

Important operations should be attributable to an authenticated identity.

Identity provider

The current identity provider for the Oryvin environment is Keycloak.

Keycloak is responsible for:

  • user authentication
  • token issuance
  • role and group assignment
  • service account support
  • identity federation where required

Applications such as WEIC and Orchestrator validate issued tokens rather than implementing their own login systems.

This makes identity a shared infrastructure concern.

Identity categories

The Oryvin identity model distinguishes between several categories of identities.

Human users

Human users are interactive identities that access the platform through browsers, tools, or administrative interfaces.

Examples include:

  • readers of documentation
  • editors of knowledge content
  • administrators of services
  • operators running workflows

Service accounts

Service accounts are non-interactive identities used by services and automation.

Examples include:

  • Orchestrator calling WEIC APIs
  • Orchestrator publishing artifacts to DropBoxMini
  • internal automation retrieving controlled resources
  • infrastructure tasks using service-level authorization

Administrative identities

Some identities may hold broader administrative roles for system governance, role management, or service configuration.

These should be limited and explicitly controlled.

Authentication model

The authentication model is based on bearer tokens issued by Keycloak.

Typical flow:

  1. a user or service authenticates to Keycloak
  2. Keycloak issues a JWT access token
  3. the client presents the token to a target service
  4. the target service validates the token
  5. the service applies authorization rules based on token claims and roles

This keeps authentication centralized while allowing authorization to remain explicit in each service.

Token model

The initial token model uses JWT bearer tokens.

Typical token contents include:

  • issuer
  • subject
  • audience
  • expiration
  • roles
  • client identity
  • service account identity where applicable

Applications should validate at least:

  • token issuer
  • token expiration
  • token signature
  • expected audience
  • relevant role claims

This validation is part of the service boundary.

Authorization model

Authorization decisions are made by each service based on authenticated identity and assigned roles.

Authorization is not delegated entirely to the identity provider. Keycloak provides trusted identity and role claims, but each application still decides what operations those roles can perform.

This keeps application behavior explicit while preserving centralized authentication.

Role model

The initial platform role model should remain small and understandable.

Reader

A reader may:

  • view documentation and published knowledge
  • retrieve approved content
  • access read-only system information where permitted

Editor

An editor may:

  • create and edit documents
  • create revisions
  • manage fragments
  • update controlled metadata within their scope

Reviewer

A reviewer may:

  • review revisions
  • approve or reject governed content
  • participate in knowledge governance workflows

This role may overlap with editor in simpler environments, but it should be distinct in the model.

Publisher

A publisher may:

  • publish approved content
  • control which revision becomes published
  • manage publication workflows and release actions

Operator

An operator may:

  • execute approved workflows
  • view operational workflow results
  • manage automation runs within defined boundaries

Administrator

An administrator may:

  • manage system configuration
  • manage higher-privilege workflows
  • oversee security and governance settings
  • perform administrative actions across services

These roles can later be mapped differently per service, but the conceptual model should remain consistent.

Service-level authorization examples

Different services apply roles differently.

WEIC

Typical WEIC authorization examples:

  • reader: retrieve readable content
  • editor: create and edit documents and fragments
  • reviewer: review revisions
  • publisher: publish approved content
  • administrator: manage higher-level governance and administration

Orchestrator

Typical Orchestrator authorization examples:

  • operator: run workflows
  • administrator: manage automation configuration and privileged operations
  • reader: view workflow results where allowed

DropBoxMini

Typical DropBoxMini authorization examples:

  • service account: publish artifacts
  • operator or reader: retrieve artifacts where allowed
  • administrator: manage storage or system behavior

This allows one shared identity system to support several application-specific policy layers.

Service accounts

Service accounts are essential to Oryvin because the platform includes automation and service-to-service interactions.

Typical service account use cases include:

  • Orchestrator publishing artifacts to DropBoxMini
  • internal automation retrieving or updating WEIC content
  • infrastructure automation invoking protected service endpoints

Service accounts should have:

  • explicit client identity
  • minimal required roles
  • non-interactive access patterns
  • separate credential management from human user accounts

This keeps automation secure and traceable.

Least-privilege principle

Both human users and service accounts should operate under least privilege.

This means:

  • grant only required roles
  • avoid broad administrator use for routine tasks
  • separate review, publication, and operational privileges where practical
  • scope service accounts tightly to their intended purpose

Least privilege is especially important for automated workflows because automation can perform actions repeatedly and at scale.

API authorization expectations

Protected APIs should enforce both authentication and authorization.

Typical rules include:

  • reject missing or invalid tokens
  • require appropriate role claims
  • restrict write operations to allowed roles
  • distinguish between read-only and privileged operations
  • treat service account operations explicitly rather than implicitly

Authorization should never rely only on the client behaving correctly.

Identity and evidence

Identity is part of the traceability chain.

Important actions should be attributable to an identity such as:

  • document revision authorship
  • review approvals or rejections
  • publication actions
  • workflow execution requests
  • artifact publication

This matters for governance, auditability, and compliance use cases.

Future extensions

The identity model is designed to support later extensions such as:

  • finer-grained permissions
  • scoped service roles
  • approval separation rules
  • environment-specific authorization
  • federated identity sources
  • stronger machine-to-machine trust models

These can be added without changing the core principles of centralized authentication and explicit authorization.

Design principles summary

The identity model follows these core rules:

  • authentication is centralized
  • authorization is explicit
  • roles are used instead of ad hoc user logic
  • service accounts are first-class identities
  • important actions are attributable to identities

Relationship to the Oryvin plan

The identity model is one of the security foundations of the Oryvin system.

authenticated identity
        ↓
authorized operation
        ↓
traceable content, workflow, or artifact action

Without a consistent identity model, the platform becomes fragmented and difficult to govern. With it, the platform can grow across documentation, automation, delivery, and operations while remaining coherent.