Phase 1 authentik連携実践マニュアル（Headscale／Samba編）

本ページの位置づけについて

ロードマップ上の「Phase 1：ハイブリッドストレージ＆ゼロトラスト認証・認可（RBAC）」完成条件（DoD）は、authentikグループとNextcloud/Samba ACLの自動同期、MFA強制、ブラウザ共同編集までを含みます。本ページで実施したのは、その一部である「特定ユーザー（利用者A）がHeadscale VPN経由でauthentik認証（TOTP多要素認証を含む）を使い、Samba private共有にアクセスできる」という個別要件の実現までです。authentikグループとACLの自動同期・Nextcloud統合は未実施のため、Phase 1全体としては「一部進展」の状態です。

authentikとは（超入門）
今回構築した全体像
STEP 1：authentikでOIDCプロバイダーを作成
STEP 2：アプリケーション作成とユーザー作成
STEP 3：Headscale側の設定変更
トラブル①：NATループバックによるOIDC初期化失敗
STEP 4：Samba側に利用者Aユーザーを恒久作成
STEP 5：動作確認（DoDエビデンス）
利用者Aさん側の利用手順
TOTP多要素認証（MFA）の設定手順
実地接続テストで発覚した5つの追加課題
最終DoDエビデンス（外部端末より）
未実施項目と次ステップ

1. authentikとは（超入門）

authentikは、複数のアプリ（Nextcloud、Grafana、Headscaleなど）へのログインを1か所に集約する「認証・認可の職員室」のようなソフトです。ユーザーはauthentikに1回ログインするだけで、許可されたアプリにパスワード入力なしでアクセスできます。管理者はユーザーの追加・削除をauthentik側で一元管理できます。

用語	身近な例え	今回の役割
プロバイダー（Provider）	アプリと会話するための「通訳さん」	Headscale用の「OAuth2/OpenID Provider」を作成
Redirect URI	ログイン成功後に戻ってくる住所	`https://hs.example.com/oidc/callback`
Client ID / Client Secret	ホテルの予約番号／暗証番号	Headscaleの`config.yaml`に設定
アプリケーション（Application）	ユーザー画面に並ぶアイコン	「Headscale」という名前で作成

より詳しい用語解説は、社内資料「authentik超入門取扱説明書」を参照。

2. 今回構築した全体像

利用者A さんの端末（外部）
   │ ① Tailscaleクライアントで Headscale (hs.example.com) に接続要求
   │    → ブラウザが開き authentik のログイン画面へリダイレクト（OIDC）
   │ ② 利用者A / パスワード で authentik にログイン
   ▼
Headscale が VPN 参加を許可（100.64.0.0/10 の仮想IPを割当）
   │
   ▼
192.168.2.3（AlmaLinux 9）へ LAN 内同等到達
   │ ③ Windowsエクスプローラーで \\192.168.2.3\private を開く
   │    （Samba独自認証：利用者A / パスワード）
   ▼
private 共有（ファイル操作）

FortiGateのインバウンドポート（445等）は一切開放していない。SMBを外部に直接晒さない、ロードマップPhase 3（ZTNA）の考え方に沿った構成。

3. STEP 1：authentikでOIDCプロバイダーを作成

https://auth.example.com の管理画面で、Applications ＞ Providers ＞ Create から OAuth2/OpenID Provider を作成した。

項目	設定値
Name	`headscale-provider`
Client Type	コンフィデンシャル
Redirect URI	`https://hs.example.com/oidc/callback`（厳密）
認可フロー	`default-provider-authorization-implicit-consent`
認証フロー	`default-authentication-flow`
無効化フロー	`default-invalidation-flow`

つまずきポイント：「認可フロー」が未選択だとエラーになる

新しいアプリ作成ウィザードでは「アプリ→プロバイダーの種類→プロバイダー設定→バインディング→確認」の順に進むが、プロバイダー設定画面の一番上にある「認可フロー（Authorization flow）」を選ばずに送信すると「プロバイダーにエラーがあります」という汎用エラーになる。よく似た名前の「認証フロー（Authentication flow）」とは別項目なので要注意。

4. STEP 2：アプリケーション作成とユーザー作成

