ja:auth:mysql

MySQL 認証バックエンド

ユーザーデータやバスワードの格納に MySQL データベースを使います。MySQL 認証バックエンドは DokuWiki本体に inc/auth/myphp.class.php として組み込まれています。

release 2006-03-09以降のバージョンには、この認証バックエンドの設定を含むひな形ファイル conf/mysql.conf.php.example が同梱されています。

DokuWikiはデータベースを使用しなくとも使えるのが特徴の一つです。しかし、ユーザー認証にデータベースを使うこともできます。既存のシステムとユーザー管理を統合させたり、複数のDokuWikiをファーム化して運用する場合にユーザー管理を一元化するなどといった場合には、有効な手段となるでしょう。

データベースの例

conf/mysql.conf.php.example では、users、groups、usergroup というの３つのテーブルを格納したデータベースを前提として、これらのテーブルを操作するSQL文があらかじめ設定されています。 conf/users.auth.php の fullname フィールドに相当するデータが、usersテーブルでは firstname と lastname の二つのフィールドに分かれている点に注意してください。

sample.sql

/* 
   Example Database -- An improved version
*/
CREATE TABLE `users` (
  `uid` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `login` VARCHAR(20) NOT NULL DEFAULT '',
  `pass` VARCHAR(60) NOT NULL DEFAULT '',
  `firstname` VARCHAR(255) NOT NULL DEFAULT '',
  `lastname` VARCHAR(255) NOT NULL DEFAULT '',
  `email` VARCHAR(255) NOT NULL DEFAULT '',
  PRIMARY KEY  (`uid`),
  UNIQUE KEY `login` (`login`)
) ENGINE = MyISAM;
 
CREATE TABLE `groups` (
  `gid` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `name` VARCHAR(50) NOT NULL DEFAULT '',
  PRIMARY KEY  (`gid`),
  UNIQUE KEY `name` (`name`)
) ENGINE = MyISAM;
 
CREATE TABLE `usergroup` (
  `uid` INT(10) UNSIGNED NOT NULL DEFAULT '0',
  `gid` INT(10) UNSIGNED NOT NULL DEFAULT '0',
  PRIMARY KEY  (`uid`,`gid`)
) ENGINE = MyISAM;

ユーザーとグループを管理する基本的な情報を備えたデータベースであれば、その情報をDokuWikiのユーザ認証とACL制御に活用できるでしょう。ただし、そのデータベースの構造にあわせて、必要な情報を取り出すためのSQL文をカスタマイズする必要があります。柔軟に対処できることから、多くのシステムと組み合わせを図った実例を後のセクションで紹介しています。

設定

conf/mysql.conf.php.example をコピーして、mysql.conf.phpを作成します。

次に conf/local.protected.php （ファイルがない場合は作成する）に次のように追記します。conf/local.php に追記すると、管理画面の操作によって local.php ファイルが上書きされて設定が失われてしまいます。

  <?php
      require_once('mysql.conf.php');

mysql.conf.php の設定

あらかじめMySQL上に用意したデータベースとの接続に必要な設定を行います。

$conf['auth']['mysql']['server'] = 'localhost';     // データベースのホスト
$conf['auth']['mysql']['user'] = 'dbuser';          // 接続に用いるユーザ名
$conf['auth']['mysql']['password'] = 'dbpassword';  // 上記ユーザのバスワード
$conf['auth']['mysql']['database'] = 'dokuwiki';    // データベースの名前

このほかに、以下のような設定項目があります。

Option 'forwardClearPass'

通常、パスワードの暗号化はDokuWiki側で行います（推奨）が、データベース側で暗号化するほうが都合が良い場合もあるでしょう。DokuWiki側でパスワードを暗号化してデータベースに格納する運用とする場合には、'forwardClearPass' を '0' に設定します（推奨）。この場合、DokuWiki は passcrypt で設定した方法でパスワードを暗号化し、それをデータベースに渡します。

'forwardClearPass' を 1 に設定すると、データベースには平文パスワードが渡されます。データベースサーバとの通信におけるセキュリティに注意が必要です。

$conf['auth']['mysql']['forwardClearPass'] = 0;

Option 'TablesToLock'

データベース内の複数テーブルが同時に更新されることを防止するため、テーブルをロックして排他制御が行われます。TablesToLockパラメータには、ロックするテーブルの名前を配列で設定します。テーブルに別名（エイリアス）をして使用する場合、それらの別名も設定する必要があります。このパラメータに設定していない別名を用いたテーブル操作が発生した場合には、警告メッセージの対象となります。

$conf['auth']['mysql']['TablesToLock']= array("users", "users AS u",
              "groups", "groups AS g", "usergroup", "usergroup AS ug");

