WordWarden ディレクトリコネクタ

Authrim WordWardenは、LDAPやActive Directoryにユーザーのパスワードを問い合わせるディレクトリコネクタです。ディレクトリの近くで動かし、ログイン画面、アカウントの対応付け、セッション、OIDC・SAMLによる連携はAuthrimが担当します。

パスワードの管理元はLDAP/ADのままです。Authrimは、この認証方式でパスワードやハッシュを保存しません。ログイン時には、入力されたパスワードをAuthrimとWordWardenが受け取り、LDAP/ADに渡して検証します。

接続方式

方式	接続の方向	ディレクトリ側で公開するもの
直接HTTPS	AuthrimからWordWardenへHTTPSで問い合わせます。	通常はリバースプロキシの背後に、到達可能なコネクタのHTTPSエンドポイントを設けます。LDAP/ADは公開しません。
Cloudflare Tunnel	Authrimが公開HTTPSホスト名へアクセスし、cloudflaredの外向きトンネルを通じてWordWardenに届きます。	コネクタのホストで受信用ポートを開ける必要はありませんが、ホスト名を通じてコネクタにアクセスできる状態になります。
Authrim Relay	WordWardenからAuthrimへWebSocketを接続し、その接続で検証依頼を受け取ります。	WordWardenの公開エンドポイントは不要です。Authrimのホストへの外向き通信が必要です。

Authrimの接続方式の設定値は、Tunnelがdirect、Relayがrelayです。どの方式でもコネクタの認証が必要です。トンネルを使っても、HMACやディレクトリとのTLS検証は省略しません。

sequenceDiagram
    participant Browser as ブラウザ
    box transparent Authrim側
        participant Authrim
    end
    box rgba(11,138,138,0.07) 内部環境・社内ネットワーク
        participant WW as WordWarden
        participant LDAP as LDAP / AD
    end
    WW->>Authrim: 外向きWebSocket接続（Relay）
    Authrim->>WW: 有効期限の短い検証値
    WW->>Authrim: HMACによる応答
    Browser->>Authrim: ユーザー名とパスワード
    Authrim->>WW: 認証済み接続で検証依頼
    WW->>LDAP: TLS上で検索とパスワード認証
    LDAP-->>WW: 検証結果と取得を許可された属性
    WW-->>Authrim: 結果、ディレクトリ識別子、選択した属性
    Authrim-->>Browser: アカウントとポリシーを確認してログインを続行

図の枠線は、Authrim側とWordWarden・LDAP/ADを置く内部環境の境界を示します。横幅が足りない場合は図を横にスクロールできます。

WebSocketは外向きに接続を始め、接続後は双方向でメッセージを送れる通信方式です。Relayでは、Authrimがこの接続を使って依頼を送ります。社内ネットワークに向けて新しい受信接続を開くわけではありません。プロキシやファイアウォールでは、WebSocketへの切り替えと長時間の接続を許可する必要があります。

接続相手の確認と返すデータ

直接接続では、AuthrimがPOST /v1/auth/verify-passwordへのリクエストにAUTHRIM-HMAC-SHA256で署名します。WordWardenは署名対象の情報、送信時刻、リクエストの再利用を検出する値であるnonceを検証します。テナントとコネクタの組み合わせも確認します。鍵の設定には現在の鍵を指定するactiveと、切り替え前の鍵を指定するpreviousがあります。切り替え中は旧鍵も受け付けられます。

Relayでは、Authrimが有効期限の短い検証値を送り、WordWardenがHMACで応答します。検証にはnonceと送信時刻も使います。通信のバージョン互換性と、Relay URL内のテナント・コネクタの組み合わせを確認します。検証依頼と応答はリクエストIDで対応付けます。接続相手をHMACで認証し、通信内容はTLSで保護します。

WordWardenが返す属性は、Authrimの要求するattribute_namesと、WordWardenで許可したldap.attributesの両方に含まれるものだけです。グループ検索では所属情報も返せます。アプリケーションのロール、ユーザーの対応付け、最終的に公開する属性はAuthrimで決めます。

