README.md
1# AuthRemoteUser #
2
3This *<a href="https://www.dokuwiki.org/" target="_blank">DokuWiki</a>*
4<a href="https://www.dokuwiki.org/plugin:authremoteuser"
5target="_blank">plugin</a> provides Single Sign On authentication via an
6environment variable of the web server which is set through authentication
7systems like
8
9 * HTTP-Auth,
10 * LDAP,
11 * CAS,
12 * Cosign,
13 * NTLM,
14 * PAM,
15 * WebAuth,
16 * SSPI,
17 * and so on.
18
19Default variable name is `REMOTE_USER`.
20
21It uses the default plain text file `conf/users.auth.php` to store user
22information.
23
24## Installation ##
25
26 1. Enable an authentication system which sets (domain and) username in an
27 environment variable on your web server (`_SERVER[...]`) (and disable
28 anonymous authentication) on your web server.
29
30 2. Search and install the plugin using the
31 <a href="https://www.dokuwiki.org/plugin:extension"
32 target="_blank">Extension Manager</a>. Refer to
33 <a href="https://www.dokuwiki.org/plugin_installation_instructions#manual_instructions"
34 target="_blank">Plugin Installation Instructions</a> on how to install
35 plugins manually.
36
37## Usage ##
38
39 1. Determine the variable name your authentication system uses:
40
41 1. Default is `REMOTE_USER`.
42
43 2. If your authentication system uses another variable name notice this
44 name.
45
46 2. Determine your username:
47
48 1. Save file `phpinfo.php` on your web server:
49
50 ```php
51 <?PHP
52 phpinfo();
53 ?>
54 ```
55
56 2. Open `phpinfo.php` in your web browser and search for the (domain and)
57 username in `_SERVER[...]` whereby `...` is the variable name of your
58 authentication system.
59
60 3. Add this value as new user ID to your user list if it is missing and
61 add them groups `admin` and `user`.[^1]
62
63 4. Remove file `phpinfo.php`.
64
65 3. In your *DokuWiki* login as superuser, click *Admin*, choose
66 *Configuration Settings*, and configure these settings:
67
68 1. Disable action `profile`.
69
70 2. If enabled, disable option `subscribers` temporarily.
71
72 3. Enable `authtype` *AuthRemoteUser*.
73
74 4. Disable `rememberme`.
75
76 5. If your authentication system doesn't use variable name `REMOTE_USER`
77 set the name (see also topic 1.2) in `server_var_name_of_auth_system`.
78
79 5. Save this configuration.
80
81 4. Remove *DokuWiki* cookie from your browser or close and restart your
82 browser.
83
84 5. Reload your *DokuWiki* installation. Your login should be automatically
85 detected.
86
87 6. Now, you can re-enable option `subscribers` again (see above).
88
89Copy the configuration settings to the `conf/local.protected.php` file to
90<a href="https://www.dokuwiki.org/plugin:config#protecting_settings"
91target="_blank">protect the settings</a> against changes via *Config Manager*.
92
93Administration of users and its groups is done in the *User Manager* which is
94fully supported by this plugin.
95
96## Storage ##
97
98*AuthRemoteUser* uses the same storage backend like *authplain* that is
99`conf/users.auth.php`. Users which are added after switching to
100*AuthRemoteUser*, won't contain an encrypted password.
101
102That is: You can switch back to *authplain* (and enable `profile` setting)
103whenever you want, and all your users which were already added before are still
104able to login using their (hopefully yet known) password. All other users can
105use the *forget my password* link.
106
107### File Format ###
108
109Empty lines, and everything after a `#` character are ignored. Each line
110contains a colon separated array of five fields:
111
112```txt
113loginname:password:Real Name:email:groups
114```
115
116 * `loginname`:
117 This has to be a valid <a href="https://www.dokuwiki.org/pagename"
118 target="_blank">page name</a>.
119 * `password`:
120 Encrypted password if user id was added using *authplain*, otherwise empty.
121 * `Real Name`:
122 Real name of the user.
123 * `email`:
124 Email address of user.
125 * `groups`:
126 Comma separated list of groups a user is member of. The group names must
127 follow the rules of valid <a href="https://www.dokuwiki.org/pagename"
128 target="_blank">page names</a>.
129
130### Editing ###
131
132Since `conf/users.auth.php` is a plain text file, it can be edited with any
133text editor.
134
135
136
137[^1]: Don't be surprised: The user ID is converted to a valid page name.
138
139