summaryrefslogtreecommitdiff
path: root/doc/authentication.rst
blob: d9d50661d00837deb125e006dfcf819583c51884 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
============================================
External authentication with SemanticScuttle
============================================

Most times, one piece of software is only a part in the big puzzle
that makes the software landscape of a company or organization.
SemanticScuttle is not different and should integrate as nicely as
possible with all other systems.

One of the basic tasks of integration is user authentication against
a central database - be it a central user database, an LDAP or a
active directory server.

Since version 0.96, SemanticScuttle supports user authentication against
external systems. To provide a wide range of supported systems, we chose
to utilize PEAR's `Authentication package`__.
It does this by providing different "`authentication containers`__",
for example Database, IMAP, LDAP, POP3, RADIUS, SAP and SOAP.

Please be aware of the fact that, after successful authentication, the user
and his scrambled password are stored in the SemanticScuttle database.
This is required for proper functioning of the software. It does not mean
that you will be able to login if your external authentication provider
is offline - you won't, execpt you switch it off in the SemanticScuttle
configuration.


__ http://pear.php.net/package/Auth
__ http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php


Basic configuration
===================
The default configuration file ``data/config.default.php`` has an own section
on auth options and an explanation of the single entries.

To utilize the external authentication, you need to install the
PEAR Auth package: ::

  $ pear install auth

If you do not have a PEAR installation available, you can try to manually
install the files in the src/ directory. If you choose to do that, the
src/ directory should look similar to that: ::

  src/
   Auth.php
   Auth/
    Anonymous.php
    Container.php
    Container/
    ..
   SemanticScuttle/
    header.php
    ..

After that, modify your ``data/config.php`` file. The most important change
is to use ::

  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';

which tells SemanticScuttle to switch to the special authentication service.

Now that's done, you can configure the single auth options:

``$authType = 'MDB2';``
  selects the authentication container.

``$authOptions``
  is an array of options specific to the authentication container. Please
  consult the PEAR Auth documentation for more information.

``$authDebug = true;``
  should be used when setup fails, since it may give important hints
  where it fails.

  Please note that login will seem to fail with
  debugging activated. Going back to the main page after that will
  show that you are logged in.



Authentication examples
=======================

General database authentification
---------------------------------
Here you also need the PEAR `MDB2 package`_.
The "``new_link``" option is important!

``config.php`` settings: ::

  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
  $authType = 'MDB2';
  $authOptions = array(
      'dsn' => array(
          'phptype'  => 'mysql',
          'hostspec' => 'FIXME',
          'username' => 'FIXME',
          'password' => 'FIXME',
          'database' => 'FIXME',
          'new_link' => true,
      ),
      'table'       => 'usersFIXME',
      'usernamecol' => 'usernameFIXME',
      'passwordcol' => 'passwordFIXME',
      'cryptType'   => 'md5',
  );


Mantis Bugtracker
-----------------
Here you also need the PEAR `MDB2 package`_.

``config.php`` settings: ::

  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
  $authType = 'MDB2';
  $authOptions = array(
      'dsn' => array(
          'phptype'  => 'mysql',
          'hostspec' => 'FIXME',
          'username' => 'FIXME',
          'password' => 'FIXME',
          'database' => 'FIXME',
          'new_link' => true,
      ),
      'table'       => 'mantis_user_table',
      'usernamecol' => 'username',
      'passwordcol' => 'password',
      'cryptType'   => 'md5',
  );

.. _MDB2 package: http://pear.php.net/package/MDB2


MediaWiki
---------
Unfortunately, the password column does not contain a simple hashed
password - for good reasons as described on
http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column

If you configure your MediaWiki_ to use passwords without salt, you
can make it work nevertheless:

MediaWiki ``LocalSettings.php``: ::

  $wgPasswordSalt = false;

\- after that, users need to change/update their passwords to get them
unsalted in the database. You can verify if the passwords are unhashed
if you do ::

  SELECT CAST( user_password AS CHAR ) FROM user

on your MediaWiki database. Passwords prefixed with "``:A:``" can be used.

Another problem is that mediawiki user names begin with an uppercase letter.
You need to modify ``www/login.php`` and remove the "``utf8_strtolower``" function
call: ::

  $posteduser = trim(utf8_strtolower(POST_USERNAME));

becomes ::

  $posteduser = trim(POST_USERNAME);


``config.php`` settings: ::

  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
  $authType = 'MDB2';
  $authOptions = array(
      'dsn' => array(
          'phptype'  => 'mysql',
          'hostspec' => 'FIXME',
          'username' => 'FIXME',
          'password' => 'FIXME',
          'database' => 'FIXME',
          'new_link' => true,
      ),
      'table'       => 'user',
      'usernamecol' => 'user_name',
      'passwordcol' => 'user_password',
      'cryptType'   => 'md5_mediawiki',
  );
  function md5_mediawiki($password) {
      return ':A:' . md5($password);
  }


.. _MediaWiki: http://www.mediawiki.org/wiki/MediaWiki

Active Directory / LDAP
-----------------------
Here we authenticate against an active directory server.

``config.php`` settings: ::

  $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser';
  $authType = 'LDAP';
  $authOptions = array(
      'host'     => '192.168.1.4',
      'version'  => 3,
      'basedn'   => 'DC=EXAMPLE,DC=ORG',
      'binddn'   => 'readuser',
      'bindpw'   => 'readuser',
      'userattr' => 'sAMAccountName',
      'userfilter' => '(objectClass=user)',
      'attributes' => array(''),
  );
  $authEmailSuffix = '@example.org';

More LDAP options can be found in the `PEAR manual`__.

__ http://pear.php.net/manual/en/package.authentication.auth.storage.ldap.php