Option 'debug'

このオプションを 1 に設定すると、認証パックエンドで発生した SQL エラーが画面表示されます。2 に設定すると、データベースに送信された SQL文も画面表示されます。これらの情報はデバック時には有効ですが、通常の運用では 0 に設定しましょう。

$conf['auth']['mysql']['debug']= 0;

MySQL認証を有効にする

mysql.conf.php を設定したら、管理画面にて authtype の設定を mysql に変更します。手動で変更する場合には、conf/local.php に次のように設定します。

$conf['authtype'] = "mysql";

注意

この時点でデータベースにはまだ adminユーザーが登録されていない点に注意してください。
管理画面で authtype を mysql に変更して設定を保存した後、ただちにユーザー管理画面を開き、admin 権限をもつユーザを作成しましょう。そうしないと、後で管理画面にアクセスできなくなってしまいます。
もし管理画面にアクセスできなくなった場合には、conf/local.php を手動で書き換えましょう（$conf['authtype'] = “plain” に戻す）。

SQL statements in mysql.conf.php

mysql.conf.php では、MySQL認証バックエンドモジュール（inc/auth/mysql.class.php）に対応する形で、実際に用いるデータベースから必要な情報を抽出するSQL文を定義します。

データベースの検索条件などを指定するために、次の変数を使用します。

変数	意味
%{user}	ユーザー名（user name）
%{pass}	ユーザーのパスワード（'forwardClearPass'の設定により、暗号または平文）
%{dgroup}	管理画面で設定した「既定のグループ」の名前（defaultgroup ）
%{name}	ユーザーの氏名（fullname）
%{mail}	ユーザーのメールアドレス（email address）
%{group}	グループ名
%{uid}	ユーザーの識別にデータベースのテーブルで使用されているID
%{gid}	グループの識別にデータベースのテーブルで使用されているID

mysql.conf.php内で定義するSQL文は複数ありますが、次の5カテゴリに整理されます。ユーザー管理の機能を DokuWiki側（＝usermanager プラグイン）でどこまで行うかによって、用意すべきSQL文のカテゴリ範囲が異なります。

SQL User Authentication – DokuWiki本体でのユーザー認証に必須となるもの
SQL Basic User Manager Support – ユーザーマネージャープラグインでユーザの表示だけを行う場合に必要
SQL Support for Add User – ユーザーマネージャープラグインでユーザの追加（作成）を行う場合に必要
SQL Support for Delete User – ユーザーマネージャープラグインでユーザの削除を行う場合に必要
SQL Support for Modify User – ユーザーマネージャープラグインでユーザの編集を行う場合に必要

以下のセクションでは、同梱されている /conf/mysql.conf.php.example に設定されているSQL文を紹介します。

SQL User Authentication

このセクションでは、DokuWikiで MySQL認証バックエンドを利用するのに必須となる SQL文について説明します。

checkPass

このSQL文は、Wikiに対するアクセスを許可または拒否するかの判別に使われます。ユーザー認証で使用するために、指定したユーザのパスワードをデータベースから取り出します。検索結果は、少なくともユーザーのパスワードを含む1行のテーブルでなければなりません。結果が空または複数行となった場合には、アクセスは拒否されます。

'forwardClearPass' を 1 に設定している場合には、このSQL文でパスワードが合致するかを確かめる必要があります。この場合、例えばSQL文のWHERE句に “AND pass = MD5('%{pass}')” を追加する方法があります。ただし、'forwardClearPass' を 0 と設定して運用する方が無難です。

$conf['auth']['mysql']['checkPass']   = "SELECT pass
                                         FROM usergroup AS ug
                                         JOIN users AS u ON u.uid=ug.uid
                                         JOIN groups AS g ON g.gid=ug.gid
                                         WHERE login='%{user}'
                                         AND name='%{dgroup}'";

上記のSQL文のWHERE句には “AND name='%{dgroup}'” という条件が含まれています。これは「既定のグループに属していないユーザは、たとえデータベースに登録されていても DokuWikiへのアクセスを拒否する」ことを意図したものです。ユーザ情報を含むデータベースを他のアプリケーションと共用している場合を念頭においたものです。実際のDokuWikiの運用にあわせて変更する必要があるでしょう。

例えば、「どのグループにも属していないユーザはアクセスを拒否する」場合には、WHERE句を次のようにします。

                                         WHERE login='%{user}' AND name<>''

getUserInfo

このSQL文は、指定したユーザに関する情報を取得するために使用されます。検索結果は、パスワード、氏名、メールアドレスの順に並んだ1行のテーブルでなければなりません。

$conf['auth']['mysql']['getUserInfo'] = "SELECT pass, CONCAT(firstname,' ',lastname) AS name, email AS mail
                                         FROM users
                                         WHERE login='%{user}'";

