Зміни в документі Версія 6: Налаштування

Остання зміна 2024/07/11 10:07 автором Ashterix
Від версії 5.1
редаговано Ashterix
дата 2024/05/08 22:30
Змінити коментар: Немає коментарів для цієї версії
До версії 25.1
редаговано Ashterix
дата 2024/07/11 10:07
Змінити коментар: Немає коментарів для цієї версії

Підсумок

Подробиці

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