Остання зміна 2024/07/11 10:07 автором Ashterix
Показати останніх авторів
1 {{box cssClass="floatinginfobox" title="**Зміст**"}}
2 {{toc/}}
3 {{/box}}
4
5 {{error}}
6 **УВАГА!!! **Ця версія документації застаріла.
7
8 В JsonRpcBundle версії 7 конфігурація зазнала суттєвих змін і не має зворотної сумісності з версією 6.
9 {{/error}}
10
11 (% class="wikigeneratedid" %)
12 Всі налаштування бандла знаходяться в файлі {{code language="none"}}config/packages/ufo_json_rpc.yaml{{/code}}.
13
14 (% class="wikigeneratedid" %)
15 Є можливість налаштувати параметри захисту API та деякі параметри формату даних, що віддається при запиті документації.
16
17 = Блок {{code language="none"}}security{{/code}} =
18
19 Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
20
21 == Параметр {{code language="none"}}protected_methods{{/code}} ==
22
23 (% class="wikigeneratedid" %)
24 Цей параметр приймає масив назв http методів, які мають бути захищені.
25
26 (% class="wikigeneratedid" %)
27 За замовченням ввімкнут захист лише для методу POST. Ви можете:
28
29 * вказати пустий масив {{code language="none"}}[]{{/code}} щоб зробити API повністю відкритим
30
31 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
32 ufo_json_rpc:
33 security:
34 protected_methods: []
35 {{/code}}
36
37 * вказати додатково захист для методу GET, що зробить запит документації недоступним без токену в заголовках запиту
38
39 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
40 ufo_json_rpc:
41 security:
42 protected_methods: ['GET', 'POST']
43 {{/code}}
44
45 (% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_methods{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
46
47 Перш за все, треба визначитися з назвою токену.
48
49 == Параметр {{code language="none"}}token_key_in_header{{/code}} ==
50
51 Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_key_in_header: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
52
53 {{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
54 Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
55
56 - Капіталізація: Зазвичай назви HTTP заголовків пишуться з використанням CamelCase, де кожне слово починається з великої літери, наприклад, Content-Type, User-Agent, Accept-Encoding. Це не впливає на технічну обробку заголовків, але робить їх легше читати.
57 - Унікальність: Кожен заголовок повинен мати унікальну назву у контексті одного HTTP запиту або відповіді. Не можна використовувати однакові назви для різних заголовків у тому самому запиті чи відповіді.
58 - Спеціальні заголовки: Існують заголовки, які використовуються специфічно для контролю поведінки кешування (Cache-Control), безпеки (Strict-Transport-Security), аутентифікації (Authorization), тощо.
59 - Норми RFC: Вимоги до заголовків регулюються документами RFC, які визначають стандарти для протоколів Інтернету. Наприклад, загальні заголовки і їхнє використання описані в RFC 7231.
60 {{/spoiler}}
61
62
63
64
65
66
67
68 == Параметр {{code language="none"}}clients_tokens{{/code}} ==
69
70 Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
71
72 Тут є певна варіативність.
73
74 === Токени в параметрах ===
75
76 (% class="box errormessage" %)
77 (((
78 **НЕ РЕКОМЕНДОВАНО!!!**
79 \\Цей підхід допускається лише для локального тестування API
80 )))
81
82 Є можливість прописати токени хардкодом прямо в файлі налаштувань.
83
84 Це погано з позиції безпеки, якщо код зберігається в публічному репозиторію, то до цього токену буде мати доступ кожен.
85
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}}
95
96 === Токени в змінних оточення ===
97
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"}}
109 ufo_json_rpc:
110 security:
111 protected_methods: ['GET', 'POST']
112 token_key_in_header: 'Ufo-RPC-Token'
113 clients_tokens:
114 - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
115 - '%env(resolve:TOKEN_FOR_APP_2)%' # token example from .env.local
116 {{/code}}
117 )))
118
119 === Токени для користувача ===
120
121 Припускаю, що у вас може виникнути потреба зробити персональні ключі для користувачів вашого додатку, можливо ви захочете впровадити ліміти або інші обмеження.
122 В такому випадку вам не потрібно вказувати перелік токенів в конфігах, ви можете зберігати їх в базі даних або іншому місці згідно вашій бізнес-логіки. Єдина вимога, у вас має бути сервіс, який вміє перевіряти чи існує наданий токен.
123
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}}