feat(server): Generic external auth callout

[sansmoraxz]

Description

Currently Iggy supports built-in credentials and external JWT verification for HTTP only. A trusted JWT issuer maps all accepted tokens to a configured Iggy user, after which authorization uses that user’s locally stored permissions.

There is no mechanism for an external service to authenticate a client and return its effective permissions.

This limits integration with centralized identity and policy systems, especially for service-to-service and device-oriented protocols.

For example, consider a scenario of fleet of embedded devices which support MQTT. During CONNECT iggy may resolve its effective permissions without provisioning a persistent Iggy user for every device.

Affected area / component

Wire protocol / API

Proposed solution

During client login or protocol handshake:

1. Iggy sends one request to the configured auth service
2. auth service authenticates the client and returns permissions
3. Iggy creates an authenticated session
4. existing operation-specific permission rules enforce the permissions

Sample request (schema too be refined):

{
  "transport": "tcp",
  "connection_id": "0195f4d7-57d3-7c21-a711-08a147ad6c90",
  "remote_address": "192.0.2.10:54321",
  "credentials": {
    "type": "username_password",
    "username": "application-service",
    "secret": "<redacted>"
  }
}

The credential object can be a tagged enum so other variants can be supported present and future, viz bearer tokens, X509 certs, etc.

Example response using session-scoped permissions:

{
  "authenticated": true,
  "principal": "service:analytics-ingestor",
  "authorization": {
    "type": "permissions",
    "permissions": {
      "global": {
        "manage_servers": false,
        "read_servers": false,
        "manage_users": false,
        "read_users": false,
        "manage_streams": false,
        "read_streams": false,
        "manage_topics": false,
        "read_topics": false,
        "poll_messages": false,
        "send_messages": false
      },
      "streams": {
        "42": {
          "manage_stream": false,
          "read_stream": false,
          "manage_topics": false,
          "read_topics": false,
          "poll_messages": false,
          "send_messages": true,
          "topics": null
        }
      }
    }
  },
  "expires_at": 1787212800
}

Alternatively, the provider could select an existing Iggy user:

{
  "authenticated": true,
  "principal": "service:analytics-ingestor",
  "authorization": {
    "type": "iggy_user",
    "user_id": 12
  },
  "expires_at": 1787212800
}

A denied response could be:

{
  "authenticated": false,
  "reason": "credential revoked"
}

Session-scoped permissions should reuse Iggy’s existing Permissions, GlobalPermissions, StreamPermissions, and TopicPermissions structures. They must not create users or modify persisted permissions.

The provider must fail closed on timeout, invalid response, explicit denial, or unavailability.

Decision left to maintainers on whether to follow fixed schema or define via some form of templating.

Alternatives considered

• Provision an Iggy user for every external identity: Works with the current permission model but creates lifecycle and synchronization overhead, particularly for large device fleets.
• Map each JWT issuer to one fixed Iggy user: Already supported for HTTP trusted issuers, but it cannot assign different permissions to individual external subjects.
• Call the authorization service for every operation: Supports immediate policy changes but adds latency and availability dependencies to message hot paths.
• Use client-certificate authentication: Suitable for some service identities, but it still requires identity-to-permission mapping and does not cover all credential types.

Contribution

• I'm willing to submit a pull request to implement this feature

Good first issue

• I think this could be a good first issue for a new contributor