From f917d8ac931e989a10d61b665ddb239759e28418 Mon Sep 17 00:00:00 2001 From: DJCrashdummy Date: Fri, 21 Feb 2020 08:39:33 +0100 Subject: [PATCH 1/3] rework readme - unified and corrected php-syntax - reworked IMAP description in the style of the XMPP description to prevent confusion with the order and numeration - added line breaks to XMPP description to make it easier readable - reworked SMB & HTTP heading - added jump-marks to headers for convenience - reordered sections to fit the order in the intro and at https://apps.nextcloud.com/apps/user_external --- README.md | 183 ++++++++++++++++++++++++++---------------------------- 1 file changed, 89 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 0bad94b..ac9cd46 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ External user authentication ============================ -**Authenticate user login against IMAP, SMB, FTP, WebDAV, HTTP BasicAuth, SSH and XMPP** +**Authenticate user login against [IMAP](#imap), [SMB](#smb), [FTP](#ftp), [WebDAV](#webdav), [HTTP BasicAuth](#http-basicauth), [SSH](#ssh) and [XMPP](#xmpp-prosody)** Passwords are not stored locally; authentication always happens against the remote server. @@ -16,45 +16,6 @@ If something does not work, check the log file at `nextcloud/data/nextcloud.log` **⚠⚠ Warning:** If you are using more than one backend or especially one backend more often than once, make sure that you still have resp. get unique `uid`s in the database. ⚠⚠ -FTP ---- -Authenticate Nextcloud users against a FTP server. - - -### Configuration -You only need to supply the FTP host name or IP. - -The second - optional - parameter determines if SSL should be used or not. - -Add the following to `config.php`: - - 'user_backends' => array( - array( - 'class' => 'OC_User_FTP', - 'arguments' => array('127.0.0.1'), - ), - ), - -To enable SSL connections via `ftps`, append a second parameter `true`: - - 'user_backends' => array( - array( - 'class' => 'OC_User_FTP', - 'arguments' => array('127.0.0.1', true), - ), - ), - - -### Dependencies -PHP automatically contains basic FTP support. - -For SSL-secured FTP connections via ftps, the PHP [openssl extension][FTP_0] -needs to be activated. - -[FTP_0]: http://php.net/openssl - - - IMAP ---- Authenticate Nextcloud users against an IMAP server. @@ -62,37 +23,34 @@ IMAP user and password need to be given for the Nextcloud login. ### Configuration -The parameters are `host, port, sslmode, domain`. -Possible values for sslmode are `ssl` or `tls`. Add the following to your `config.php`: - 'user_backends' => array( - array( + 'user_backends' => array ( + 0 => array ( 'class' => 'OC_User_IMAP', - 'arguments' => array( - '127.0.0.1', 993, 'ssl', 'example.com', true, false + 'arguments' => array ( + 0 => '127.0.0.1', + 1 => 993, + 2 => 'ssl', + 3 => 'example.com', + 4 => true, + 5 => false, ), ), ), -This connects to the IMAP server on IP `127.0.0.1`. -The default port is 143. However, note that parameter order matters and if -you want to restrict the domain (4th parameter), you need to also specify -the port (2nd parameter) and sslmode (3rd parameter; set to `null` for -insecure connection). -If a domain name (e.g. example.com) is specified, then this makes sure that -only users from this domain will be allowed to login. If the fifth parameter -is set to true, after successfull login the domain part will be striped and -the rest used as username in Nextcloud. e.g. 'username@example.com' will be -'username' in Nextcloud. The sixth parameter toggles whether on creation of -the user, it is added to a group corresponding to the name of the domain part -of the address. +`0`: IMAP server +`1`: IMAP server port (default `143`) +`2`: `'ssl'` or `'tls'` for secure connection (use `null` for insecure connection) +`3`: only users from this domain will be allowed to login (use `''` to allow all) +`4`: strip domain part after sucessful login and use the rest as username in Nextcloud (e.g. "username@example.com" will be "username" in Nextcloud) +`5`: on creation of a user add it to a group corresponding to the domain part of the address (e.g. "username" will get member of group "example.com" in Nextcloud) **⚠⚠ Warning:** If you are [**upgrading** from versions **<0.6.0**](https://github.com/nextcloud/user_external/releases/tag/v0.6.0), beside adapting your `config.php` you also have to change the `backend` column in the `users_external` table of the database. In your pre 0.6.0 database it may look like `{127.0.0.1:993/imap/ssl/readonly}INBOX` or similar, but now it has to be just `127.0.0.1` for everything to work flawless again. ⚠⚠ -Samba ------ +SMB +--- Utilizes the `smbclient` executable to authenticate against a windows network machine via SMB. @@ -102,10 +60,10 @@ The only supported parameter is the hostname of the remote machine. Add the following to your `config.php`: - 'user_backends' => array( - array( + 'user_backends' => array ( + array ( 'class' => 'OC_User_SMB', - 'arguments' => array('127.0.0.1'), + 'arguments' => array ('127.0.0.1'), ), ), @@ -114,34 +72,72 @@ Add the following to your `config.php`: The `smbclient` executable needs to be installed and accessible within `$PATH`. +FTP +--- +Authenticate Nextcloud users against a FTP server. + + +### Configuration +You only need to supply the FTP host name or IP. + +The second - optional - parameter determines if SSL should be used or not. + +Add the following to `config.php`: + + 'user_backends' => array ( + array ( + 'class' => 'OC_User_FTP', + 'arguments' => array ('127.0.0.1'), + ), + ), + +To enable SSL connections via `ftps`, append a second parameter `true`: + + 'user_backends' => array ( + array ( + 'class' => 'OC_User_FTP', + 'arguments' => array ('127.0.0.1', true), + ), + ), + + +### Dependencies +PHP automatically contains basic FTP support. + +For SSL-secured FTP connections via ftps, the PHP [openssl extension][FTP_0] +needs to be activated. + +[FTP_0]: http://php.net/openssl + + WebDAV ------ - Authenticate users by a WebDAV call. You can use any WebDAV server, Nextcloud server or other web server to authenticate. It should return http 200 for right credentials and http 401 for wrong ones. Attention: This app is not compatible with the LDAP user and group backend. This app is not the WebDAV interface of Nextcloud, if you don't understand what it does then do not enable it. + ### Configuration The only supported parameter is the URL of the web server. Add the following to your `config.php`: - 'user_backends' => array( - array( + 'user_backends' => array ( + array ( 'class' => '\OCA\User_External\WebDAVAuth', - 'arguments' => array('https://example.com/webdav'), + 'arguments' => array ('https://example.com/webdav'), ), ), -BasicAuth ------- - -Authenticate users by an [HTTP Basic access authentication][BasicAuth_0] call. +HTTP BasicAuth +-------------- +Authenticate users by an [HTTP Basic access authentication][BasicAuth_0] call. HTTP server of your choice to authenticate. It should return HTTP 2xx for correct credentials and an appropriate other error code for wrong ones or refused access. The HTTP server _must_ respond to any requests to the target URL with the "www-authenticate" header set. Otherwise BasicAuth considers itself to be misconfigured or the HTTP server unfit for authentication. + ### Configuration The only supported parameter is the URL of the web server where the authentication happens. @@ -149,31 +145,30 @@ The only supported parameter is the URL of the web server where the authenticati Add the following to your `config.php`: - 'user_backends' => array( - array( + 'user_backends' => array ( + array ( 'class' => 'OC_User_BasicAuth', - 'arguments' => array('https://example.com/basic_auth'), + 'arguments' => array ('https://example.com/basic_auth'), ), ), - [BasicAuth_0]: https://en.wikipedia.org/wiki/Basic_access_authentication SSH --- - Authenticates users via SSH. You can use any SSH2 server, but it must accept password authentication. + ### Configuration The supported parameters are the hostname and the port (default `22`) of the remote machine. Add the following to your `config.php`: - 'user_backends' => array( - array( + 'user_backends' => array ( + array ( 'class' => 'OC_User_SSH', - 'arguments' => array('127.0.0.1', '22'), + 'arguments' => array ('127.0.0.1', 22), ), ), @@ -194,25 +189,25 @@ Add the following to your `config.php`: 'user_backends' => array ( 0 => array ( 'class' => 'OC_User_XMPP', - 'arguments' => array ( - 0 => 'dbhost', - 1 => 'prosodydb', - 2 => 'dbuser', - 3 => 'dbuserpassword', - 4 => 'xmppdomain', - 5 => true, - ), + 'arguments' => array ( + 0 => 'dbhost', + 1 => 'prosodydb', + 2 => 'dbuser', + 3 => 'dbuserpassword', + 4 => 'xmppdomain', + 5 => true, ), + ), ), -0 - Database Host -1 - Prosody Database Name -2 - Database User -3 - Database User Password -4 - XMPP Domain -5 - Hashed Passwords in Database (true) / Plaintext Passwords in Database (false) +`0`: Database Host +`1`: Prosody Database Name +`2`: Database User +`3`: Database User Password +`4`: XMPP Domain +`5`: Hashed Passwords in Database (`true`) | Plaintext Passwords in Database (`false`) -**⚠⚠ Warning:** If you need to set *5 (Hashed Password in Database)* to false, your Prosody Instance is storing passwords in plaintext. This is insecure and not recommended. We highly recommend that you change your Prosody configuration to protect the passwords of your Prosody users. ⚠⚠ +**⚠⚠ Warning:** If you need to set *`5` (Hashed Passwords in Database)* to `false`, your Prosody Instance is storing passwords in plaintext. This is insecure and not recommended. We highly recommend that you change your Prosody configuration to protect the passwords of your Prosody users. ⚠⚠ Alternatives From b26d58336456b95d25a5ae038074f5e53310ff8a Mon Sep 17 00:00:00 2001 From: DJCrashdummy Date: Sat, 29 Feb 2020 18:38:29 +0100 Subject: [PATCH 2/3] [IMAP] changed ssl-parameter to fit version >=0.9 - parameter number `2` (the 3rd one): adapted options according to https://github.com/nextcloud/user_external/pull/126#discussion_r382742520 to fit https://github.com/nextcloud/user_external/pull/122 - parameter number `3` (the 4th one): added the second possibility to allow all domains according to https://github.com/nextcloud/user_external/pull/126#discussion_r384796352 Signed-off-by: DJCrashdummy --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ac9cd46..d15d6b3 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Add the following to your `config.php`: 'arguments' => array ( 0 => '127.0.0.1', 1 => 993, - 2 => 'ssl', + 2 => true, 3 => 'example.com', 4 => true, 5 => false, @@ -41,8 +41,8 @@ Add the following to your `config.php`: `0`: IMAP server `1`: IMAP server port (default `143`) -`2`: `'ssl'` or `'tls'` for secure connection (use `null` for insecure connection) -`3`: only users from this domain will be allowed to login (use `''` to allow all) +`2`: secure connection +`3`: only users from this domain will be allowed to login (use `''` or `null` to allow all) `4`: strip domain part after sucessful login and use the rest as username in Nextcloud (e.g. "username@example.com" will be "username" in Nextcloud) `5`: on creation of a user add it to a group corresponding to the domain part of the address (e.g. "username" will get member of group "example.com" in Nextcloud) From 1984b4114421bf0e9022755ddb01050f20d86c5e Mon Sep 17 00:00:00 2001 From: DJCrashdummy Date: Sat, 29 Feb 2020 18:39:51 +0100 Subject: [PATCH 3/3] fixed typo Signed-off-by: DJCrashdummy --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d15d6b3..4cfd1e1 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Add the following to your `config.php`: `0`: IMAP server `1`: IMAP server port (default `143`) -`2`: secure connection +`2`: secure connection `3`: only users from this domain will be allowed to login (use `''` or `null` to allow all) `4`: strip domain part after sucessful login and use the rest as username in Nextcloud (e.g. "username@example.com" will be "username" in Nextcloud) `5`: on creation of a user add it to a group corresponding to the domain part of the address (e.g. "username" will get member of group "example.com" in Nextcloud)