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