ディレクトリ内で同じユーザーを識別し続けるため、変わりにくい属性を使ってください。active_directoryプロファイルの既定値はobjectGUID、openldapはentryUUIDです。バイナリ属性はbase64urlで返します。ディレクトリ内の識別名であるDNは、ユーザーのエントリを移動すると変わる場合があります。汎用ディレクトリでは必要に応じてsubject_attributeを明示します。

導入前に用意するもの

項目	用意する値・確認する内容
設置場所と通信	LDAP/ADへ到達できるホスト。RelayではAuthrimへの外向きWebSocket、直接接続・TunnelではAuthrimから到達できるHTTPS URL。
ディレクトリ接続	LDAP URL、CA証明書、証明書のサーバー名、検索用アカウント、検索開始DN、ユーザー検索条件。
ユーザーの識別	変わりにくい識別属性、許可するユーザー名の形式とドメイン、Authrimへ返す属性。
コネクタ認証	AuthrimとWordWardenで一致するテナントID・コネクタID・鍵ID・秘密値。
常駐と監視	再起動しても残る状態保存先、起動方法、ログの収集先、鍵と証明書の更新担当。

まず社内側からLDAPの検索とパスワード認証を確認し、その後にAuthrimとの通信を確認します。この順序なら、ディレクトリへの接続不良とRelay・HTTPSの接続不良を切り分けられます。

Authrim側の設定

テナントのディレクトリ認証の設定画面でコネクタを登録し、接続方式を選びます。画面名はDirectory Authenticationです。コネクタID、HMACの鍵IDと秘密値への参照、要求する属性、タイムアウトを設定してください。直接接続・TunnelではWordWardenのHTTPSエンドポイントも指定します。Relayでは管理用の秘密値を発行し、一度だけ表示される値をWordWardenのホストに保存します。

Authrimの設定には２種類のIDがあります。idはcampusなどのAuthrim内の設定キー、connector_idはwwcon_8K4M2Q9F7D3H6P1XなどのWordWarden識別子です。Relay URLに入れるのは後者です。URL内のテナントとコネクタはWordWardenの設定と一致させます。

対象テナントのディレクトリパスワード認証も有効にしてください。LDAPでの認証操作をbindと呼びます。bindの成功後、Authrimがアカウントの対応付けとログイン条件を確認してセッションを作ります。未連携ユーザーは、auto_provisionが有効なら管理者承認のために記録できます。承認前はログインできません。

WordWarden側の設定

コネクタのリポジトリにあるconfig.example.yamlから作成します。以下は設定の抜粋です。実行するには、残りの設定も必要です。LDAPの検索条件、ユーザー名の規則、タイムアウト、保護設定はテンプレートから追加してください。

deployment:
  mode: single_tenant
server:
  listen: "127.0.0.1:8080"
  state_dir: "/var/lib/authrim-wordwarden"
tenants:
  - tenant_id: "tenant-a"
    connector_id: "wwcon_8K4M2Q9F7D3H6P1X"
    authrim:
      hmac_keys:
        active:
          kid: "kid_from_authrim"
          secret_ref: "env:AUTHRIM_WORDWARDEN_SECRET_ACTIVE"
      audit_hash_secret_ref: "env:AUTHRIM_WORDWARDEN_AUDIT_HASH_SECRET"
      relay:
        enabled: true
        url: "wss://login.example.com/api/auth/directory-relay/connect/tenant-a/wwcon_8K4M2Q9F7D3H6P1X"
    ldap:
      url: "ldaps://ldap.example.com:636"
      tls:
        verify: true
        server_name: "ldap.example.com"
        ca_file_ref: "file:/etc/authrim-wordwarden/ca/ldap-ca.pem"

秘密値の参照にはenv:NAMEかfile:/absolute/pathを使います。YAMLへ秘密値を直接書かないでください。config validateは参照の書式を検証しますが、値は読みません。server.state_dirには、起動したコネクタを監視画面で識別するためのIDを保存します。再起動しても残る領域を指定してください。現在、設定変更にはプロセスの再起動が必要です。