Applications ＞ Applications ＞ Create で、Name: Headscale、Slug: headscale、Provider: headscale-provider を割り当てて作成。
Directory ＞ Users ＞ Create で、ユーザー名 利用者A を作成。

作成後に確認できる値（Provider詳細画面）

OpenID構成の発行者（Issuer）:
https://auth.example.com/application/o/headscale/

Client ID:
<発行されたClient ID>

Client Secretは「関連アクション」内の「編集」画面でのみ確認できる（一覧・概要画面には表示されない）。

5. STEP 3：Headscale側の設定変更

AlmaLinux 9（192.168.2.3）の /srv/containers/headscale/config/config.yaml を編集。

# 修正前（未修正のプレースホルダが残っていた）
server_url: https://hs.yourdomain.example

# 修正後
server_url: https://hs.example.com

# 追加（authentik OIDC連携）
oidc:
  issuer: "https://auth.example.com/application/o/headscale/"
  client_id: "<headscale-providerのClient ID>"
  client_secret: "<headscale-providerのClient Secret>"
  scope: ["openid", "profile", "email"]

sudo systemctl daemon-reload
sudo systemctl restart headscale

6. トラブル①：NATループバックによるOIDC初期化失敗

発生した事象

Could not retrieve OIDC Config: Get "https://auth.example.com/.../.well-known/openid-configuration": dial tcp <自宅の公開グローバルIP>:443: i/o timeout
Headscaleがこのエラーで初期化に失敗し、再起動を繰り返すクラッシュループに陥った。

原因

コンテナがauth.example.comを名前解決すると、自宅の公開グローバルIP（<自宅の公開グローバルIP>）に折り返され（NATヘアピン／ループバック）、FortiGateがこの折り返し通信を正しく戻せず接続がタイムアウトしていた。authentikコンテナ自身は同様の理由から DNS=<内部DNSサーバのIP>（内部Unbound）を明示指定することで既に回避していたが、Headscale側には同じ対策が入っていなかった。

対応

事前に、AlmaLinuxからDMZのCaddy（<DMZリバースプロキシのIP>）へ直接到達できることを確認：

curl -sk --resolve auth.example.com:443:<DMZリバースプロキシのIP> https://auth.example.com/ --max-time 8
# → HTTP_CODE:302（到達OK）

Unbound（/srv/containers/identity/unbound/unbound.conf）にSplit-DNSを追加し、内部から問い合わせた場合のみ内部IPを返すよう設定：

local-zone: "example.com." transparent
local-data: "auth.example.com. IN A <DMZリバースプロキシのIP>"
local-data: "hs.example.com. IN A <DMZリバースプロキシのIP>"

/etc/containers/systemd/headscale-pod.pod に、authentik-pod.podと同じ方式で DNS=<内部DNSサーバのIP> を追加し、daemon-reload・restart headscaleを実施。以後1分40秒以上安定稼働し、OIDCエラーが解消したことを確認した。

7. STEP 4：Samba側に利用者Aユーザーを恒久作成

Phase 1 Samba基盤構築マニュアルで既知の課題として記録されていた「smbuserのパスワードがコンテナ再作成で消える」問題を踏襲しないよう、Quadletの起動引数でユーザーを自動投入する方式を採用した。

# /etc/containers/systemd/samba.container の [Container] セクションに追記
Exec=-u "利用者A;<利用者Aさんのパスワード>"

# /srv/containers/samba/smb.conf の [private] セクションを更新
[private]
   valid users = smbuser 利用者A   # 既存smbuserは維持し、利用者Aを追加

sudo systemctl daemon-reload
sudo systemctl restart samba

8. STEP 5：動作確認（DoDエビデンス）

Headscale：OIDC修正後の安定稼働

Active: active (running) since 2026-08-06 12:04:02 JST; 1min 40s以上
（journalctlにOIDC関連エラーなし、再起動なし）

Samba：利用者Aユーザーでのログイン確認

$ sudo podman exec samba-server smbclient -L localhost -U 利用者A%<パスワード> -m SMB3

        Sharename       Type      Comment
        ---------       ----      -------
        public          Disk      Public Shared Directory
        private         Disk      Private Shared Directory
        IPC$            IPC       IPC Service (Home Server Samba)

