prosody-modules
099dcdb732b1
mod_auth_cyrus/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_auth_cyrus/README.md @ 4710:099dcdb732b1

mod_auth_cyrus: Import from Prosody rev 8f1e7fd55e7b
author Kim Alvefur <zash@zash.se>
date Sun, 17 Oct 2021 17:08:07 +0200
child 4926:b8366e31c829
comparison
equal deleted inserted replaced
4709:679f1834dbdb 4710:099dcdb732b1
1 ---
2 title: Cyrus SASL
3 rockspec:
4 build:
5 modules:
6 util.sasl_cyrus: sasl_cyrus.lua
7 ---
8
9 # Introduction
10
11 XMPP uses a standard authentication protocol called 'SASL' to validate
12 client credentials. Prosody has a built-in SASL library, and uses this
13 by default to validate credentials against Prosody's internal account
14 store.
15
16 Alternatively Prosody supports using Cyrus SASL, an external SASL
17 provider which can validate user-supplied credentials against other
18 sources, such as PAM, LDAP, SQL and more. It also allows the use of
19 GSSAPI for single-sign-on services.
20
21 # Usage
22
23 ## lua-cyrussasl
24
25 To allow Prosody to access Cyrus SASL you need to install lua-cyrussasl.
26 Information on how to do that on most platforms can be found on our
27 [dependencies page](/doc/depends). Those running Debian/Ubuntu can
28 simply:
29
30 ``` {.code}
31 sudo apt-get install lua-cyrussasl
32 ```
33
34 On Redhat/CentOS, the [EPEL
35 repository](https://fedoraproject.org/wiki/EPEL) needs to be enabled,
36 after which you can install the package:
37
38 ``` {.code}
39 sudo yum install lua-cyrussasl
40 ```
41
42 ## Configuration
43
44 Enable the cyrus backend by adding the following line to your config
45 file:
46
47 ``` {.code .lua}
48 authentication = "cyrus"
49 cyrus_service_name = "xmpp" -- Optional, defaults to "xmpp"
50 ```
51
52 Configuring Cyrus SASL itself is currently beyond the scope of this
53 documentation. If you feel you could contribute a simple how-to, or know
54 the link of a good one to add below then [let us know](/discuss)
55 [:smile:]{.icon}
56
57 Prosody's Cyrus SASL-related options:
58
59 Option Default Description
60 ---------------------------- --------- --------------------------------------------------------------------------------------------------------------
61 cyrus_service_name xmpp The service name to pass to Cyrus SASL.
62 cyrus_service_realm (auto) The realm to pass to Cyrus SASL, the virtual host the user is signing into if not specified.
63 cyrus_require_provisioning false If true then Prosody requires user accounts to exist in Prosody, even if successfully authenticated via SASL
64 cyrus_application_name prosody The application name to pass to Cyrus SASL. Determines the Cyrus SASL configuration file name.
65 cyrus_server_fqdn hostname passed to Cyrus
66
67 ## Troubleshooting
68
69 ### Permissions
70
71 One of the most common issues is Prosody being unable to access the
72 saslauthd socket (this is obviously only an issue if you are using the
73 saslauthd daemon), used to communicate with the authentication daemon.
74 An example error caused by this would be:
75
76 ``` {.code}
77 Got SASL error condition -1: Password verification failed
78 ```
79
80 This can be confirmed by trying testsaslauthd as root and then as the
81 user prosody runs as (typically 'prosody'); the former should succeed
82 and the latter should fail.
83
84 The solution is to make sure that prosody can access the socket
85 (typically in /var/run/saslauthd/) by adding the 'prosody' user to the
86 'sasl' group (or otherwise ensuring that the prosody user has filesystem
87 permissions to access the socket).
88
89 ### Cyrus SASL Configuration file {#cyrus_sasl_configuration_file}
90
91 Cyrus SASL needs a configuration file in order to know where to look for
92 user credentials. For Prosody, the file will be named prosody.conf by
93 default. Its location varies by OS and distribution; refer to the table
94 below or your local system documentation for where it should go.
95
96 Location Platforms
97 ------------ -------------------
98 /etc/sasl Debian and Ubuntu
99 /etc/sasl2 Arch, RHEL/CentOS
100
101 The contents of the configuration file depend on what you want to
102 authenticate against. If you want to authenticate against local
103 accounts, you'll want to set up saslauthd (the configuration of
104 saslauthd varies from system to system), and your prosody.conf will look
105 like this:
106
107 ``` {.code}
108 pwcheck_method: saslauthd
109 mech_list: PLAIN
110 ```
111
112 If using saslauthd, you must specify only PLAIN in the mech_list, as it
113 only supports plaintext authentication methods.
114
115 ## Other references {#other_references}
116
117 - [Setting up Prosody to authenticate against LDAP (blog
118 post)](http://blog.marc-seeger.de/2009/12/30/setting-up-prosody-to-authenticate-against-ldap/)
119 - This post uses xmpp.conf, but the name is now prosody.conf (see
120 cyrus_application_name above)
121 - [Surviving Cyrus SASL
122 (PDF)](http://www.arschkrebs.de/slides/surviving_cyrus_sasl-handout.pdf)
123 [(view)](http://docs.google.com/viewer?url=http%3A%2F%2Fwww.arschkrebs.de%2Fslides%2Fsurviving_cyrus_sasl-handout.pdf)
124 - [Cyrus SASL error
125 codes](http://cvs.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/lib/libsasl/include/sasl.h#186)