Runbook: OID (Identity Service)

Runbook: OID (Identity Service)

Last updated: 2026-03-30 Service owner: ODS Platform Team Pipeline status: STAGING_VERIFIED

1. Service Overview

OID is the OpenID Connect (OIDC) identity provider for the ODS Platform. It handles tenant provisioning, user authentication, JWT token issuance (RS256), OAuth 2.0 authorization code flow, client credentials (M2M), and JWKS endpoint for token verification by all other services.

Property Value
Language Rust (Actix-web)
Container port 8080
DB schema oid on ods database
DB tables tenants, users, clients, auth_codes, refresh_tokens, roles, user_roles
Event bus topic oid.events
Coolify app UUID h0w80o4kwwogkkoo8ww0ksw4

2. Health Check

Endpoint: GET /health Expected response: HTTP 200

curl -sf https://oid.staging.orbusdigital.com/health

3. Staging URL

https://oid.staging.orbusdigital.com

OIDC discovery: https://oid.staging.orbusdigital.com/.well-known/openid-configuration JWKS: https://oid.staging.orbusdigital.com/.well-known/jwks.json

4. Environment Variables

Variable Required Description
DATABASE_URL Yes postgres://ods:***@ods-postgres:5432/ods?search_path=oid
HOST No Bind address (default 0.0.0.0)
PORT No Listen port (default 8080)
CORS_ALLOWED_ORIGINS Yes Comma-separated allowed origins
JWT_ISSUER Yes https://oid.staging.orbusdigital.com
JWT_AUDIENCE Yes ods-platform
ACCESS_TOKEN_TTL_SECS No Token lifetime in seconds (default 3600)
REDPANDA_BROKERS No Kafka broker address (default in-memory)
REDPANDA_TOPIC No Event topic (default oid.events)
RUST_LOG No Log level filter (default info)
ODS_ENV No Environment identifier (staging)
E2E_BYPASS_TOKEN No Staging-only bypass for rate limiter during E2E tests
RATE_LIMIT_PER_MINUTE No Per-IP rate limit on auth endpoints (default 60)

5. How to Deploy

Via Coolify API (preferred)

source ~/.env.adlc 2>/dev/null
curl -sf -X POST "https://app.coolify.io/api/v1/applications/h0w80o4kwwogkkoo8ww0ksw4/restart" \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json"

Via Coolify Dashboard

  1. Open Coolify dashboard
  2. Navigate to project “Comite Produits” > OID
  3. Click “Deploy” or “Rebuild”

Git-based deploy

Push to the main branch of jniox/ods-oid on GitHub. Coolify auto-deploys from there.

6. How to Check Logs

# SSH to srv-staging (35.195.54.220) then:
docker logs --tail 200 -f $(docker ps -qf "label=coolify.applicationId=h0w80o4kwwogkkoo8ww0ksw4")

# Or by container name (may vary):
docker ps | grep oid
docker logs --tail 200 -f <container_id>

7. Common Issues and Fixes

Issue: JWT verification fails on other services

Symptom: Other services (docstore, pdf-engine, etc.) reject tokens with “invalid signature”.

Fix: Verify JWKS endpoint is accessible from inside the Docker network:

docker exec <other_service_container> curl -sf http://oid:8080/.well-known/jwks.json

If unreachable, ensure both containers are on the coolify Docker network.

Issue: Rate limiter blocking E2E tests

Symptom: E2E tests get HTTP 429 after a few requests.

Fix: Set E2E_BYPASS_TOKEN env var in Coolify and use X-E2E-Bypass header in test requests. Or increase RATE_LIMIT_PER_MINUTE.

Issue: Database connection refused

Symptom: Service fails to start, logs show “connection refused” to postgres.

Fix: Verify ods-postgres container is running and on the coolify network:

docker ps | grep ods-postgres
docker network inspect coolify | grep ods-postgres

8. How to Restart

# On srv-staging:
docker restart $(docker ps -qf "label=coolify.applicationId=h0w80o4kwwogkkoo8ww0ksw4")

Or via Coolify dashboard: navigate to OID app and click “Restart”.

9. Dependencies

Dependency Type Details
PostgreSQL 17 Database ods-postgres:5432, schema oid, 7 tables
Redpanda Event bus redpanda:9092, topic oid.events
None Upstream services OID is the root identity service; no upstream dependencies

Downstream dependents (services that depend on OID): - docstore (JWKS verification) - pdf-engine (JWKS verification) - notification-hub (JWKS verification) - workflow-engine (JWT secret or JWKS) - form-engine (JWKS verification)

10. Monitoring / Alerting