getGroups

このSQL文は、指定したユーザが属する全てのグループ名を取得するために使用されます。検索結果は、複数行のテーブルとなっても構いません。

$conf['auth']['mysql']['getGroups']   = "SELECT name AS `group`
                                         FROM groups g, users u, usergroup ug
                                         WHERE u.uid = ug.uid
                                         AND g.gid = ug.gid
                                         AND u.login='%{user}'";

SQL Basic User Manager Support

このセクションでは、ユーザーマネージャープラグインでユーザの表示（一覧）だけを行う場合に必要な SQL文を取り上げます。
（ユーザーマネージャープラグインを使用しない場合には、これらは不要です。）

getUsers

このSQL文は、ユーザー管理画面において、検索フィルターで設定した条件を満たす全てのユーザーを列挙するために使用されます。

検索フィルターに条件が指定されている場合には、FilterLogin, FilterName, FilterEmail, FilterGroup のうち該当するパラメータの設定がWHERE句として追加されます。さらに、末尾にソート条件が追加されます。

検索結果のテーブルには、ユーザ名が重複しない（一回だけ出現する）ようにしなければなりません。

$conf['auth']['mysql']['getUsers']    = "SELECT DISTINCT login AS user
                                         FROM users AS u
                                         LEFT JOIN usergroup AS ug ON u.uid=ug.uid
                                         LEFT JOIN groups AS g ON ug.gid=g.gid";
$conf['auth']['mysql']['FilterLogin'] = "login LIKE '%{user}'";
$conf['auth']['mysql']['FilterName']  = "CONCAT(firstname,' ',lastname) LIKE '%{name}'";
$conf['auth']['mysql']['FilterEmail'] = "email LIKE '%{email}'";
$conf['auth']['mysql']['FilterGroup'] = "name LIKE '%{group}'";
$conf['auth']['mysql']['SortOrder']   = "ORDER BY login";

SQL Support for Add User

このセクションでは、ユーザマネージャープラグインを使って新規ユーザの登録を行う場合に必要となるSQL文を説明します。
（データベースのデータ操作をDokuWiki以外のアプリケーションで行う場合には、これらは不要です。）

addUser

このSQL文は、新たなユーザを作成するために使用されます。

'forwardClearPass' を 1 に設定している場合、データベースにはパスワードが平文で格納されることに注意して下さい。データベース側でパスワードを暗号化するには、'%{pass}' を MD5('%{pass}') と書き換えます。

'forwardClearPass' を 0 に設定している（推奨）なら、DokuWiki 側でパスワードを暗号化した結果がデータベースに格納されます。この方法を使用するのが無難です。

$conf['auth']['mysql']['addUser']     = "INSERT INTO users
                                         (login, pass, email, firstname, lastname)
                                         VALUES ('%{user}', '%{pass}', '%{email}',
                                         SUBSTRING_INDEX('%{name}',' ', 1),
                                         SUBSTRING_INDEX('%{name}',' ', -1))";

ユーザ作成画面（ユーザマネージャー）の氏名欄（fullname）に入力した文字列は、空白文字の前半と後半に分けて、それぞれ firstname とlastname のフィールドに格納されます。lastnameを空にしたい場合には、氏名欄への入力文字列の末尾に空白文字を追加します。

addGroup

このSQL文は、新たなグループを作成するために使用されます。

$conf['auth']['mysql']['addGroup']    = "INSERT INTO groups (name)
                                         VALUES ('%{group}')";

addUserGroup

このSQL文は、ユーザをグループのメンバーとするために使用されます。ユーザの識別にはユーザIDを、グループの識別にはグループIDを使用します。

$conf['auth']['mysql']['addUserGroup']= "INSERT INTO usergroup (uid, gid)
                                         VALUES ('%{uid}', '%{gid}')";

delGroup

このSQL文は、指定したグループIDをもつグループを削除するために使用されます。

$conf['auth']['mysql']['delGroup']    = "DELETE FROM groups
                                         WHERE gid='%{gid}'";

getUserID

このSQL文は、指定したユーザ名のユーザIDを取得するために使用されます。

'%{user}' will be replaced by the user name

$conf['auth']['mysql']['getUserID']   = "SELECT uid AS id
                                         FROM users
                                         WHERE login='%{user}'";

getGroupID

このSQL文は、指定したグループ名のグループIDを取得するために使用されます。

$conf['auth']['mysql']['getGroupID']  = "SELECT gid AS id
                                         FROM groups
                                         WHERE name='%{group}'";

SQL Support for Delete User

