LFX v2 Auth Service

A NATS-based authentication and user management microservice for the LFX v2 platform. This service provides an abstraction layer between applications and identity providers (Auth0 and Authelia).

Overview

The LFX v2 Auth Service provides authentication and profile access in the v2 Platform, serving as an abstraction layer between applications and identity providers (Auth0 and Authelia). This service enables user management, profile updates, email/social account linking, and user discovery while maintaining compatibility across different deployment environments.

The service operates as a NATS-based microservice, responding to request/reply patterns on specific subjects.

Prerequisites

• Go 1.24.5+
• NATS server
• Auth0 configuration (optional, defaults to mock mode)
• Kubernetes cluster (for local Authelia development setup)

Local Development Support

The auth-service supports Authelia + NATS KV integration for local development environments. This setup provides:

• Authelia as a local identity provider running in Kubernetes
• NATS Key-Value store for persistent user data storage
• Automatic synchronization between NATS KV and Authelia's ConfigMap/Secrets
• DaemonSet restart capability when user data changes require Authelia pod restarts

For detailed information about the Authelia integration architecture and sync mechanisms, see: internal/infrastructure/authelia

Installation

├── .github/                        # Github files
│   └── workflows/                  # Github Action workflow files
├── charts/                         # Helm charts for running the service in kubernetes
├── cmd/                            # Services (main packages)
│   └── server/                     # Auth service code
├── internal/                       # Internal service packages
│   ├── domain/                     # Domain logic layer (business logic)
│   │   ├── model/                  # Domain models and entities
│   │   └── port/                   # Repository and service interfaces
│   ├── service/                    # Service logic layer (use cases)
│   └── infrastructure/             # Infrastructure layer
├── pkg/                            # Shared packages
│   ├── constants/                  # Application constants
│   ├── converters/                 # Data conversion utilities
│   ├── errors/                     # Error handling utilities
│   ├── httpclient/                 # HTTP client utilities
│   └── log/                        # Logging utilities
└── README.md                       # This documentation

Usage

NATS Request/Reply Pattern

The LFX v2 Auth Service operates as a NATS-based microservice that responds to request/reply patterns on specific subjects. The service provides user management capabilities through NATS messaging.

Available Operations

The service exposes NATS request/reply operations grouped by area. Each link has the full reference (subjects, payloads, examples):

• Email Lookups — look up a user by email
• Username Lookups — look up a subject identifier by username
• User Metadata — read and update user profile metadata
• User Emails — read emails and set the primary email
• Email Verification — passwordless OTP verification of alternate emails
• Identity Linking — link, unlink, and list identities
• Password Management — change password and send reset links
• Impersonation — exchange a token to act as another user
• Aliases — claim a system-managed alias email
• Indexer Contract — data sent to the indexer service (currently none)

For end-to-end authentication flows, see Auth Flows.

---

Configuration

NATS Configuration

The NATS client can be configured using environment variables:

• NATS_URL: NATS server URL (default: nats://localhost:4222)
• NATS_TIMEOUT: Request timeout duration (default: 10s)
• NATS_MAX_RECONNECT: Maximum reconnection attempts (default: 3)
• NATS_RECONNECT_WAIT: Time between reconnection attempts (default: 2s)

Auth0 Configuration

The Auth0 integration can be configured using environment variables:

• USER_REPOSITORY_TYPE: Set to "auth0" to use Auth0 integration, or "mock" for local development
  • If not set, defaults to "mock"
• AUTH0_TENANT: Auth0 tenant name (e.g., "linuxfoundation", "linuxfoundation-staging", "linuxfoundation-dev")
  • Required when using Auth0 repository type
• AUTH0_DOMAIN: Auth0 domain for Management API calls (e.g., "sso.linuxfoundation.org")
  • If not set, defaults to ${AUTH0_TENANT}.auth0.com
• AUTH0_M2M_CLIENT_ID: Auth0 Machine-to-Machine application client ID
  • Required when using Auth0 repository type
• AUTH0_M2M_PRIVATE_BASE64_KEY: Private key for Auth0 M2M authentication (base64-encoded or raw PEM)
  • Required when using Auth0 repository type
• AUTH0_AUDIENCE: Auth0 API audience/identifier for the Management API
  • Required when using Auth0 repository type
• AUTH0_LFX_PROFILE_CLIENT_ID: Auth0 LFX Profile client ID (Regular Web Application) for passwordless flows
  • Required when using passwordless email linking flow
• AUTH0_LFX_PROFILE_CLIENT_SECRET: Auth0 LFX Profile client secret (Regular Web Application) for passwordless flows
  • Required when using passwordless email linking flow

Releases

Creating a Release

To create a new release of the auth service:

1. Update the chart version in charts/lfx-v2-auth-service/Chart.yaml prior to any project releases, or if any change is made to the chart manifests or configuration:

   version: 0.2.0  # Increment this version
   appVersion: "latest"  # Keep this as "latest"

2. After the pull request is merged, create a GitHub release and choose the option for GitHub to also tag the repository. The tag must follow the format v{version} (e.g., v0.2.0). This tag does not have to match the chart version: it is the version for the project release, which will dynamically update the appVersion in the released chart.

3. The GitHub Actions workflow will automatically:

   • Build and publish the container images (auth-service)
   • Package and publish the Helm chart to GitHub Pages
   • Publish the chart to GitHub Container Registry (GHCR)
   • Sign the chart with Cosign
   • Generate SLSA provenance

Important Notes

• The appVersion in Chart.yaml should always remain "latest" in the committed code.
• During the release process, the ko-build-tag.yaml workflow automatically overrides the appVersion with the actual tag version (e.g., v0.2.0 becomes 0.2.0).
• Only update the chart version field when making releases - this represents the Helm chart version.
• The container image tags are automatically managed by the consolidated CI/CD pipeline using the git tag.
• Both container images (auth-service) and the Helm chart are published together in a single workflow.

Development

To contribute to this repository:

1. Fork the repository
2. Commit your changes to a feature branch in your fork. Ensure your commits are signed with the Developer Certificate of Origin (DCO). You can use the git commit -s command to sign your commits.
3. Ensure the chart version in charts/lfx-v2-auth-service/Chart.yaml has been updated following semantic version conventions if you are making changes to the chart.
4. Submit your pull request

License

Copyright The Linux Foundation and each contributor to LFX.

This project’s source code is licensed under the MIT License. A copy of the license is available in LICENSE.

This project’s documentation is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). A copy of the license is available in LICENSE-docs.