You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f48d1b2
Browse filesBrowse the repository at this point in the historyBrowse files
to others without granting them full administration privileges (and without making them a
122
+
member of the ``admin`` group).
123
+
124
+
Specific groups can be granted authorization to access individual admin settings. This is a
125
+
feature that needs to be enabled for each admin setting class. To do so, the setting class
126
+
needs to implement ``IDelegatedSettings`` instead of ``ISettings`` and implement two additional
127
+
methods.
128
+
129
+
Authorizing app-config keys
130
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
131
+
132
+
The values returned by ``getAuthorizedAppConfig()`` define which app-config keys delegated
133
+
administrators may modify. Use exact key names whenever possible. Regular expressions are
134
+
supported for dynamic key names, but should match the complete key using ``^`` and ``$``.
135
+
Avoid unanchored expressions such as ``/notes_.*/``, which can match a key that merely
136
+
contains the intended prefix.
117
137
118
138
.. code-block:: php
119
139
@@ -137,19 +157,138 @@ and implement two additional methods.
137
157
138
158
public function getAuthorizedAppConfig(): array {
139
159
return [
140
-
// Allow a list of regex that the user can modify with this setting.
141
-
'notes' => ['/notes_.*/', '/my_notes_setting/'],
160
+
// Simplest: authorize one exact key from this app.
161
+
'notes' => [
162
+
'my_notes_setting',
163
+
],
142
164
];
143
165
}
144
166
}
145
167
146
-
Additionally, if your setting class needs to fetch data or send data to some admin-only
147
-
controllers, you will need to mark the methods in the controller as accessible by the
148
-
setting with attribute.
168
+
Using the application ID
169
+
~~~~~~~~~~~~~~~~~~~~~~~~
149
170
150
-
.. note::
171
+
The app name can be referenced through ``Application::APP_ID``. This avoids duplicating
172
+
the app ID as a string:
173
+
174
+
.. code-block:: php
175
+
176
+
use OCA\NotesTutorial\AppInfo\Application;
177
+
178
+
public function getAuthorizedAppConfig(): array {
179
+
return [
180
+
// Multiple keys: authorize several exact keys in this app.
181
+
Application::APP_ID => [
182
+
'my_notes_setting',
183
+
'another_notes_setting',
184
+
],
185
+
];
186
+
}
187
+
188
+
Authorizing dynamic key names
189
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190
+
191
+
For a family of dynamically named keys, use an anchored regular expression that is as
192
+
restrictive as possible:
193
+
194
+
.. code-block:: php
195
+
196
+
public function getAuthorizedAppConfig(): array {
197
+
return [
198
+
// Authorize keys such as "notes_feature_a" and "notes_feature_b",
199
+
// but not "custom_notes_feature_a".
200
+
Application::APP_ID => [
201
+
'/^notes_[a-z0-9_]+$/',
202
+
],
203
+
];
204
+
}
205
+
206
+
Escaping dynamic regular expressions
207
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
208
+
209
+
When a regular expression is built from a variable or a constant, escape the inserted
210
+
value with ``preg_quote()``:
211
+
212
+
.. code-block:: php
213
+
214
+
$prefix = preg_quote('notes_', '/');
215
+
216
+
return [
217
+
Application::APP_ID => [
218
+
"/^{$prefix}[a-z0-9_]+$/",
219
+
],
220
+
];
221
+
222
+
Using configuration constants
223
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224
+
225
+
For stable, declared configuration keys, prefer dedicated constants or constants from an
226
+
app's ``ConfigLexicon`` class. This keeps the delegated authorization list synchronized
227
+
with the app's configuration definitions.
228
+
229
+
For example, ``<myapp>/lib/ConfigLexicon.php`` might contain:
151
230
152
-
The attribute is only available in Nextcloud 27 or later. In older versions, the ``@AuthorizedAdminSetting(settings=OCA\NotesTutorial\Settings\NotesAdmin)`` annotation can be used.
231
+
.. code-block:: php
232
+
233
+
<?php
234
+
namespace OCA\NotesTutorial;
235
+
236
+
class ConfigLexicon {
237
+
// For PHP versions before 8.3, omit the "string" type.
238
+
public const string MY_SETTING = 'my_notes_setting';
239
+
public const string ANOTHER_SETTING = 'another_notes_setting';
240
+
}
241
+
242
+
Which can then reference:
243
+
244
+
.. code-block:: php
245
+
246
+
use OCA\NotesTutorial\AppInfo\Application;
247
+
use OCA\NotesTutorial\ConfigLexicon;
248
+
249
+
public function getAuthorizedAppConfig(): array {
250
+
return [
251
+
// Constants: Preferred for stable, declared configuration keys.
252
+
Application::APP_ID => [
253
+
ConfigLexicon::MY_SETTING,
254
+
ConfigLexicon::ANOTHER_SETTING,
255
+
],
256
+
];
257
+
}
258
+
259
+
Authorizing keys from multiple apps
260
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261
+
262
+
If a setting intentionally authorizes configuration keys from more than one app, return
263
+
one entry for each app. Prefer the corresponding app's ``Application::APP_ID`` constant
264
+
when it is available:
265
+
266
+
.. code-block:: php
267
+
268
+
use OCA\AnotherApp\AppInfo\Application as AnotherAppApplication;
269
+
270
+
public function getAuthorizedAppConfig(): array {
271
+
return [
272
+
Application::APP_ID => [
273
+
ConfigLexicon::MY_SETTING,
274
+
],
275
+
AnotherAppApplication::APP_ID => [
276
+
// Prefer AnotherApp's ConfigLexicon constant when available.
277
+
'another_setting',
278
+
],
279
+
];
280
+
}
281
+
282
+
Do not use ``/.*/`` unless the setting intentionally grants delegated administrators
283
+
access to every key belonging to the app. Do not use a regular expression for a fixed key:
284
+
return the literal key instead.
285
+
286
+
Authorizing admin-only controllers
287
+
----------------------------------
288
+
289
+
The ``getAuthorizedAppConfig()`` method controls app-config writes. It does not grant
290
+
access to arbitrary controller endpoints. If your setting class needs to call admin-only
291
+
controller methods, mark those methods with the ``AuthorizedAdminSetting`` attribute.
153
292
154
293
.. code-block:: php
155
294
:emphasize-lines: 8
@@ -168,14 +307,17 @@ setting with attribute.
168
307
...
169
308
}
170
309
171
-
172
-
If you have several ``IDelegatedSettings`` classes that are needed for a function, add multiple attributes and separate them with semicolons.
173
-
174
310
.. note::
175
311
176
-
If you use the deprecated annotation specify the classes separated by semicolons:
312
+
The attribute is only available in Nextcloud 27 or later. In older versions, the
0 commit comments