Hook Service

This is the Canonical Identity Platform Hook Service used for handling Hydra Hooks and managing groups. It integrates with Ory Kratos for identity management, Ory Hydra for OAuth2/OIDC flows, OpenFGA for fine-grained authorization, and optional Salesforce for group management.

Environment Variables

The application is configured via environment variables.

Variable	Description	Default
OTEL_GRPC_ENDPOINT	OTel gRPC endpoint for traces
OTEL_HTTP_ENDPOINT	OTel HTTP endpoint for traces
TRACING_ENABLED	Enable tracing	true
LOG_LEVEL	Log level (debug, info, warn, error)	error
DEBUG	Enable debug mode	false
PORT	HTTP server port	8080
API_TOKEN	Token for API authentication
OPENFGA_API_SCHEME	OpenFGA API scheme
OPENFGA_API_HOST	OpenFGA API host
OPENFGA_API_TOKEN	OpenFGA API token
OPENFGA_STORE_ID	OpenFGA store ID
OPENFGA_AUTHORIZATION_MODEL_ID	OpenFGA authorization model ID
SALESFORCE_ENABLED	Enable Salesforce integration	true
SALESFORCE_DOMAIN	Salesforce domain
SALESFORCE_CONSUMER_KEY	Salesforce consumer key
SALESFORCE_CONSUMER_SECRET	Salesforce consumer secret
AUTHORIZATION_ENABLED	Enable authorization middleware	false
OPENFGA_WORKERS_TOTAL	Total OpenFGA workers	150
DSN	Database connection string (Required)
DB_MAX_CONNS	Max DB connections	25
DB_MIN_CONNS	Min DB connections	2
DB_MAX_CONN_LIFETIME	Max DB connection lifetime	1h
DB_MAX_CONN_IDLE_TIME	Max DB connection idle time	30m

Development Setup

Prerequisites

• Go 1.25+
• Make
• Docker
• Rockcraft (for building the container image)

Build

To build the application binary:

make build

This produces a binary named app in the current directory.

Container

To build the OCI image using Rockcraft:

rockcraft pack

This will produce a .rock file which can be imported into Docker.

E2E Tests

The E2E tests are located in tests/e2e and run in a separate module to isolate test dependencies.

To run the E2E tests:

make test-e2e

This command will:

1. Switch to the tests/e2e directory.
2. Spin up the required environment (Postgres, Hydra, Kratos, OpenFGA) using Testcontainers.
3. Run the tests.

Local Development Environment

You can start a full local development environment including dependencies:

make dev
# or
./start.sh

This starts Kratos, Hydra, OpenFGA, Postgres, and Mailslurper using docker-compose.dev.yml.

Token Claims Configuration

The service adds user groups to OAuth2/OIDC tokens via the Hydra token hook. By default, Hydra would nest custom claims under an ext namespace. To ensure groups appear as a top-level claim in access tokens, the Hydra configuration includes:

oauth2:
  allowed_top_level_claims:
    - groups
  mirror_top_level_claims: false

This configuration is set in docker/hydra/hydra.yml for local development. For production deployments, ensure your Hydra instance is configured with these settings to make the groups claim accessible at the top level of the token payload.

Security

Please see SECURITY.md for guidelines on reporting security issues.