authentikにOIDCプロバイダー・アプリケーション・利用者Aユーザーを作成完了
HeadscaleがauthentikのOIDC設定を正常に読み込み、安定稼働完了
Sambaの利用者Aユーザーがコンテナ再作成後も消えない形で恒久化完了
利用者AユーザーでのSamba private共有ログイン完了
利用者Aさん自身の端末からのTailscale接続・実地確認完了（詳細は10章参照）

9. 利用者Aさん側の利用手順（確定版）

Tailscale公式クライアント（Windows版）をインストール（tailscale.com/download/windows）
コマンドプロンプトで接続（--accept-routesが必須。無いと自宅LANへの経路を受け取れない）：
```
tailscale up --login-server=https://hs.example.com --accept-routes
```
ブラウザが自動で開かない場合は、表示された認証用URLを手動でブラウザに貼り付ける。
開いたブラウザのauthentikログイン画面で、利用者Aのユーザー名・パスワードを入力し、続けてスマートフォンの認証アプリに表示される6桁のTOTPコードを入力する（MFA設定手順は次章参照）
接続確認：
```
tailscale status
ping 192.168.2.3
```
Samba共有への接続はコマンドで明示的に行うことを推奨（エクスプローラー直打ちだと認証情報のキャッシュが崩れ再入力を求められないことがあるため）：
```
net use \\192.168.2.3\private /user:利用者A <パスワード>
```
接続済みの状態を一度クリアしたい場合は net use \\192.168.2.3\private /delete を先に実行する。

10. TOTP多要素認証（MFA）の設定手順

当初はパスワードのみでログイン可能な構成だったが、後日TOTP（Time-based One-Time Password）による多要素認証を追加した。設定はauthentik側の確認と、利用者本人によるデバイス登録の2段階に分かれる。

10-1. authentik側：MFA検証ステージが認証フローに含まれているか確認

authentikの既定の認証フロー（default-authentication-flow）には、通常あらかじめMFA検証ステージ（default-authentication-mfa-validation）が組み込まれている。これは「ユーザーがMFAデバイスを登録済みなら要求し、未登録なら素通りさせる」という条件付きの挙動のため、ステージ自体は追加設定なしで機能する。管理画面のFlows & Stages ＞ Flows ＞該当の認証フローを開き、「Stage Bindings」タブにこのステージが含まれていることだけ確認しておく。

10-2. 利用者本人：TOTPデバイスを登録する

スマートフォンに認証アプリ（Google Authenticator、Microsoft Authenticator等）をインストールする
authentikにログインし、右上のアバターから「ユーザー設定」を開く
左メニューの「認証情報」＞「MFAデバイス」を開き、「登録」ボタンから「TOTP」を選択
表示されたQRコードを、スマートフォンの認証アプリのカメラで読み取る
アプリに表示された6桁のコードを入力して登録を確定する
MFAデバイス一覧に、登録した「TOTP Authenticator」が表示されていれば完了

QRコードは一度しか表示されないことが多い

登録画面を離れると同じQRコードは再表示できないことがほとんど。その場で確実に認証アプリへ読み取らせること。

10-3. ログイン時の実際の見え方

登録後、次回ログイン時はユーザー名・パスワードに続けて「認証コード」の入力画面が表示され、認証アプリの6桁コードを入力して初めてログインが完了する。

認証コード入力画面が出てこない場合

ブラウザに既にauthentikへのログイン済みセッションが残っていると、パスワード入力もMFAもスキップされてそのままログインが完了する（SSO）ことがある。動作確認の際は、一度authentikからログアウトしてブラウザタブを閉じてから接続をやり直すか、シークレット/InPrivateウィンドウを使うと切り分けやすい。またTOTPコードには有効時間があるため、表示されてから間を置かず入力すること。

11. 実地接続テストで発覚した5つの追加課題

ここまでの設定でLAN内の動作確認は完了していたが、実際に利用者Aさんの端末（別PC）から接続してみたところ、「VPNに繋がる」ことと「自宅LANに実際に到達できる」ことは別の設定が必要だと判明した。以下、発生順に記録する。

