Authentication

Control access to the ElasticClaw Server web UI with GitHub OAuth and tag-based ACLs.

Overview

By default, the server web UI uses a single password (ui_password inhub.yaml). For team deployments, you can enable GitHub OAuth and tag-based access control to restrict who can view and interact with agents.

GitHub OAuth

When enabled, users sign in with their GitHub account. ElasticClaw Server validates their identity against allowlists (users, orgs, or teams).

1. Create a GitHub OAuth App

  1. Go to GitHub → Settings → Developer Settings → OAuth Apps → New OAuth App
  2. Authorization callback URL: https://server.example.com/auth/github/callback
  3. Copy the Client ID and generate a Client Secret

2. Configure hub.yaml

yaml
auth:
  github_oauth:
    client_id: Ov23lixxxxxxxxxxxx
    client_secret: ${GITHUB_OAUTH_SECRET}
    allowed_users: []        # specific GitHub logins (empty = any)
    allowed_orgs: []          # org names (empty = any)
    allowed_teams: []         # "org/team" format (empty = any)
  disable_password_auth: false

Allowlist behavior

  • allowed_users — only these specific GitHub logins
  • allowed_orgs — any member of these orgs
  • allowed_teams — any member of these specific teams (format: org/team)
If all three allowlists are empty, any authenticated GitHub user can access ElasticClaw Server. This is the default and a common misconfiguration — populate at least one list before deploying to production.

Tag-based access control

Beyond authentication, you can restrict what authenticated users can dobased on agent tags. This is useful for multi-team setups where different teams manage different agents.

yaml
auth:
  access:
    admins: []                          # GitHub logins — bypass all tag checks
    view_requires_tags: ["frontend"]    # must have at least one matching tag to view
    interact_requires_tags: ["frontend"]
Tag-based access control is enforced by the ElasticClaw Server API and WebSocket paths.view_requires_tags filters agent visibility, andinteract_requires_tags gates chat, terminal, and mutating actions. Admins bypass all tag checks.

Disabling password auth

Once GitHub OAuth is configured and working, you can disable the fallback password login:

yaml
auth:
  disable_password_auth: true
Keep password auth enabled until you've verified OAuth works. If OAuth breaks, you'll be locked out without password fallback.

API endpoints

GET /api/settings — Returns auth config (redacted secrets)

PATCH /api/settings — Update auth config