Версія 2.2 додана 2024/07/11 10:05 автором Ashterix
Показати останніх авторів
1 {{box cssClass="floatinginfobox" title="**Зміст**"}}
2 {{toc/}}
3 {{/box}}
4
5 {{info}}
6 Конфігурація зазнала суттєвих змін і не має зворотної сумісності з версією 6.
7 {{/info}}
8
9 (% class="wikigeneratedid" %)
10 Всі налаштування бандла знаходяться в файлі {{code language="none"}}config/packages/ufo_json_rpc.yaml{{/code}}.
11
12 (% class="wikigeneratedid" %)
13 Є можливість налаштувати параметри захисту API та деякі параметри формату даних, що віддається при запиті документації.
14
15 = Блок {{code language="none"}}security{{/code}} =
16
17 Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
18
19 == Параметр {{code language="none"}}protected_methods{{/code}} ==
20
21 (% class="wikigeneratedid" %)
22 Цей параметр приймає масив назв http методів, які мають бути захищені.
23
24 (% class="wikigeneratedid" %)
25 За замовченням ввімкнут захист лише для методу POST. Ви можете:
26
27 * вказати пустий масив {{code language="none"}}[]{{/code}} щоб зробити API повністю відкритим
28
29 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
30 ufo_json_rpc:
31 security:
32 protected_methods: []
33 {{/code}}
34
35 * вказати додатково захист для методу GET, що зробить запит документації недоступним без токену в заголовках запиту
36
37 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
38 ufo_json_rpc:
39 security:
40 protected_methods: ['GET', 'POST']
41 {{/code}}
42
43 (% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_methods{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
44
45 Перш за все, треба визначитися з назвою токену.
46
47 == Параметр {{code language="none"}}token_key_in_header{{/code}} ==
48
49 Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_key_in_header: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
50
51 {{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
52 Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
53
54 - Капіталізація: Зазвичай назви HTTP заголовків пишуться з використанням CamelCase, де кожне слово починається з великої літери, наприклад, Content-Type, User-Agent, Accept-Encoding. Це не впливає на технічну обробку заголовків, але робить їх легше читати.
55 - Унікальність: Кожен заголовок повинен мати унікальну назву у контексті одного HTTP запиту або відповіді. Не можна використовувати однакові назви для різних заголовків у тому самому запиті чи відповіді.
56 - Спеціальні заголовки: Існують заголовки, які використовуються специфічно для контролю поведінки кешування (Cache-Control), безпеки (Strict-Transport-Security), аутентифікації (Authorization), тощо.
57 - Норми RFC: Вимоги до заголовків регулюються документами RFC, які визначають стандарти для протоколів Інтернету. Наприклад, загальні заголовки і їхнє використання описані в RFC 7231.
58 {{/spoiler}}
59
60
61
62
63
64
65
66
67
68
69 == Параметр {{code language="none"}}clients_tokens{{/code}} ==
70
71 Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
72
73 Тут є певна варіативність.
74
75 === Токени в параметрах ===
76
77 (% class="box errormessage" %)
78 (((
79 **НЕ РЕКОМЕНДОВАНО!!!**
80 \\Цей підхід допускається лише для локального тестування API
81 )))
82
83 Є можливість прописати токени хардкодом прямо в файлі налаштувань.
84
85 Це погано з позиції безпеки, якщо код зберігається в публічному репозиторію, то до цього токену буде мати доступ кожен.
86
87 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
88 ufo_json_rpc:
89 security:
90 protected_methods: ['GET', 'POST']
91 token_key_in_header: 'Ufo-RPC-Token'
92 clients_tokens:
93 - 'ClientTokenExample' # hardcoded token example. Importantly!!! Replace or delete it!
94
95 {{/code}}
96
97 === Токени в змінних оточення ===
98
99 Це найбільш доцільний механізм у разі, якщо ви розробляєте сервіс для розподіленого бекенду, що написаний на SOA (Сервіс-Орієнтована Архітектура). Зазвичай, в такому випадку, вам треба відкрити доступ до апі одному або обмеженій кількості клієнтських додатків і оновлення ключів не буде відбуватися занадто часто.
100
101 В такому випадку можна прописати токени в змінних оточення (файл {{code language="none"}}.env.local{{/code}} під час локальної розробки). Цей механізм достатньо безпечний з боку збереження доступів.
102
103 (((
104 {{code language="ini" layout="LINENUMBERS" title=".env.local"}}
105 TOKEN_FOR_APP_1=9363074966579432364f8b73b3318f71
106 TOKEN_FOR_APP_2=456fg87g8h98jmnb8675r4445n8up365
107 {{/code}}
108
109 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
110 ufo_json_rpc:
111 security:
112 protected_methods: ['GET', 'POST']
113 token_key_in_header: 'Ufo-RPC-Token'
114 clients_tokens:
115 - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
116 - '%env(resolve:TOKEN_FOR_APP_2)%' # token example from .env.local
117 {{/code}}
118 )))
119
120 === Токени для користувача ===
121
122 Припускаю, що у вас може виникнути потреба зробити персональні ключі для користувачів вашого додатку, можливо ви захочете впровадити ліміти або інші обмеження.
123 В такому випадку вам не потрібно вказувати перелік токенів в конфігах, ви можете зберігати їх в базі даних або іншому місці згідно вашій бізнес-логіки. Єдина вимога, у вас має бути сервіс, який вміє перевіряти чи існує наданий токен.
124
125 Для того, щоб JsonRpcServer міг використовувати вашу логіку, доведеться реалізувати власний клас, що реалізує інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator{{/code}}
126
127 {{code language="php" layout="LINENUMBERS" title="==== Приклад власного валідатора токенів ===="}}
128 <?php
129
130 namespace App\Services\RpcSecurity;
131
132 use App\Services\UserService;
133 use Symfony\Component\Security\Core\Exception\UserNotFoundException;
134 use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
135 use Ufo\RpcError\RpcInvalidTokenException;
136
137 class UserTokenValidator implements ITokenValidator
138 {
139
140 public function __construct(protected UserService $userService) {}
141
142 public function isValid(string $token): true
143 {
144 try {
145 $this->userService->getUserByToken($token);
146 return true;
147 } catch (UserNotFoundException $e) {
148 throw new RpcInvalidTokenException(previous: $e);
149 }
150 }
151 }
152 {{/code}}
153
154 (% class="box warningmessage" %)
155 (((
156 **ВАЖЛИВО!!!**
157 Метод {{code language="none"}}isValid{{/code}} має повертати {{code language="none"}}true{{/code}} якщо токен існує і валідний, або викидати {{code language="none"}}Ufo\RpcError\RpcInvalidTokenException{{/code}} в іншому разі.
158 )))
159
160 Після цього вам потрібно в файлі {{code language="none"}}config/services.yaml{{/code}} прописати що класи, що мають залежність від інтерфейса {{code language="none"}}ITokenValidator{{/code}} мають приймати ваш новий клас.
161
162 {{code language="yaml" layout="LINENUMBERS" title="config/services.yaml"}}
163 parameters:
164 # some parameters list
165 # ...
166
167 services:
168 # some services list
169 # ...
170
171 Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
172 class: App\Services\RpcSecurity\UserTokenValidator
173 {{/code}}
174
175 = Блок {{code language="none"}}async{{/code}} =
176
177 Цей блок для налаштування [[асинхронного транспорту>>doc:docs.JsonRpcBundle.functionality.async.WebHome]].
178
179 Додайте параметр {{code language="none"}}rpc_async{{/code}} який містить рядок у форматі DSN. Цей рядок є конфігурацією [[Symfony Messenger>>https://symfony.com/doc/current/messenger.html]], він вказує на асинхронний транспорт по якому RPC Server буде очікувати вхідні запити якщо у вас запущений консюмер ({{code language="none"}}php bin/console messenger:consume rpc_async{{/code}}). Для більш детального розуміння цього процесу читайте документацію [[Symfony Messenge>>https://symfony.com/doc/current/messenger.html]].
180
181 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
182 ufo_json_rpc:
183 async:
184 rpc_async: '%env(resolve:RPC_TRANSPORT_DSN)%'
185
186 {{/code}}
187
188 (% class="box warningmessage" %)
189 (((
190 Це налаштування має на увазі, що у вас в змінних оточення встановлена змінна RPC_TRANSPORT_DSN що містить DSN рядок.
191 )))
192
193 = Блок {{code language="none"}}docs{{/code}} =
194
195 Це блок який налаштовує генерацію документації коли ви робите GET запит на RPC Server
196
197 == Секція {{code language="none"}}response{{/code}} ==
198
199 Містить налаштування, що відповідають за вміст відповіді.
200
201 === Параметр {{code language="none"}}key_for_methods{{/code}} ===
202
203 Цей параметр дозволяє вказати назву ключа у відповіді в якій буде віддаватися масив доступних сервісів.
204
205 Значення за замовченням {{code language="none"}}methods{{/code}}. Може мати будь-яке значення типу рядок.
206
207 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
208 ufo_json_rpc:
209 docs:
210 key_for_methods: methods
211 {{/code}}
212
213 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
214 ufo_json_rpc:
215 docs:
216 key_for_methods: services
217 {{/code}}
218
219 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
220 ufo_json_rpc:
221 docs:
222 key_for_methods: some_custom_key
223 {{/code}}
224
225 === Параметр {{code language="none"}}async_dsn_info{{/code}} ===
226
227 Відповідає за відображення в документації інформації про асинхронний транспорт.
228
229 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
230 ufo_json_rpc:
231 async_dsn_info: true # or false
232 {{/code}}
233
234 ==== **Приклад документації ** ====
235
236 {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
237 {
238 "envelope": "JSON-RPC-2.0/UFO-RPC-6",
239 "contentType": "application/json",
240 "description": "",
241 "transport": {
242 "sync": {
243 "scheme": "http",
244 "host": "example.com",
245 "path": "/api",
246 "method": "POST"
247 },
248 "async": {
249 "scheme": "amqp",
250 "user": "{user}",
251 "pass": "{pass}",
252 "host": "async_rabbit",
253 "port": 5672,
254 "path": "/%2f/json-rpc"
255 }
256 },
257 "methods": {
258 ...
259 }
260 }
261 {{/code}}
262
263 {{info}}
264 Не переймайтеся щодо безпеки ваших авторизаційних даних. що містяться в DSN.
265
266 Документатор побудований таким чином, що перед виводом інформації про DSN він видаляє дані про користувача і його пароль, а також інші секретні дані, як то токени, секретні ключі, тощо.
267
268 Шаблон, по якому відбувається захист {{code language="none"}}/([\w\d_]*(?:secret|access|token|key)[_\w]*)=((?:\w|\d)+(?=&?))/{{/code}}.
269
270 Приклад:
271
272 {{code language="json" layout="LINENUMBERS" title="RPC_TRANSPORT_DSN=https://sqs.eu-west-3.amazonaws.com/123456789012/messages?access_key=AKIAIOSFODNN7EXAMPLE&secret_key=j17M97ffSVoKI0briFoo9a"}}
273 {
274 "async": {
275 "scheme": "https",
276 "host": "sqs.eu-west-3.amazonaws.com",
277 "path": "/123456789012/messages",
278 "query": "access_key={access_key}&secret_key={secret_key}"
279 }
280 }
281 {{/code}}
282 {{/info}}
283
284 === Параметр {{code language="none"}}validations{{/code}} ===
285
286 Відповідає за відображення в документації методів додаткових блоків, що вказують на вимоги до валідації даних.
287
288 Наразі цей блок має два можливих налаштування:
289
290 * {{code language="none"}}json_schema: <bool>{{/code}}
291 * {{code language="none"}}symfony_asserts: <bool>{{/code}}
292
293 У всіх опцій в цьому параметрі значення за замовченням {{code language="none"}}false{{/code}}, тобто ці блоки не будуть відображатися в документації.
294 Якщо ви потребуєте якийсь з цих блоків інформації при запиті документації, то встановіть значення в {{code language="none"}}true{{/code}}.
295
296 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
297 ufo_json_rpc:
298 docs:
299 json_schema: true
300 symfony_asserts: true
301 {{/code}}
302
303 ==== **Приклад документації ** ====
304
305 (% class="box infomessage" %)
306 (((
307 В цьому прикладі я видалив вміст обʼєктів symfony_assertions для спрощення прикладу.
308 Детальніше про валідацію методів дивись сторінку **[[Валідація процедур>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]]**
309 )))
310
311 {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
312 {
313 "envelope": "JSON-RPC-2.0/UFO-RPC-6",
314 "contentType": "application/json",
315 "description": "",
316 "transport": {
317 "sync": {
318 "scheme": "https",
319 "host": "example.com",
320 "path": "/api",
321 "method": "POST"
322 }
323 },
324 "methods": {
325 "getUserNameByUuid": {
326 "name": "getUserNameByUuid",
327 "description": "Get username by id",
328 "parameters": {
329 "userId": {
330 "type": "string",
331 "name": "userId",
332 "description": "User id in uuid format",
333 "optional": false
334 }
335 },
336 "returns": "string",
337 "responseFormat": "string",
338 "json_schema": {
339 "$schema": "http://json-schema.org/draft-07/schema#",
340 "type": "object",
341 "properties": {
342 "userId": {
343 "type": "string"
344 }
345 },
346 "required": [
347 "userId"
348 ]
349 },
350 "symfony_assertions": {
351 "userId": [
352 {
353 "class": "Symfony\\Component\\Validator\\Constraints\\Uuid",
354 "context": {}
355 }
356 ]
357 }
358 },
359 "sendEmail": {
360 "name": "sendEmail",
361 "description": "Send mail",
362 "parameters": {
363 "email": {
364 "type": "string",
365 "name": "email",
366 "description": "",
367 "optional": false
368 },
369 "subject": {
370 "type": "string",
371 "name": "subject",
372 "description": "",
373 "optional": false
374 },
375 "text": {
376 "type": "string",
377 "name": "text",
378 "description": "",
379 "optional": false
380 }
381 },
382 "returns": "boolean",
383 "responseFormat": "boolean",
384 "json_schema": {
385 "$schema": "http://json-schema.org/draft-07/schema#",
386 "type": "object",
387 "properties": {
388 "email": {
389 "type": "string",
390 "format": "email"
391 },
392 "subject": {
393 "type": "string",
394 "minLength": 1,
395 "maxLength": 100
396 },
397 "text": {
398 "type": "string",
399 "minLength": 10
400 }
401 },
402 "required": [
403 "email",
404 "subject",
405 "text"
406 ]
407 },
408 "symfony_assertions": {
409 "email": [
410 {
411 "class": "Symfony\\Component\\Validator\\Constraints\\Email",
412 "context": {}
413 }
414 ],
415 "subject": [
416 {
417 "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
418 "context": {}
419 },
420 {
421 "class": "Symfony\\Component\\Validator\\Constraints\\Length",
422 "context": {}
423 }
424 ],
425 "text": [
426 {
427 "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
428 "context": {}
429 },
430 {
431 "class": "Symfony\\Component\\Validator\\Constraints\\Length",
432 "context": {}
433 }
434 ]
435 }
436 }
437 }
438 }
439 {{/code}}