11-1. Headscareアプリのアクセス制限がインフラ機器の登録もブロック

発生した事象

Headscaleアプリケーションへのアクセスを利用者Aだけに制限するバインディングを追加した直後、サーバー機器（後述のサブネットルーター）を管理者アカウントで認証しようとしたところ、ログインはできてもアプリの認可画面に進まずダッシュボードに戻されてしまった。

対応

管理者アカウントも同じバインディングに追加して解消。教訓：Headscaleに新しいノード（サーバー機器等）を追加する際は、その認証に使うアカウントも事前にアプリのバインディング対象に加えておく必要がある。

11-2. サブネットルーターの欠如（最大の見落とし）

発生した事象

利用者Aさんの端末はHeadscaleに認証され仮想IPも割り当てられたが、自宅LAN（192.168.2.0/24）へのpingが一切通らなかった。

原因

「VPNに認証されて参加する」ことと「LANへの経路が広告されている」ことは別物。AlmaLinuxサーバー自身にTailscaleクライアントが入っておらず、LANへの経路を広告する「サブネットルーター」役のノードが存在しなかった。

対応

curl -fsSL https://tailscale.com/install.sh | sh
echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf
sudo sysctl -p /etc/sysctl.d/99-tailscale.conf
sudo tailscale up --login-server=https://hs.example.com --advertise-routes=192.168.2.0/24 --accept-routes

認証後、Headscale側で経路の有効化が別途必要：

sudo podman exec headscale headscale routes list
sudo podman exec headscale headscale routes enable -r <ID>

11-3. firewalldでtailscale0インターフェースが未所属

原因

tailscale0インターフェースがfirewalldのどのゾーンにも属しておらず、既存のpublicゾーンで許可していた転送（forward）やSamba関連ポートの許可が適用されていなかった。

対応

sudo firewall-cmd --zone=public --add-interface=tailscale0 --permanent
sudo firewall-cmd --reload

11-4. DERPリレーサーバーが完全に未設定

発生した事象

tailscale netcheckで確認したところ、直接P2P接続ができない環境同士（外出先↔自宅）を中継する仕組みが一切存在しないことが判明した。

対応

自前でDERPサーバーを構築する必要はなく、Tailscale公式が無料公開しているDERPマップを参照するだけで解消した。

derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default

11-5. Headscale ACLポリシーファイルの不在

原因

設定ファイルが参照するACL(アクセス制御)ポリシーファイルが存在しなかった。Headscaleは既定で「別ユーザーのノード同士は互いに見えない」仕様のため、利用者Aさんの端末とサブネットルーター（認証に使ったアカウントが異なる）が別ユーザー扱いとなり、tailscale statusにお互いが一切表示されていなかった。

対応

sudo tee /srv/containers/headscale/config/acl.hujson > /dev/null << 'EOF'
{
  "acls": [
    { "action": "accept", "src": ["*"], "dst": ["*:*"] }
  ]
}
EOF
sudo systemctl restart headscale

注意

これは全ノード間を無条件許可する最も単純なACLです。利用者・機器が増える場合は、より細かい制限への見直しを推奨します。

11-6. SambaのファイルレベルでUID/GID不一致（Access Denied）

発生した事象

Samba認証（net use）自体は成功するが、dirコマンドで「アクセスが拒否されました」となった。Phase 1 Samba基盤構築マニュアルに記録済みの「ファイル所有者の不一致」問題と同種で、今回は新規追加した利用者Aアカウントで再発した。

原因

privateフォルダの所有者はUID100/GID101（770権限）だが、コンテナ内の利用者AアカウントはUID/GID 1000で作成されていた（sudo podman exec samba-server id 利用者Aで確認）。

対応

既存ユーザーの権限には触れず、ACLで個別に権限を追加した。

sudo setfacl -R -m u:1000:rwx /srv/samba/private
sudo setfacl -R -d -m u:1000:rwx /srv/samba/private

12. 最終DoDエビデンス（外部端末より）

上記5つの課題をすべて解消後、利用者Aさんの実機（外部の別PC）から、書込・読込・削除を含む完全な動作確認を実施した。