このセクションでは、ユーザマネージャープラグインを使ってユーザの削除を行う場合に必要となるSQL文を説明します。
（データベースのデータ操作をDokuWiki以外のアプリケーションで行う場合には、これらは不要です。）

delUser

このSQL文は、ユーザをデータベースから削除するために使用されます。ユーザの識別にはユーザIDを使用します。

$conf['auth']['mysql']['delUser']     = "DELETE FROM users
                                         WHERE uid='%{uid}'";

delUserRefs

このSQL文は、指定したユーザをその所属グルーブ全てから外すために使用されます。ユーザの識別にはユーザIDを使用します。

$conf['auth']['mysql']['delUserRefs'] = "DELETE FROM usergroup
                                         WHERE uid='%{uid}'";

SQL Support for Modify User

このセクションでは、ユーザマネージャープラグインを使ってユーザ情報の変更を行う場合に必要となるSQL文を説明します。
（データベースのデータ操作をDokuWiki以外のアプリケーションで行う場合には、これらは不要です。）

updateUser

このSQL文は、データベースのユーザエントリを修正するために使用されます。修正する項目に応じて、UpdateLogin, UpdatePass, UpdateEmail, UpdateName のうち必要なものだけが updateUser に追加されます。

$conf['auth']['mysql']['updateUser']  = "UPDATE users SET";
$conf['auth']['mysql']['UpdateLogin'] = "login='%{user}'";
$conf['auth']['mysql']['UpdatePass']  = "pass='%{pass}'";
$conf['auth']['mysql']['UpdateEmail'] = "email='%{email}'";
$conf['auth']['mysql']['UpdateName']  = "firstname=SUBSTRING_INDEX('%{name}',' ', 1),
                                         lastname=SUBSTRING_INDEX('%{name}',' ', -1)";
$conf['auth']['mysql']['UpdateTarget']= "WHERE uid=%{uid}";

delUserGroup

このSQL文は、指定するグループから特定のユーザーを外すために使用されます。ユーザの識別にはユーザIDを、グループの識別にはグループIDを使用します。

$conf['auth']['mysql']['delUserGroup']= "DELETE FROM usergroup
                                         WHERE uid='%{uid}'
                                         AND gid='%{gid}'";

補足情報

DokuWiki 2012-01-25b “Angua” においてMySQL認証バックエンドをテストした際に気付いた点をメモしておきます。認証に用いるデータベースの構造や仕様を考える際に役立つかもしれません。

ユーザ―マネージャープラグインの新規ユーザ登録画面を通じて、「ユーザー名がメールアドレス形式のユーザ」（例えば foo@bar）を作成したり、削除できる。ただし、当該ユーザーの編集はできない。
- 同プラグインを利用して、例えば、所属グループを後から変更できるようにするには、ユーザ―マネージャープラグインのソース修正が必要。（ヒント：関数 _editUser と _modifyUser の計2カ所で、cleanID()を適用を外す）
ユーザー名がメールアドレス形式のユーザーであっても、DokuWikiにログインできる。
- サイト設定で許可していれば、ログインユーザ自身がユーザ情報（フルネーム、メールアドレス、パスワード）を変更できる。
- メールアドレス形式のユーザーの専用ページ（例えば user:foo@bar）は作成できない。（DokuWikiページ名の仕様による）
chained（英文）で紹介されている認証チェーン機構（Chained Auth）と組み合わせることにより、ページの編集を許可するユーザの管理はDokuWiki側で行い、閲覧だけを許可するユーザは MySQL認証を使う方法を実現することも可能。

他システムのデータベースを使った例

(Real World Examples)

他のアプリケーション（掲示板、ブログなどのシステム）が使用するデータベースを DokuWukiのユーザ認証にも使うようにカスタマイズした例です。

Unclassified News Board (UNB) - a message board / forum
Another Unclassified News Board (UNB) - a message board / forum
Phorum - a message board / forum
FUDforum - a message board / forum
InvisionBoard - a message board / forum
phpBB Board - a message board / forum
Flyspray - a bug tracker
Drupal - a fine content management system (CMS)
e107 - another fine content management system (CMS)
Nucleus - a powerful blogging system
Gallery2 - a gallery: Gallery
Nuked Klan - a CMS for gamers :Nuked Klan
PostNuke - a CMS http://www.postnuke.org
Simple Machines Forum - Simple Machines Forum http://www.simplemachines.org
ProjectPier - collaboration system: http://projectpier.org
WordPress - a blogging system
Typo3 - an enterprise related content management system (CMS)
VBulletin - a message board / forum
Woltlab Burning Board - a message board / forum
Moodle - an elearning system

ja/auth/mysql.txt · 最終更新: 2012-08-23 15:53 by 2409:11:8000:0:e85e:d714:8fb6:7b29

目次