Legion System Authentication

A standalone authentication service for Legion integrations on edge devices, development machines, and other systems. This service handles OAuth2 authentication, token lifecycle management (automatic refreshes), and terminal entity registration.

For comprehensive API details, please refer to the Legion API Documentation.

Features

• OAuth2 PKCE Flow: Secure authentication without hardcoded credentials.
• Automatic Token Management: Monitors and refreshes access tokens automatically.
• Headless Support: Supports authentication flows on headless devices via local callbacks.
• Service Integration: Built-in support for installing as a system service:
  • Linux: Systemd
  • macOS: Launchd

Installation

Quick Install (Recommended)

Install the latest release with a single command:

curl -fsSL https://raw.githubusercontent.com/picogrid/legion-system-auth/main/install.sh | bash

The script will automatically detect your platform and prompt for sudo if needed.

Build from Source

Prerequisites

• Go 1.23 or later
• Make

Build and Install

1. Clone the repository:

   git clone https://github.com/picogrid/legion-system-auth.git
   cd legion-system-auth

2. Build the binary:

   make build

3. Install globally (optional):

   sudo make install

   This installs legion-auth to /usr/local/bin.

Usage

1. Initial Setup

Run the interactive setup wizard to authenticate and configure the integration.

legion-auth setup

Options:

• --create-entity: Prompts to create a Terminal entity in Legion during setup.
• --storage-path <dir>: Custom directory to store tokens and config (Default: /etc/picogrid/auth).

Example:

legion-auth setup --create-entity

2. Install as a Service (Recommended)

To ensure the token monitor runs automatically and keeps credentials fresh, you can install as either a user-level or system-level service:

User-Level Service (No sudo required)

Runs as your user account and starts automatically on login:

legion-auth install-service --user

Benefits:

• No sudo required
• Runs with your user permissions
• Starts automatically when you log in
• Stores credentials in your home directory

System-Level Service (Requires sudo)

Runs at system startup with specified user permissions:

sudo legion-auth install-service

This will:

• Generate the appropriate service file (systemd unit or launchd plist)
• Enable the service to start at boot
• Start the service immediately

Custom options:

• --service-user User to run service as (Linux system-level only, default: "pg" if exists, otherwise "root")
• --service-group Group to run service as (Linux system-level only, default: primary group of service user)

# Custom storage path
legion-auth install-service --user --storage-path ~/.config/legion-auth

# System-level with specific user (Linux only)
sudo legion-auth install-service --service-user myuser

# System-level with specific user and group (Linux only)
sudo legion-auth install-service --service-user myuser --service-group mygroup

3. Uninstall Service

To remove an installed service:

# Uninstall user-level service
legion-auth uninstall-service --user

# Uninstall system-level service (requires sudo)
sudo legion-auth uninstall-service

This will:

• Stop the running service
• Disable it from starting automatically
• Remove the service configuration file

4. Manual Execution

You can run the monitor process manually (foreground):

legion-auth

Configuration

The service stores its data in /etc/picogrid/auth by default.

• oauth_config.json: Integration settings.
• access_token.json: Current active tokens.
• refresh_token.json: Long-lived refresh token.
• terminal_entity.json: Device metadata (if entity creation was used).

Security & Verification

All release binaries include SHA256 checksum files (.sha256) for integrity verification.

Verifying Checksums

# Download binary and checksum
curl -LO https://github.com/picogrid/legion-system-auth/releases/latest/download/legion-auth-linux-amd64
curl -LO https://github.com/picogrid/legion-system-auth/releases/latest/download/legion-auth-linux-amd64.sha256

# Verify
sha256sum -c legion-auth-linux-amd64.sha256

The install script automatically verifies checksums when available.

Development

Building

• Build: make build - Build the binary with version info
• Clean: make clean - Remove build artifacts

Quality Checks

• Test: make test - Run tests with race detection and coverage
• Lint: make lint - Run golangci-lint
• Security: make security - Run gosec security scanner
• Check All: make check - Run all checks (fmt, vet, lint, security, test)

Installation

• Install: make install - Install binary to /usr/local/bin
• Install Service: sudo make install-service - Install as system service

Help

• Help: make help - Show all available make targets