Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: rework readme #126

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

DOC: rework readme #126

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f917d8a
rework readme
DJCrashdummy Feb 21, 2020
b26d583
[IMAP] changed ssl-parameter to fit version >=0.9
DJCrashdummy Feb 29, 2020
1984b41
fixed typo
DJCrashdummy Feb 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 89 additions & 94 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -16,83 +16,41 @@ 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.
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 => true,
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. '[email protected]' 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`: secure connection
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay, update for this parameter (also for the example above). We missed the case of starttls (as in #135). So code changes under way in #138. To conclude there is:

  • ssl for ssl/tls connections as normaly on port 993 which are encrypted from the beginning
  • tls for STARTTLS which is normally used on port 143 (so connection is initialized but then "upgraded" to a tls connection via a respective IMAP command with instructions)
  • notls (or technically any different value as of the implementations, but notls should be used) for plain connections (normally on port 143)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay, this might change again, as there is an intention to default to STARTTLS (everything that's not explicit ssl or notls) in #140

`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. "[email protected]" 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.

Expand All @@ -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'),
),
),

Expand All @@ -114,66 +72,103 @@ 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.

**⚠⚠ Warning:** make sure to use the URL of a correctly configured HTTP Basic authenticating server. If the server always responds with a HTTP 2xx response without validating the users, this would allow anyone to log in to your Nextcloud instance with **any username / password combination**. ⚠⚠

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),
),
),

Expand All @@ -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
Expand Down