silo/docs/AUTH_USER_GUIDE.md

Silo Authentication User Guide

Logging In

Username and Password

Navigate to the Silo web UI. If authentication is enabled, you'll be redirected to the login page.

Enter your username and password. This works for both local accounts and LDAP/FreeIPA accounts — Silo tries local authentication first, then LDAP if configured.

Keycloak / OIDC

If your deployment has OIDC enabled, the login page will show a "Sign in with Keycloak" button. Click it to be redirected to your identity provider. After authenticating there, you'll be redirected back to Silo with a session.

Roles

Your role determines what you can do in Silo:

Role	Permissions
viewer	Read all items, projects, schemas, BOMs. Manage own API tokens.
editor	Everything a viewer can do, plus: create/update/delete items, upload files, manage BOMs, import CSV, generate part numbers.
admin	Everything an editor can do, plus: user management (future), configuration changes.

Your role is shown as a badge next to your name in the header. For LDAP and OIDC users, the role is determined by group membership or token claims and re-evaluated on each login.

API Tokens

API tokens allow the FreeCAD plugin, scripts, and CI pipelines to authenticate with Silo without a browser session. Tokens inherit your role.

Creating a Token (Web UI)

1. Click Settings in the navigation bar
2. Under API Tokens, enter a name (e.g., "FreeCAD workstation") and click Create Token
3. The raw token is displayed once — copy it immediately
4. Store the token securely. It cannot be shown again.

Creating a Token (CLI)

export SILO_API_URL=https://silo.example.internal
export SILO_API_TOKEN=silo_<your-existing-token>

silo token create --name "CI pipeline"

Output:

Token created: CI pipeline
API Token:     silo_a1b2c3d4e5f6...
Save this token — it will not be shown again.

Listing Tokens

silo token list

Revoking a Token

Via the web UI settings page (click Revoke next to the token), or via CLI:

silo token revoke <token-id>

Revocation is immediate. Any in-flight requests using the token will fail.

FreeCAD Plugin Configuration

The FreeCAD plugin reads the API token from two sources (checked in order):

1. FreeCAD Preferences: Tools > Edit parameters > BaseApp/Preferences/Mod/Silo > ApiToken
2. Environment variable: SILO_API_TOKEN

To set the token in FreeCAD preferences:

1. Open FreeCAD
2. Go to Edit > Preferences > General > Macro or use the parameter editor
3. Navigate to BaseApp/Preferences/Mod/Silo
4. Set ApiToken to your token string (e.g., silo_a1b2c3d4...)

Or set the environment variable before launching FreeCAD:

export SILO_API_TOKEN=silo_a1b2c3d4...
freecad

The API URL is configured the same way via the ApiUrl preference or SILO_API_URL environment variable.

Default Admin Account

On first deployment, configure a default admin account to bootstrap access:

# config.yaml
auth:
  enabled: true
  local:
    enabled: true
    default_admin_username: "admin"
    default_admin_password: ""  # Set via SILO_ADMIN_PASSWORD env var

export SILO_ADMIN_PASSWORD=<strong-password>

The admin account is created on the first startup if it doesn't already exist. Subsequent startups skip creation. Change the password after first login via the database or a future admin UI.

Configuration Reference

Minimal (Local Auth Only)

auth:
  enabled: true
  session_secret: ""  # Set via SILO_SESSION_SECRET

  local:
    enabled: true
    default_admin_username: "admin"
    default_admin_password: ""  # Set via SILO_ADMIN_PASSWORD

LDAP / FreeIPA

auth:
  enabled: true
  session_secret: ""

  local:
    enabled: true
    default_admin_username: "admin"
    default_admin_password: ""

  ldap:
    enabled: true
    url: "ldaps://ipa.example.internal"
    base_dn: "dc=kindred,dc=internal"
    user_search_dn: "cn=users,cn=accounts,dc=kindred,dc=internal"
    user_attr: "uid"
    email_attr: "mail"
    display_attr: "displayName"
    group_attr: "memberOf"
    role_mapping:
      admin:
        - "cn=silo-admins,cn=groups,cn=accounts,dc=kindred,dc=internal"
      editor:
        - "cn=silo-users,cn=groups,cn=accounts,dc=kindred,dc=internal"
        - "cn=engineers,cn=groups,cn=accounts,dc=kindred,dc=internal"
      viewer:
        - "cn=silo-viewers,cn=groups,cn=accounts,dc=kindred,dc=internal"
    tls_skip_verify: false

OIDC / Keycloak

auth:
  enabled: true
  session_secret: ""

  local:
    enabled: true

  oidc:
    enabled: true
    issuer_url: "https://keycloak.example.internal/realms/silo"
    client_id: "silo"
    client_secret: ""  # Set via SILO_OIDC_CLIENT_SECRET
    redirect_url: "https://silo.example.internal/auth/callback"
    scopes: ["openid", "profile", "email"]
    admin_role: "silo-admin"
    editor_role: "silo-editor"
    default_role: "viewer"

CORS (Production)

auth:
  cors:
    allowed_origins:
      - "https://silo.example.internal"

Environment Variables

Variable	Description	Config Path
SILO_SESSION_SECRET	Session encryption key	auth.session_secret
SILO_ADMIN_USERNAME	Default admin username	auth.local.default_admin_username
SILO_ADMIN_PASSWORD	Default admin password	auth.local.default_admin_password
SILO_OIDC_CLIENT_SECRET	OIDC client secret	auth.oidc.client_secret
SILO_LDAP_BIND_PASSWORD	LDAP service account password	auth.ldap.bind_password
SILO_API_URL	API base URL (CLI and FreeCAD)	—
SILO_API_TOKEN	API token (CLI and FreeCAD)	—

Environment variables override config file values.

Troubleshooting

"Authentication required" on every request

• Verify auth.enabled: true in your config
• Check that the sessions table exists in PostgreSQL (migration 009)
• Ensure SILO_SESSION_SECRET is set (empty string is allowed for dev but not recommended)
• Check browser cookies — silo_session should be present after login

API token returns 401

• Tokens are case-sensitive. Ensure no trailing whitespace
• Check token expiry with silo token list
• Verify the user account is still active
• Ensure the Authorization header format is exactly Bearer silo_<hex>

LDAP login fails

• Check ldaps:// URL is reachable from the Silo server
• Verify base_dn and user_search_dn match your FreeIPA tree
• Test with ldapsearch from the command line first
• Set tls_skip_verify: true temporarily to rule out certificate issues
• Check Silo logs for the specific LDAP error message

OIDC redirect loops

• Verify redirect_url matches the Keycloak client configuration exactly
• Check that issuer_url is reachable from the Silo server
• Ensure the Keycloak client has the correct redirect URI registered
• Check for clock skew between Silo and Keycloak servers (JWT validation is time-sensitive)

Locked out (no admin account)

If you've lost access to all admin accounts:

1. Set auth.local.default_admin_password to a new password via SILO_ADMIN_PASSWORD
2. Use a different username (e.g., default_admin_username: "recovery-admin")
3. Restart Silo — the new account will be created
4. Log in and fix the original accounts

Or directly update the database:

-- Reset a local user's password (generate bcrypt hash externally)
UPDATE users SET password_hash = '<bcrypt-hash>', is_active = true WHERE username = 'admin';

FreeCAD plugin gets 401

• Verify the token is set in FreeCAD preferences or SILO_API_TOKEN
• Check the API URL points to the correct server
• Test with curl: curl -H "Authorization: Bearer silo_..." https://silo.example.internal/api/items