Write a better documentation about authentication and rights

[Forage]

Hi,

I've been going through the user documentation and the mains thing that remains unclear to me is how users are handled. There's talk about users and usernames, but it doesn't talk about where the users are actually coming from and/or how they should be created.

For example, there's this section talking about apache authentication which starts about restricting access only to alice.
Would it be possible to also include where this alice is coming from and how the access is restricted to this user? What should be done where?

Thanks in advance.

[liZe]

That's a good question.

It's really important to understand the two different parts:

• Authentication is the step needed to know which user is requesting the data (get an username from a CalDAV request).
• Rights management is the step needed to know what an user can do (get read/write rights from an username).

There's talk about users and usernames, but it doesn't talk about where the users are actually coming from and/or how they should be created.

Users and usernames are defined in the source of your authentication method. For example, if you're using the IMAP module, you must have an IMAP server with users configured in it. It's the same with LDAP, PAM…

If you don't have a service like this, you can use the htpasswd module where the users come from a simple file with a username and a password on each line. You then need this in your configuration file:

[auth]
type = htpasswd
htpasswd_filename = /path/to/my/htpasswd/file
htpasswd_encryption = crypt

[rights]
type = owner_only

And this in your /path/to/my/htpasswd/file

alice:p@ssw0rd

Is that better than the documentation 😄?

[Forage]

Yes, merci for your response :-)

I managed to figure out most of it by now, but what has cost me the most time where the references to user in the documentation. Please, to prevent others not wasting a lot of time and/or giving up, give all references to user a different mark-up like italic, optionally surround it by whatnot ((), [], {}, %%), state in each case that that part should be replaced by the actual user name, give it the name username instead of just user and do this consistently throughout the user manual.

E.g. https://example.com/radicale/user/ http://example.com:5232/Username http://localhost:5232/user/calendar.ics/ etc.

Here I was thinking it was some kind of REST style endpoint, not replacing it by the actual user name and looking for the reason why things were not working in all sorts of different places... Highly frustrating.

Also, even though you removed the well-known URL stuff again, for the current stable release, shouldn't the default rewrite rules include a RewriteCond %{REQUEST_URI} !^/.well-known/.+ to not have those requests simply result in a forbidden response when running your server behind Apache?

[liZe]

Please, to prevent others not wasting a lot of time and/or giving up, give all references to user a different mark-up like italic, optionally surround it by whatnot ((), [], {}, %%), state in each case that that part should be replaced by the actual user name, give it the name username instead of just user and do this consistently throughout the user manual.

Definitely. I'm always disappointed when I spend hours fighting against some bad documentation, so… I'm sorry!

Also, even though you removed the well-known URL stuff again, for the current stable release, shouldn't the default rewrite rules include a RewriteCond %{REQUEST_URI} !^/.well-known/.+ to not have those requests simply result in a forbidden response when running your server behind Apache?

We really need to have some documentation pages dedicated to HTTP servers and their configurations.

I close this issues as it's tracked by #372 and somehow related to #197 and #511.