Identity Service
A robust Go microservice for enterprise-grade User, Company, and Team management. Features pluggable authorization, OpenTelemetry, and native MCP support.
Quickstart
Get Identity up and running in minutes using our Docker-based local development environment.
# 1. Clone & Start
git clone https://github.com/launchrail/identity
cd identity
docker-compose up -d
# 2. Run initial migrations
make migrate-upCLI Interaction
Local Run & Dev
The Identity service is a highly optimized Go microservice designed for high-concurrency user and membership operations.
Bootstrap Environment
git clone https://github.com/launch-rail/identity.git
cd identity
make dev-setup
docker-compose up -dThe make dev-setup command initializes dependencies and regenerates protobuf + SQLC artifacts.
Client SDK Usage
const { user, error } = await identity.signIn({
email: "user@example.com",
password: "secure-password"
});
if (user) {
// Session is automatically established via secure cookies
window.location.href = "/dashboard";
}Architecture
Stateless authentication with session-shadowing. Identities are verified at the edge, while authorization is enforced at the core.
Core Domain Entities
Our data model is built for B2B SaaS complexity, supporting multi-tenant isolation and granular membership roles.
User
The primary identity entity. Linked to authentication providers (Kratos, Zitadel) and audit trails.
Company (Tenant)
The root tenant container. Controls domain white-labeling, billing context, and global settings.
Team
A logical grouping of users within a company. Supports nested hierarchies and team-specific permissions.
Membership
The join entity mapping Users to Companies/Teams with specific Roles and Permissions.
Configuration Reference
Configure the service via Environment Variables or a config.yaml file.
Core Service Settings
| Variable | Default | Description |
|---|---|---|
| PORT | 8080 | HTTP/ConnectRPC listener |
| ENVIRONMENT | development | Set to production for strict validation |
| TRUSTED_PROXY_CIDRS | - | Required in prod for identity header trust |
Infrastructure State
Relational: PostgreSQL
Main source of truth for all domain entities. Use a connection pool for production.
const response = await identity.verifyMfa({
userId: "user-123",
code: "123456",
strategy: "TOTP"
});Ephemeral: Redis
Used for distributed caching of authorization results and session lookups.
REDIS_ENABLED=true
REDIS_ADDR=localhost:6379Event Bus Providers
The service emits events for all mutations (e.g., user.created, company.updated).
const response = await identity.validateSession({
token: "session-token-from-cookie"
});
if (response.valid) {
console.log("Authenticated as:", response.user.email);
}Authorization Architecture
Pluggable check engine supporting local database evaluation or remote providers like Ory Keto or Zitadel.
Check Providers
- Database: Eval permissions via SQL joins (Good for simple SaaS)
- Ory Keto: Google Zanzibar-style tuple checking
- Zitadel: Built-in IAM and policy evaluation
Resilience
Remote providers are automatically wrapped with:
- • Automatic Retries
- • Circuit Breakers
- • LRU In-Memory Caching
Policy & Overrides
Control mapping from high-level roles to granular permissions via JSON policy overrides.
{
"AUTH_POLICY_OVERRIDES": {
"organization_admin": ["read", "write", "manage_billing", "delete_company"],
"team_lead": ["read", "write", "manage_members"]
}
}Deployment & Operations
Recommended Production Controls
- • Set
ENVIRONMENT=productionto enable strict header validation. - • Use
cmd/migratoras a k8s init-container or pre-deploy job. - • Configure
OTEL_COLLECTOR_URLfor trace export.
GCP / Cloud Run Quick-Deploy
# Build image
gcloud builds submit --tag gcr.io/$PROJECT_ID/identity .
# Deploy manually
gcloud run deploy identity \
--image gcr.io/$PROJECT_ID/identity:latest \
--region us-central1 \
--platform managed \
--set-env-vars ENVIRONMENT=production,DATABASE_URL=...