OAuth

Introduction

VeilNet Conflux can use OAuth-issued JWTs for identity-based access control. When you register a Conflux (via the CLI, system service, Docker, or Kubernetes), you can pass the JWT and the metadata Guardian needs to verify it. Guardian validates the token via JWKS and uses it for Packet-Level Authentication; it does not store the JWT.

This guide describes how to pass JWT and related options during registration in DevOps workflows. For how to obtain JWTs and configure your identity provider, see the developer OAuth guide.

What you need to pass

For Guardian to verify your JWT, provide:

These are optional identity/auth fields on veilnet-conflux register; they are forwarded to Guardian during registration. You still need a registration token (-t / VEILNET_REGISTRATION_TOKEN) to call Guardian.

Reference: System Service — register flags.

System service (CLI)

Using flags

sudo veilnet-conflux register \
  -t "$VEILNET_REGISTRATION_TOKEN" \
  --guardian "https://guardian.veilnet.app" \
  --tag "my-node" \
  --jwt "$VEILNET_CONFLUX_JWT" \
  --jwks-url "https://your-idp.example.com/.well-known/jwks.json" \
  --issuer "https://your-idp.example.com/" \
  --audience "https://api.example.com"

Using environment variables

Set the same values via env vars so you don’t put secrets on the command line:

export VEILNET_REGISTRATION_TOKEN="..."
export VEILNET_GUARDIAN="https://guardian.veilnet.app"
export VEILNET_CONFLUX_TAG="my-node"
export VEILNET_CONFLUX_JWT="eyJ..."
export VEILNET_CONFLUX_JWKS_URL="https://your-idp.example.com/.well-known/jwks.json"
export VEILNET_CONFLUX_ISSUER="https://your-idp.example.com/"
export VEILNET_CONFLUX_AUDIENCE="https://api.example.com"

sudo -E veilnet-conflux register

Use sudo -E so the environment is preserved. For a systemd service, put these in a protected env file and source it in the service unit, or use a secrets manager.

Docker

Pass JWT and related options through the container environment (env file or environment in Compose). The Conflux container typically runs the binary with no subcommand (defaults to run), so it uses config that was written at registration time. If you register inside the container at startup, use the same env vars:

# Example: env file for registration or for a container that runs Conflux
VEILNET_REGISTRATION_TOKEN=...
VEILNET_GUARDIAN=https://guardian.veilnet.app
VEILNET_CONFLUX_TAG=my-node
VEILNET_CONFLUX_JWT=eyJ...
VEILNET_CONFLUX_JWKS_URL=https://your-idp.example.com/.well-known/jwks.json
VEILNET_CONFLUX_ISSUER=https://your-idp.example.com/
VEILNET_CONFLUX_AUDIENCE=https://api.example.com

In Docker Compose, reference this file with env_file and ensure the Conflux service runs with these variables when it performs registration (or when it starts and reads existing conflux.json that was created with JWT the first time).

Kubernetes

Store the JWT and identity provider settings in a Secret, and reference them in the Conflux container’s env (e.g. sidecar or DaemonSet). Use the same variable names so the Conflux process receives them when it registers or starts:

apiVersion: v1
kind: Secret
metadata:
  name: veilnet-conflux-secret
  namespace: default
type: Opaque
stringData:
  VEILNET_REGISTRATION_TOKEN: "<YOUR_REGISTRATION_TOKEN>"
  VEILNET_GUARDIAN: "https://guardian.veilnet.app"
  VEILNET_CONFLUX_TAG: "<YOUR_TAG>"
  VEILNET_CONFLUX_JWT: "<YOUR_JWT>"
  VEILNET_CONFLUX_JWKS_URL: "https://your-idp.example.com/.well-known/jwks.json"
  VEILNET_CONFLUX_ISSUER: "https://your-idp.example.com/"
  VEILNET_CONFLUX_AUDIENCE: "https://api.example.com"
  # Optional: mode, IP, taints
  VEILNET_CONFLUX_PORTAL: "true"
  VEILNET_CONFLUX_IP: "10.128.0.1"

Then in your Pod spec:

containers:
  - name: veilnet-conflux
    image: veilnet/conflux:beta
    envFrom:
      - secretRef:
          name: veilnet-conflux-secret
    # ... securityContext, volumeMounts, etc.

If the Conflux container runs a wrapper that calls veilnet-conflux register at startup, it will pick up these env vars and pass JWT/JWKS/issuer/audience to Guardian during registration.