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.jsonfor 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_SIGNER |
JWT signer backend: file (default) or kms_aws |
GATEWAY_JWT_KEYS_FILE |
Path to the file-backed signer's keys file (see docs/key-rotation.md) |
GATEWAY_JWT_KMS_KEYS |
AWS KMS signer: CSV of kid=arn entries |
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
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
identity
command
Command identity is the identity service container entry point.
|
Command identity is the identity service container entry point. |
|
examples
|
|
|
embedded
command
Command embedded shows how a host program mounts identity into its own Go server instead of running the dedicated container.
|
Command embedded shows how a host program mounts identity into its own Go server instead of running the dedicated container. |
|
gen
|
|
|
Package identityserver is identity's embeddable public API.
|
Package identityserver is identity's embeddable public API. |
|
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. |
|
observability
Package observability wires OpenTelemetry traces for the identity server.
|
Package observability wires OpenTelemetry traces for the identity server. |
|
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.
|
Package jwt provides RS256 JWT signing, verification, and JWKS publishing. |
|
jwt/file
Package file implements the default file-backed jwt.Signer for the identity service.
|
Package file implements the default file-backed jwt.Signer for the identity service. |
|
jwt/jwttest
Package jwttest provides an in-process jwt.Signer for tests.
|
Package jwttest provides an in-process jwt.Signer for tests. |
|
jwt/kmsaws
Package kmsaws implements a jwt.Signer that delegates the signature operation to AWS KMS.
|
Package kmsaws implements a jwt.Signer that delegates the signature operation to AWS KMS. |
|
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. |
Click to show internal directories.
Click to hide internal directories.