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