====== MySQL 認証バックエンド ======

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

[[:changes#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'' の二つのフィールドに分かれている点に注意してください。

<code sql 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;
</code>


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




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

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

<code php>
  <?php
      require_once('mysql.conf.php');
</code>

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

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

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

=== Option 'forwardClearPass' ===

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

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

<code php>
$conf['auth']['mysql']['forwardClearPass'] = 0;
</code>

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

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

=== Option 'debug' ===

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

<code php>
$conf['auth']['mysql']['debug']= 0;
</code>


\\
==== MySQL認証を有効にする ====

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

<code php>
$conf['authtype'] = "mysql";
</code>

**注意**
  * この時点でデータベースには まだ adminユーザーが登録されていない点に注意してください。
  * 管理画面で [[ja:config: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}  | 管理画面で設定した「既定のグループ」の名前 （[[ja:config:defaultgroup]] ）  |
| %{name}  | ユーザーの 氏名（fullname）  |
| %{mail}  | ユーザーのメールアドレス（email address）  |
| %{group}  | グループ名  |
| %{uid}  | ユーザーの識別にデータベースのテーブルで使用されているID  |
| %{gid}  | グループの識別にデータベースのテーブルで使用されているID  |


\\
mysql.conf.php内で定義するSQL文は複数ありますが、次の5カテゴリに整理されます。ユーザー管理の機能を DokuWiki側（＝[[ja:plugin:usermanager]] プラグイン）でどこまで行うかによって、用意すべきSQL文のカテゴリ範囲が異なります。
  - [[ja:auth:mysql#SQL User Authentication]] -- DokuWiki本体でのユーザー認証に必須となるもの
  - [[ja:auth:mysql#SQL Basic User Manager Support]] -- ユーザーマネージャー プラグイン でユーザの表示だけを行う場合に必要
  - [[ja:auth:mysql#SQL Support for Add User]] -- ユーザーマネージャー プラグイン でユーザの追加（作成）を行う場合に必要
  - [[ja:auth:mysql#SQL Support for Delete User]] -- ユーザーマネージャー プラグイン でユーザの削除を行う場合に必要
  - [[ja:auth:mysql#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 と設定して運用する方が無難です。 

<code php>
$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}'";
</code>

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

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

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


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

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


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

<code php>
$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}'";
</code>


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

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

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

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

<code php>
$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";
</code>


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


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

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

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

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

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


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

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

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

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

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

<code php>
$conf['auth']['mysql']['delGroup']    = "DELETE FROM groups
                                         WHERE gid='%{gid}'";
</code>

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

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

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

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

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


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

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

<code php>
$conf['auth']['mysql']['delUser']     = "DELETE FROM users
                                         WHERE uid='%{uid}'";
</code>

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

<code php>
$conf['auth']['mysql']['delUserRefs'] = "DELETE FROM usergroup
                                         WHERE uid='%{uid}'";
</code>


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

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

<code php>
$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}";
</code>

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

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


\\
===== 補足情報 =====

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

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



\\
===== 他システムのデータベースを使った例 =====
(Real World Examples)

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

  * [[auth:mysql_UNB|Unclassified News Board]] ([[http://newsboard.unclassified.de/|UNB]]) - a message board / forum
  * [[auth:mysql_UNB2|Another Unclassified News Board]] ([[http://newsboard.unclassified.de/|UNB]]) - a message board / forum
  * [[auth:mysql_phorum|Phorum]] - a message board / forum
  * [[auth:mysql_fudforum|FUDforum]] - a message board / forum
  * [[auth:mysql_invision|InvisionBoard]] - a message board / forum
  * [[auth:mysql_phpbb|phpBB Board]] - a message board / forum
  * [[auth:mysql_flyspray|Flyspray]] - a bug tracker
  * [[auth:mysql_drupal|Drupal]] - a fine content management system (CMS)
  * [[auth:mysql_e107|e107]] - another fine content management system (CMS)
  * [[auth:mysql_nucleus|Nucleus]] - a powerful blogging system  
  * [[auth:mysql_gallery2|Gallery2]] - a gallery: [[http://gallery.menalto.com|Gallery]]
  * [[auth:mysql_nuked-klan|Nuked Klan]] - a CMS for gamers :[[http://www.nuked-klan.org|Nuked Klan]]
  * [[auth:mysql_postnuke|PostNuke]] - a CMS [[http://www.postnuke.org]]
  * [[auth:mysql_smf|Simple Machines Forum]] - Simple Machines Forum [[http://www.simplemachines.org]]
  * [[auth:mysql_projectpier|ProjectPier]] - collaboration system: [[http://projectpier.org|http://projectpier.org]]
  * [[http://thedeadone.net/software/getting-dokuwiki-to-use-wordpress-authentication/|WordPress]] - a blogging system
  * [[auth:mysql_typo3|Typo3]] - an enterprise related content management system (CMS)
  * [[auth:mysql_vbulletin|VBulletin]] - a message board / forum
  * [[auth:mysql_wbb|Woltlab Burning Board]] - a message board / forum
  * [[auth:mysql_moodle|Moodle]] - an elearning system