> tailscale status
100.64.0.1 desktop-xxxxxxx          windows -
100.64.0.2 localhost    <サブネットルーターのユーザー名> linux  -

> ping 192.168.2.3
192.168.2.3 からの応答: バイト数=32 時間=59～188ms TTL=64（4/4送信成功、0%ロス）

> net use \\192.168.2.3\private /user:利用者A <パスワード>
コマンドは正常に終了しました。

> dir \\192.168.2.3\private
（正常にディレクトリ一覧を表示）

> echo test > \\192.168.2.3\private\test.txt
> type \\192.168.2.3\private\test.txt
test
> del \\192.168.2.3\private\test.txt
（書込・読込・削除いずれもエラーなし）

利用者Aさんの外部端末からの、書込・読込・削除を含む完全な動作確認が完了した。

authentik ⇔ Headscale ⇔ Samba 連携・外部端末からの完全動作確認達成 🎉

authentikのOIDCプロバイダー構築から、Headscaleとの連携、NATループバック問題の解消、Samba 利用者Aユーザーの恒久化、そして実際の外部端末からのVPN接続・自宅LANアクセス・ファイル書込読込削除までを実機で完了しました。全体ロードマップは「ゼロトラスト統合基盤検証ロードマップ」を、Samba基盤の土台は「Phase 1 Samba基盤構築マニュアル」をご参照ください。

13. 未実施項目と次ステップ

ロードマップ上のPhase 1完成条件（DoD）と比較した、現時点での未実施項目です。今回のセッションで、利用者Aさんのauthentikパスワード設定・アクセス制限・実地接続確認はすべて完了しました。

Headscareアプリの認証フローにTOTP多要素認証（MFA）を設定し、外部端末からのログインで実地確認完了（2026年8月11日）

authentikグループとSamba ACL／Nextcloudグループフォルダの自動同期未実施
Passkey（WebAuthn）対応とNextcloud/OnlyOfficeでのブラウザ共同編集未実施
public共有のWindowsゲストアクセスブロック問題への対応方針決定（Phase1 Samba基盤構築マニュアルより継続）未実施
Headscale ACLが「全ノード間無条件許可」の簡易設定のまま。利用者・機器が増える場合は見直しが必要未実施
サブネットルーター（AlmaLinux上のTailscaleクライアント）の認証が管理者個人アカウントに紐づいている。専用のサービスアカウント化を検討の余地あり未実施

authentikグループとACL/Nextcloudの自動同期（ロードマップPhase 1のフルDoD）が、次の主要な未実施項目である。

本ページの位置づけについて

目次

1. authentikとは（超入門）

2. 今回構築した全体像

3. STEP 1：authentikでOIDCプロバイダーを作成

つまずきポイント：「認可フロー」が未選択だとエラーになる

4. STEP 2：アプリケーション作成とユーザー作成

5. STEP 3：Headscale側の設定変更

6. トラブル①：NATループバックによるOIDC初期化失敗

7. STEP 4：Samba側に利用者Aユーザーを恒久作成

8. STEP 5：動作確認（DoDエビデンス）

9. 利用者Aさん側の利用手順（確定版）

10. TOTP多要素認証（MFA）の設定手順

10-1. authentik側：MFA検証ステージが認証フローに含まれているか確認

10-2. 利用者本人：TOTPデバイスを登録する

QRコードは一度しか表示されないことが多い

10-3. ログイン時の実際の見え方

認証コード入力画面が出てこない場合

11. 実地接続テストで発覚した5つの追加課題

11-1. Headscareアプリのアクセス制限がインフラ機器の登録もブロック

11-2. サブネットルーターの欠如（最大の見落とし）

11-3. firewalldでtailscale0インターフェースが未所属

11-4. DERPリレーサーバーが完全に未設定

11-5. Headscale ACLポリシーファイルの不在

注意

11-6. SambaのファイルレベルでUID/GID不一致（Access Denied）

12. 最終DoDエビデンス（外部端末より）

authentik ⇔ Headscale ⇔ Samba 連携・外部端末からの完全動作確認達成 🎉

13. 未実施項目と次ステップ