2. Digital Identity & Access¶

The Real Estate Platform consumes the government-wide KRDPASS identity system. This section defines how we integrate with it and the domain-specific access models for property services.

2.1 Architecture¶

graph TD
  subgraph GOV["🏛️ Government Shared Services (consumed)"]
    KRDPASS["🪪 KRDPASS\nNational Digital ID"]
    KC["🔑 Keycloak 24\nSSO / OAuth 2.1 / OIDC"]
    EJBCA["🔏 EJBCA\nDigital Signatures / PKI"]
  end

  subgraph RE["🏗️ Real Estate Platform (our system)"]
    PORTAL["🌐 Property Portal\n(Web + Mobile)"]
    ADMIN["⚙️ Admin Dashboard\n(Municipality Staff)"]
    API["📡 Property APIs"]
  end

  KRDPASS --> KC
  KC -->|JWT tokens| PORTAL
  KC -->|JWT tokens| ADMIN
  KC -->|service tokens| API
  EJBCA -->|digital signatures| API

2.2 Identity Integration¶

Aspect	Detail
Authentication	All users authenticate via Keycloak (SSO). The RE platform is a Keycloak client — we never store passwords.
Authorization	JWT tokens include roles and scopes. Our platform enforces property-specific permissions via OPA policies.
Digital Signatures	Property transfers, building permits, and legal documents require EJBCA digital signatures. Both parties sign.
Citizen Verification	For high-stakes operations (property transfer, mortgage), we request biometric verification via KRDPASS API.

2.3 User Roles (Domain-Specific)¶

Role	Description	Example Users
`property_owner`	Citizens who own property or want to buy/sell	Any KRG citizen
`real_estate_agent`	Licensed real estate agents acting on behalf of owners	Registered agents
`notary`	Authorized notaries who validate transactions	Government notaries
`municipality_clerk`	Staff processing applications, permits, registrations	Municipal office employees
`municipality_supervisor`	Supervisors who approve/reject complex cases	Senior municipal staff
`inspector`	Building inspectors, property valuators	Field officers
`gis_operator`	Staff managing spatial data, parcel boundaries	GIS department
`auditor`	Read-only access to audit trails and reports	Internal/external auditors
`system_admin`	Platform administration	IT team

2.4 Property Actor Registry¶

-- Property actors extend citizen identity with domain-specific data
CREATE TABLE property_actors (
    actor_id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    citizen_id          UUID NOT NULL,          -- Links to KRDPASS citizen_id
    actor_type          VARCHAR(30) NOT NULL,    -- owner, agent, notary, appraiser
    license_number      VARCHAR(50),             -- For agents and notaries
    license_issued_at   DATE,
    license_expires_at  DATE,
    license_status      VARCHAR(20) DEFAULT 'active', -- active, suspended, revoked, expired
    organization        VARCHAR(200),            -- Agency or firm name
    specialization      VARCHAR(100),            -- residential, commercial, agricultural, industrial
    governorate         VARCHAR(50),
    phone               VARCHAR(20),
    email               VARCHAR(255),
    is_verified         BOOLEAN DEFAULT FALSE,
    verified_at         TIMESTAMP,
    verified_by         UUID,
    created_at          TIMESTAMP DEFAULT NOW(),
    updated_at          TIMESTAMP DEFAULT NOW()
);

-- Power of attorney — allows agents to act on behalf of owners
CREATE TABLE power_of_attorney (
    poa_id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    grantor_citizen_id  UUID NOT NULL,           -- Property owner
    grantee_actor_id    UUID REFERENCES property_actors(actor_id),
    scope               VARCHAR(50) NOT NULL,    -- sale, purchase, all, specific_property
    property_id         UUID,                    -- NULL means all properties
    document_url        TEXT,                    -- Scanned/signed POA document
    document_hash       TEXT,                    -- SHA-256 integrity
    digital_signature   TEXT,                    -- EJBCA signature
    valid_from          DATE NOT NULL,
    valid_until         DATE NOT NULL,
    status              VARCHAR(20) DEFAULT 'active', -- active, revoked, expired
    created_at          TIMESTAMP DEFAULT NOW()
);

2.5 Authentication Flow for Property Transactions¶

sequenceDiagram
    participant Citizen as 👤 Property Owner
    participant Portal as 🌐 Portal
    participant KC as 🔑 Keycloak
    participant KRDPASS as 🪪 KRDPASS
    participant RE as ⚙️ RE Platform
    participant EJBCA as 🔏 EJBCA

    Citizen->>Portal: Initiate property transfer
    Portal->>KC: Redirect to login
    KC->>KRDPASS: Verify identity (biometric if high-stakes)
    KRDPASS-->>KC: Identity confirmed
    KC-->>Portal: JWT token (roles: property_owner)
    Portal->>RE: POST /transfers (JWT)
    RE->>RE: Validate token + check ownership
    RE->>EJBCA: Request digital signature
    EJBCA-->>RE: Signed document
    RE-->>Portal: Transfer initiated, pending counter-party