Debian Codegraph @

doc/html/_sources/imap/reference/admin/access-control/identifiers.rst.txt

raw
1 .. _imap-admin-access-control-identifiers:
2
3 Access Control Identifier (ACI)
4 ===============================
5
6 The Access Control Identifier (ACI) part of an ACL entry specifies the
7 user or group for which the entry applies. Group identifiers are
8 distinguished by the prefix "group:". For example, "group:accounting".
9
10 .. todo:: FIXME: Clarify what an ACL entry looks like first. Refer to
11 how user login names are translated into their identifiers, and (in
12 that section) refer to altnamespace, unixhierarchysep, default domain,
13 virtdomains, tips and tricks etc.
14
15 There are two special identifiers, "anonymous", and "anyone". The meaning of
16 other identifiers usually depends on the
17 :ref:`authorization mechanism<imap-admin-access-control-authorization-mechanisms>`
18 being used.
19
20 ``anonymous`` and ``anyone``
21 ----------------------------
22
23 With any authorization mechanism, two special identifiers are defined.
24 The identifier ``anonymous`` refers to the anonymous, or unauthenticated
25 user. The identifier ``anyone`` refers to all users, including the
26 anonymous user.
27
28 Both ``anonymous`` and ``anyone`` may commonly be used with the **post**
29 right ``p`` to allow message insertion to mailboxes.
30
31 .. _imap-admin-access-control-authorization-mechanisms:
32
33 Authorization Mechanisms
34 ========================
35
36 The Cyrus IMAP server comes with four authorization mechanisms, one is
37 compatible with Unix-style (``/etc/passwd``) authorization, one called
38 ``mboxgroups``, one for use with Kerberos 5, and one for use with an
39 external authorization process (ptloader) which can interface with
40 other group databases (e.g. AFS PTS groups, LDAP Groups, etc).
41
42 .. note::
43 **Authentication !== Authorization**
44
45 Note that authorization is *not* the same thing as authentication.
46 Authentication is the act of proving who you are. Authorization is
47 the act of determining what rights you have. Authentication is
48 discussed in the :ref:`imap-concepts-login-authentication` part of
49 this document.
50
51 The authorization mechanism in use is determined by the ``auth_mech``
52 :cyrusman:`imapd.conf(5)` option:
53
54 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
55 :start-after: startblob auth_mech
56 :end-before: endblob auth_mech
57
58
59 Unix Authorization
60 ------------------
61
62 ::
63
64 auth_mech: unix
65
66 In the Unix authorization mechanism, ACIs are either a valid userid or
67 the string ``group:`` followed by a group listed in ``/etc/group``.
68 Thus:
69
70 ::
71
72 root Refers to the user root
73 group:staff Refers to the group staff
74
75 It is also possible to use unix groups with users authenticated through
76 a non-/etc/passwd backend. Note that using unix groups in this way
77 (without associated ``/etc/passwd`` entries) is not recommended.
78
79 .. note::
80 Cyrus requires the getgrent(3) POSIX sysctl. As such, NSS needs to
81 be configured to have the groups available, one of which includes
82 "files", but could also include "ldap".
83
84 NSS augmentations, such as ``nss_ldap``, ``pam_ldap`` or ``sssd``
85 may be used to provide Cyrus access to group information via NSS.
86
87 .. _auth_mech_mboxgroups:
88
89 mboxgroups Authorization
90 ------------------------
91
92 ::
93
94 auth_mech: mboxgroups
95
96 The mboxgroups authorization mechanism is like the Unix mechanism, but it
97 looks for groups stored in the mailboxes.db instead of the system groups file.
98
99 When this authorization mechanism is in use, imapd will report the capability
100 ``XUSERGROUPS``, and admins can use the IMAP commands ``GETUSERGROUP``,
101 ``SETUSERGROUP``, and ``UNSETUSERGROUP`` for group management.
102
103 **GETUSERGROUP** *item*
104
105 If *item* is a userid, returns the groups the user belongs to. If
106 *item* is a group identifier, returns its members.
107
108 ::
109
110 C: 8 GETUSERGROUP cassandane
111 S: * USERGROUP cassandane ("group:group c" "group:group co")
112 S: 8 OK Completed
113 C: 9 GETUSERGROUP "group:group co"
114 S: * USERGROUP "group:group co" (cassandane otheruser)
115 S: 9 OK Completed
116
117 **SETUSERGROUP** *userid* *group*
118
119 Adds *userid* as a member of *group*
120
121 ::
122
123 C: 9 SETUSERGROUP cassandane "group:new group"
124 S: 9 OK Completed
125
126 **UNSETUSERGROUP** *userid* *group*
127
128 Removes *userid* from *group*
129
130 ::
131
132 C: 9 UNSETUSERGROUP cassandane "group:group c"
133 S: 9 OK Completed
134
135 Kerberos Authorization
136 ----------------------
137
138 ::
139
140 auth_mech: krb5
141
142 Using the Kerberos authorization mechanism, ACIs are of the form:
143
144 *$principal*.*$instance*@*$realm*
145
146 If ``$instance`` is omitted, it defaults to the null string. If
147 ``$realm`` is omitted, it defaults to the local realm.
148
149 PTS Authorization
150 -----------------
151
152 ::
153
154 auth_mech: pts
155
156 The PTS authorization mechanism is modular, with the module selected by the
157 ``pts_module`` :cyrusman:`imapd.conf(5)` option:
158
159 .. include:: /imap/reference/manpages/configs/imapd.conf.rst
160 :start-after: startblob pts_module
161 :end-before: endblob pts_module
162
163 The meaning of identifiers depends on the PTS module being used.
164
165 AFSKRB Authorization using PTS
166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
167
168 ::
169
170 auth_mech: pts
171 pts_module: afskrb
172
173 Document this! Probably by linking to a separate document.
174
175 HTTP Authorization using PTS
176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177
178 ::
179
180 auth_mech: pts
181 pts_module: http
182
183 Document this! Probably by linking to a separate document.
184
185 LDAP Authorization using PTS
186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
187
188 ::
189
190 auth_mech: pts
191 pts_module: ldap
192
193 Document this! Probably by linking to a separate document.
194
195 Alternative Authorization using PTS
196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
197
198 ::
199
200 auth_mech: pts
201 pts_module: ???
202
203 A site may wish to write their own authorization mechanism, perhaps to
204 implement a local group mechanism. You do this by implementing a custom
205 PTS module. The form and meaning of identifiers will be up to the
206 implementation.