LDAPには証明書を検証するLDAPS、またはtls.start_tls: trueを指定したldap://を使います。実行時のTLS検証は必須です。検索に使うサービス用アカウントの権限は、選んだ方式で必要な範囲に限定してください。

検索方式	動作
search_then_bind	サービス用アカウントでbindし、base_dn配下から１件のユーザーを検索します。そのDNと入力されたパスワードでbindします。
dn_template	テンプレートからユーザーのDNを組み立ててbindします。属性の取得には必要に応じてサービス用bind・検索設定を使います。
direct_bind	前処理したユーザー名でbindした後、サービス用bindと検索で、指定範囲内のユーザーを１件に絞ります。

検索前に、ユーザー名の形式・ドメイン制限、NFKC正規化、大文字小文字の扱いを適用し、LDAPフィルタの値をエスケープします。メールアドレスを前提にせず、実際のディレクトリに合わせて指定してください。

接続の確認

完全な設定ファイルを用意し、秘密値を参照できる状態でコネクタのホストから実行します。

wordwarden --config /etc/authrim-wordwarden/config.yaml config validate
wordwarden --config /etc/authrim-wordwarden/config.yaml ldap test --tenant tenant-a
wordwarden --config /etc/authrim-wordwarden/config.yaml ldap test --tenant tenant-a --username john --password-stdin
wordwarden --config /etc/authrim-wordwarden/config.yaml doctor

３つ目は標準入力から検証用パスワードを読みます。続いてRelay接続またはHTTPSエンドポイントを確認し、Authrimから正常なアカウント、誤ったパスワード、存在しないユーザー、未連携ユーザーでログインを試します。通常のディレクトリパスワード認証では、使った認証方法としてamr=["pwd","directory"]を記録します。パスキーへの移行などでは、そのフローに応じた認証情報も使います。

検証が通ったら、WordWardenを起動します。常駐サービスやコンテナで運用する場合も、同じ設定ファイルと秘密値への参照を使います。

wordwarden --config /etc/authrim-wordwarden/config.yaml serve

Relayでは、監視画面で接続が認証済みになったことを確認します。直接接続・Tunnelでは、Authrimから使うHTTPS URLへの到達を確認してからログインを試してください。

検証結果にはsuccess、failure、policy_requiredがあります。パスワードの期限切れや変更要求はログイン成功ではありません。ディレクトリの停止、TLSエラー、過負荷、HMAC検証失敗は、パスワードが正しいかどうかの判定と区別します。現在のコネクタには、期限切れパスワードをユーザー自身で解決する一連の操作は用意されていません。

運用と現在の制約

GET /healthzはプロセスが動いているかを確認します。LDAPへの接続確認は行いません。/healthz/detailsと/metricsは、既定では同じホストからのアクセスだけを受け付けます。

コネクタの監視画面であるConnector Fleetでは、インスタンスID、バージョン、接続状態、設定のずれを確認できます。直接接続・Tunnelでは、稼働状況を定期的に送るheartbeatに別の鍵を使います。Relayは接続の認証時に監視用の情報を登録します。

同時実行数とタイムアウトは、LDAP/ADが処理できる範囲に合わせます。WordWardenはリクエストの再送による不正利用と連続した異常を検出します。ただし、再利用を検出する記録は複数のコネクタ間で共有しません。複数台構成は個別に設計してください。鍵は新旧両方を受け付ける期間を設けて切り替え、時計を同期します。パスワードをログに残さず、AuthrimとコネクタのイベントをリクエストIDで照合します。

コネクタのリポジトリでは、現在は公開ベータの準備段階とされています。導入するコネクタとAuthrimのリリース互換性を確認してください。コードに機能があることと、利用環境でその機能が有効になっていることは別です。

関連ドキュメント

• 読み物「パスワードを預けない連携」
• 個人情報の分離

実装の参照先は、Authrimのpackages/ar-auth/src/directory-password-login.ts、directory-password.ts、directory-connector-relay.ts、packages/ar-management/src/routes/directory-connectors.ts、WordWardenのinternal/adapters/ldap/client.go、internal/adapters/hmac/verifier.go、internal/adapters/relay/client.go、docs/configuration.mdです。