identity

module

v0.6.6 Latest Latest Go to latest Published: May 13, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/elloloop/identity

Links

Open Source Insights

README ¶

Identity

Authentication and user-management service. Deploys as a single container; pulls a pinned image, points at an EntDB instance, exposes Connect-RPC over HTTP/JSON.

Treat this like tenant-shard-db: one image, deployed once per product, fully isolated user pools.

What it provides

Email + password signup, login, change, reset, lockout
Passkeys (WebAuthn) registration and login
TOTP (2FA) setup, verify, recovery codes
QR cross-device login
OAuth login (Google, Microsoft — server consumes pre-verified ID tokens from frontend SDKs)
Sessions with revoke and sign-out-everywhere
JWT issuance with key rotation, plus /.well-known/jwks.json for downstream services
User and Group CRUD, group membership data
Audit log of auth events
Email and phone verification flows

Identity authenticates users, issues JWTs, and assigns coarse roles (admin / member / guest). It stores groups and memberships, but it does not enforce per-group or per-resource ACLs. Calling applications are responsible for authorization decisions built on that data.

Storage

All persistent state lives in EntDB. The service reserves type IDs 1–99 in the EntDB schema:

type_id	Node
1	User
2	Group
5	RefreshToken
6	Passkey
7	TOTPSecret
8	AuditEvent

Other services consuming the same EntDB instance must use type IDs 100+ to avoid collisions.

Configuration

All config is via environment variables. See internal/config/config.go for the full list. Most-tweaked:

Var	Purpose
`GATEWAY_ENTDB_ADDRESS`	EntDB endpoint (e.g. `entdb:50051`)
`GATEWAY_DEFAULT_TENANT_ID`	Tenant ID for this deployment (each product = its own tenant)
`GATEWAY_JWT_KEYS`	JWT signing key ring (JSON, base64-encoded RSA private keys)
`GATEWAY_PASSKEY_RP_ID`	Passkey relying party ID — must match your domain
`GATEWAY_PASSKEY_ORIGIN`	Allowed origin for passkey ceremonies
`GATEWAY_TOTP_ISSUER`	Name shown in user authenticator apps
`GATEWAY_DEFAULT_EMAIL_DOMAIN`	Default email domain for new accounts
`GATEWAY_ALLOWED_ORIGINS`	CORS origins
`GATEWAY_AUTH_ALLOW_LOCAL`	Set `false` in prod to disable username/password if you only want OAuth

Deployment

Pull the image and run alongside an EntDB instance:

docker run -p 80:80 -p 9090:9090 \
  -e GATEWAY_ENTDB_ADDRESS=entdb:50051 \
  -e GATEWAY_DEFAULT_TENANT_ID=my-product \
  -e GATEWAY_PASSKEY_RP_ID=my-product.com \
  -e GATEWAY_PASSKEY_ORIGIN=https://my-product.com \
  -e GATEWAY_TOTP_ISSUER="My Product" \
  ghcr.io/elloloop/identity:0.1.0

Releasing

Push a v* tag — .github/workflows/release.yml builds and pushes a multi-arch image to ghcr.io/elloloop/identity:<version>.

git tag v0.1.0
git push origin v0.1.0

Local development

go build ./...
go test ./...

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
identity command Command identity is the identity service entry point.	Command identity is the identity service entry point.
gen
go/entdb
go/identity
go/identity/identityconnect
go/identity/schema
internal
app Package app builds the identity service HTTP handler from injected dependencies.	Package app builds the identity service HTTP handler from injected dependencies.
config Package config loads the identity service configuration from environment variables with the GATEWAY_ prefix.	Package config loads the identity service configuration from environment variables with the GATEWAY_ prefix.
connect Package connect provides the Connect-Go RPC handler layer for the identity service.	Package connect provides the Connect-Go RPC handler layer for the identity service.
middleware
repo Package repo selects between concrete service.Repository / service.DB drivers (entdb, postgres, memory) for the production binary's wiring code.	Package repo selects between concrete service.Repository / service.DB drivers (entdb, postgres, memory) for the production binary's wiring code.
repo/conformance Package conformance is a driver-agnostic test suite for service.Repository implementations.	Package conformance is a driver-agnostic test suite for service.Repository implementations.
repo/entdb Package entdb is the EntDB-backed implementation of service.Repository.	Package entdb is the EntDB-backed implementation of service.Repository.
repo/memory Package memory is the in-process Repository driver.	Package memory is the in-process Repository driver.
repo/postgres Package postgres provides a Postgres-backed implementation of service.Repository for the identity service.	Package postgres provides a Postgres-backed implementation of service.Repository for the identity service.
service Package service implements the business logic for the identity service.	Package service implements the business logic for the identity service.
pkg
audit Package audit provides best-effort audit event logging to EntDB.	Package audit provides best-effort audit event logging to EntDB.
email Package email provides a provider-agnostic email transport layer.	Package email provides a provider-agnostic email transport layer.
idv Package idv defines the pluggable identity-verification provider interface.	Package idv defines the pluggable identity-verification provider interface.
jwt Package jwt provides RS256 JWT signing, verification, and JWKS publishing with key rotation support.	Package jwt provides RS256 JWT signing, verification, and JWKS publishing with key rotation support.
oauth Package oauth implements provider-side OAuth code-exchange flows for authenticating end users into the identity service.	Package oauth implements provider-side OAuth code-exchange flows for authenticating end users into the identity service.
passkeys Package passkeys provides WebAuthn/FIDO2 passkey registration and authentication using the go-webauthn library.	Package passkeys provides WebAuthn/FIDO2 passkey registration and authentication using the go-webauthn library.
passwords Package passwords provides bcrypt password hashing and strength validation.	Package passwords provides bcrypt password hashing and strength validation.
totp Package totp provides TOTP (RFC 6238) utilities for two-factor authentication.	Package totp provides TOTP (RFC 6238) utilities for two-factor authentication.