hook-service

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.

Features

JWT Authentication

The Groups and Authorization APIs (/api/v0/authz) are protected by JWT authentication middleware. When enabled, all requests to these endpoints must include a valid JWT token in the Authorization header.

Configuration:

• AUTHENTICATION_ENABLED: Set to true to enable JWT authentication (default: true)
• AUTHENTICATION_ISSUER: The expected JWT issuer URL. Used for OIDC metadata discovery to fetch JWKS or to verify the iss claim when using manual JWKS URL
• AUTHENTICATION_JWKS_URL: (Optional) Explicit JWKS URL. If set, fetches keys from this URL instead of using OIDC discovery
• AUTHENTICATION_ALLOWED_SUBJECTS: Comma-separated list of allowed JWT sub claims
• AUTHENTICATION_REQUIRED_SCOPE: (Optional) A specific scope that grants access (e.g., hook-service:admin)

JWKS Configuration:

The middleware supports two modes for fetching JWKS:

1. OIDC Discovery (default): Discovers JWKS URL from {AUTHENTICATION_ISSUER}/.well-known/openid-configuration
2. Manual JWKS URL: If AUTHENTICATION_JWKS_URL is set, fetches keys directly from that URL

Use manual JWKS URL when the issuer is not an OIDC provider or when OIDC discovery is not available.

Authorization Logic:

A request is authorized if either:

1. The JWT's sub claim matches one of the AUTHENTICATION_ALLOWED_SUBJECTS, OR
2. The JWT's scope or scp claim contains the AUTHENTICATION_REQUIRED_SCOPE

Usage:

# Include JWT token in Authorization header
curl -H "Authorization: Bearer <jwt-token>" http://localhost:8080/api/v0/authz/groups

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.