Autheliaをローカル環境で実行する

Aug 16, 2025

概要

本記事は、Authelia をローカル環境で実行し、その操作手順や設定方法、発生し得るエラーとその解決策を記録した備忘録です。

対象読者

とりあえず Authelia をローカルで実行してみたい方

環境と前提条件

Authelia の動作環境、および設定ファイルの前提について整理します。

バージョン・設定ファイル

• Authelia コンテナ
  • docker.io/authelia/authelia:latest
• 設定ファイル
  • authelia/config/configuration.yaml
  • compose.yaml

Authelia の起動手順

Authelia をローカル環境で起動するための手順を以下に記載します。

.
├── authelia
│   ├── config
│   │   ├── configuration.yml
│   │   └── users_database.yml # docker compose upで自動生成される
│   └── secrets
│       ├── JWT_SECRET
│       ├── SESSION_SECRET
│       └── STORAGE_ENCRYPTION_KEY
├── compose.yaml
└── README.md

設定ファイルの準備

以下のコードブロックは、Authelia の基本設定例です。

authelia/config/configuration.yaml

# config.template.yaml
# https://github.com/authelia/authelia/blob/master/config.template.yml

log:
  level: debug
  format: json

session:
  # 環境変数でAUTHELIA_SESSION_SECRET_FILEを設定しているためsecretは設定しない
  # secret: 'DO_NOT_EDIT'
  name: 'authelia_session'
  same_site: 'lax'
  inactivity: '5m'
  expiration: '1h'
  remember_me: '1M'
  cookies:
    - domain: '127.0.0.1'
      authelia_url: 'https://127.0.0.1:9091'
      name: 'authelia_session'
      same_site: 'lax'
      inactivity: '5m'
      expiration: '1h'
      remember_me: '1d'


authentication_backend:
  file:
    path: /config/users_database.yml

storage:
  local:
    path: /data/db.sqlite3

notifier:
  filesystem:
    filename: /data/notification.txt

access_control:
  default_policy: one_factor

次に、コンテナ起動用の compose.yaml の例です。

compose.yaml

---
services:
  authelia:
    container_name: 'authelia'
    image: 'docker.io/authelia/authelia:latest'
    restart: 'unless-stopped'
    environment:
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: '/secrets/JWT_SECRET'
      AUTHELIA_SESSION_SECRET_FILE: '/secrets/SESSION_SECRET'
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: '/secrets/STORAGE_ENCRYPTION_KEY'
    volumes:
      - '${PWD}/authelia/config:/config'
      - '${PWD}/authelia/secrets:/secrets'
    ports:
      - '9091:9091'

シークレットファイルの生成

Authelia では CLI を利用して、セキュリティ上必要なランダムな英数字の文字列を生成できます。下記のコマンド例を参考にしてください。

$ docker run --rm authelia/authelia:latest authelia crypto rand --length 64 --charset alphanumeric
Random Value: Gy....ghB

引用： Generating a Random Alphanumeric String

authelia/secrets/JWT_SECRET

Gy....ghB

authelia/secrets/SESSION_SECRET

Gy....ghB

authelia/secrets/STORAGE_ENCRYPTION_KEY

Gy....ghB

Authelia の起動

以下の手順で Authelia を起動します。

• Docker Compose によりコンテナを起動

docker compose up

• Webブラウザで http://127.0.0.1:9091 にアクセス

• 初期ユーザー情報

  • ユーザー名：authelia
  • パスワード：authelia

※ コンテナ起動時に自動生成される users_database.yml により詳細を確認可能です。

authelia/config/users_database.yml

users:
  authelia:
    disabled: false
    displayname: "Test User"
    password: "$argon2id$v=19$m=32768,t=1,p=8$eUhVT1dQa082YVk2VUhDMQ$E8QI4jHbUBt3EdsU1NFDu4Bq5jObKNx7nBKSn1EYQxk"  # Password is 'authelia'
    email: authelia@authelia.com
    groups:
      - admins
      - dev

Authelia の設定解説

Authelia の各種設定項目と設定方法について整理します。

環境変数

Authelia の環境変数には、先頭に AUTHELIA_ の prefix をつける必要があります。

例として、log.level は AUTHELIA_LOG_LEVEL=info で設定可能です。

configuration.yaml

log:
  level: 'info'

参考：Environment - Authelia

シークレット設定

Authelia ではシークレットの設定方法が以下の4通り存在します。

• _FILE が付く環境変数で秘密ファイルを指定
• file filter を使用する方法
  • 例： Template Example
• _FILE 無しの環境変数で直接設定（4.30.0以降）
• configuration.yaml に直接記述

以下の文字が付いている設定項目は、環境変数名の後ろに _FILE の suffix をつけることで、secret file を参照します。

• key
• secret
• password
• token
• certificate_chain

例として、storage.encryption_key は AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE で設定可能です。

configuration.yaml

storage:
  encryption_key: "xxxxxxxxxx"

AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE="secretがあるファイルパス"

ユーザーデータベース設定

ユーザーのパスワードは、以下のコマンドで生成できます。

docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'password'

参考： Passwords - Authelia

ストレージ設定

ローカル環境では、SQLite3 を使用します。

参考資料

• Environment variables - Authelia
• Security Sensitive Values - Authelia
• Why you shouldn’t use ENV variables for secret data

メモ・トラブルシューティング

実際に遭遇したエラー事例とそれぞれの原因および対策を以下にまとめます。

エラーと対策

シークレットエラー

• エラーメッセージ: “Configuration: secrets: error loading secret into key ‘session.secret’: it’s already defined in other configuration sources”
• 原因: compose.yaml で環境変数と configuration.yaml の両方で設定が行われている。
• 対策: configuration.yaml の該当設定を削除し、環境変数で統一する。

Storage オプションの競合

• エラーメッセージ: “Configuration: storage: option ‘local’, ‘mysql’ and ‘postgres’ are mutually exclusive but ‘local’ and ‘postgres’ have been configured”
• 原因: configuration.yaml では local を指定しているが、compose.yaml に AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE が設定されている。
• 対策: 不要な環境変数（例：AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE）を削除する。

Cookie ドメイン不正

• エラーメッセージ: “Configuration: session: domain config #1 (domain ‘localhost’): option ‘domain’ is not a valid cookie domain: must have at least a single period or be an ip address”
• 原因: ドメインが localhost のみ指定されているため、. が含まれていない。
• 対策: cookies.domain に dev.localhost や 127.0.0.1:9091 などを設定する。

その他の注意点

• ログイン後、authelia_session が Cookie に設定される。
• NTP サーバーとの時刻同期エラーについては Understanding what this error means #6865 を参照。
• default_redirection_url は、ユーザーがターゲット URL を指定しなかった場合のリダイレクト先として設定。

Tags:

• Authelia

Authelia と Next.js (Auth.js) による OIDC 認証連携ガイド

GitHub Actions と Terraform で構築する ECR + Lambda コンテナデプロイ環境