Версія 19.3 додана 2024/05/16 11:03 автором 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
60
61
62 == Параметр {{code language="none"}}clients_tokens{{/code}} ==
63
64 Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
65
66 Тут є певна варіативність.
67
68 === Токени в параметрах ===
69
70 (% class="box errormessage" %)
71 (((
72 **НЕ РЕКОМЕНДОВАНО!!!**
73 \\Цей підхід допускається лише для локального тестування API
74 )))
75
76 Є можливість прописати токени хардкодом прямо в файлі налаштувань.
77
78 Це погано з позиції безпеки, якщо код зберігається в публічному репозиторію, то до цього токену буде мати доступ кожен.
79
80 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
81 ufo_json_rpc:
82 security:
83 protected_methods: ['GET', 'POST']
84 token_key_in_header: 'Ufo-RPC-Token'
85 clients_tokens:
86 - 'ClientTokenExample' # hardcoded token example. Importantly!!! Replace or delete it!
87
88 {{/code}}
89
90 === Токени в змінних оточення ===
91
92 Це найбільш доцільний механізм у разі, якщо ви розробляєте сервіс для розподіленого бекенду, що написаний на SOA (Сервіс-Орієнтована Архітектура). Зазвичай, в такому випадку, вам треба відкрити доступ до апі одному або обмеженій кількості клієнтських додатків і оновлення ключів не буде відбуватися занадто часто.
93
94 В такому випадку можна прописати токени в змінних оточення (файл {{code language="none"}}.env.local{{/code}} під час локальної розробки). Цей механізм достатньо безпечний з боку збереження доступів.
95
96 (((
97 {{code language="ini" layout="LINENUMBERS" title=".env.local"}}
98 TOKEN_FOR_APP_1=9363074966579432364f8b73b3318f71
99 TOKEN_FOR_APP_2=456fg87g8h98jmnb8675r4445n8up365
100 {{/code}}
101
102 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
103 ufo_json_rpc:
104 security:
105 protected_methods: ['GET', 'POST']
106 token_key_in_header: 'Ufo-RPC-Token'
107 clients_tokens:
108 - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
109 - '%env(resolve:TOKEN_FOR_APP_2)%' # token example from .env.local
110 {{/code}}
111 )))
112
113 === Токени для користувача ===
114
115 Припускаю, що у вас може виникнути потреба зробити персональні ключі для користувачів вашого додатку, можливо ви захочете впровадити ліміти або інші обмеження.
116 В такому випадку вам не потрібно вказувати перелік токенів в конфігах, ви можете зберігати їх в базі даних або іншому місці згідно вашій бізнес-логіки. Єдина вимога, у вас має бути сервіс, який вміє перевіряти чи існує наданий токен.
117
118 Для того, щоб JsonRpcServer міг використовувати вашу логіку, доведеться реалізувати власний клас, що реалізує інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator{{/code}}
119
120 {{code language="php" layout="LINENUMBERS" title="==== Приклад власного валідатора токенів ===="}}
121 <?php
122
123 namespace App\Services\RpcSecurity;
124
125 use App\Services\UserService;
126 use Symfony\Component\Security\Core\Exception\UserNotFoundException;
127 use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
128 use Ufo\RpcError\RpcInvalidTokenException;
129
130 class UserTokenValidator implements ITokenValidator
131 {
132
133 public function __construct(protected UserService $userService) {}
134
135 public function isValid(string $token): true
136 {
137 try {
138 $this->userService->getUserByToken($token);
139 return true;
140 } catch (UserNotFoundException $e) {
141 throw new RpcInvalidTokenException(previous: $e);
142 }
143 }
144 }
145 {{/code}}
146
147 (% class="box warningmessage" %)
148 (((
149 **ВАЖЛИВО!!!**
150 Метод {{code language="none"}}isValid{{/code}} має повертати {{code language="none"}}true{{/code}} якщо токен існує і валідний, або викидати {{code language="none"}}Ufo\RpcError\RpcInvalidTokenException{{/code}} в іншому разі.
151 )))
152
153 Після цього вам потрібно в файлі {{code language="none"}}config/services.yaml{{/code}} прописати що класи, що мають залежність від інтерфейса {{code language="none"}}ITokenValidator{{/code}} мають приймати ваш новий клас.
154
155 {{code language="yaml" layout="LINENUMBERS" title="config/services.yaml"}}
156 parameters:
157 # some parameters list
158 # ...
159
160 services:
161 # some services list
162 # ...
163
164 Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
165 class: App\Services\RpcSecurity\UserTokenValidator
166 {{/code}}
167
168 = (% id="cke_bm_29916S" style="display:none" %) (%%)Блок {{code language="none"}}async{{/code}} =
169
170 Цей блок для налаштування [[асинхронного транспорту>>doc:.functionality.async.WebHome]].
171
172 Додайте параметр {{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]].
173
174 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
175 ufo_json_rpc:
176 async:
177 rpc_async: '%env(resolve:RPC_TRANSPORT_DSN)%'
178
179 {{/code}}
180
181 = Блок {{code language="none"}}docs{{/code}} =
182
183 Це блок який налаштовує генерацію документації коли ви робите GET запит на RPC Server
184
185 == Секція {{code language="none"}}response{{/code}} ==
186
187 Містить налаштування, що відповідають за вміст відповіді.
188
189 === Параметр {{code language="none"}}key_for_methods{{/code}} ===
190
191 Цей параметр дозволяє вказати назву ключа у відповіді в якій буде віддаватися масив доступних сервісів.
192
193 Значення за замовченням {{code language="none"}}methods{{/code}}. Може мати будь-яке значення типу рядок.
194
195 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
196 ufo_json_rpc:
197 docs:
198 key_for_methods: methods
199 {{/code}}
200
201 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
202 ufo_json_rpc:
203 docs:
204 key_for_methods: services
205 {{/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: some_custom_key
211 {{/code}}
212
213 === Параметр {{code language="none"}}validations{{/code}} ===
214
215 Відповідає за відображення в документації методів додаткових блоків, що вказують на вимоги до валідації даних.
216
217 Наразі цей блок має два можливих налаштування:
218
219 * {{code language="none"}}json_schema: <bool>{{/code}}
220 * {{code language="none"}}symfony_asserts: <bool>{{/code}}
221
222 У всіх опцій в цьому параметрі значення за замовченням {{code language="none"}}false{{/code}}, тобто ці блоки не будуть відображатися в документації.
223 Якщо ви потребуєте якийсь з цих блоків інформації при запиті документації, то встановіть значення в {{code language="none"}}true{{/code}}.
224
225 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
226 ufo_json_rpc:
227 docs:
228 json_schema: true
229 symfony_asserts: true
230 {{/code}}
231
232 ==== **Приклад документації ** ====
233
234 (% class="box infomessage" %)
235 (((
236 В цьому прикладі я видалив вміст обʼєктів symfony_assertions для спрощення прикладу.
237 Детальніше про валідацію методів дивись сторінку **[[Валідація процедур>>doc:.add_rpc_service.assertions.WebHome]]**
238 )))
239
240 {{code language="json" layout="LINENUMBERS" title="GET: /api"}}
241 {
242 "envelope": "JSON-RPC-2.0/UFO-RPC-6",
243 "contentType": "application/json",
244 "description": "",
245 "transport": {
246 "sync": {
247 "scheme": "https",
248 "host": "example.com",
249 "path": "/api",
250 "method": "POST"
251 }
252 },
253 "methods": {
254 "getUserNameByUuid": {
255 "name": "getUserNameByUuid",
256 "description": "Get username by id",
257 "parameters": {
258 "userId": {
259 "type": "string",
260 "name": "userId",
261 "description": "User id in uuid format",
262 "optional": false
263 }
264 },
265 "returns": "string",
266 "responseFormat": "string",
267 "json_schema": {
268 "$schema": "http://json-schema.org/draft-07/schema#",
269 "type": "object",
270 "properties": {
271 "userId": {
272 "type": "string"
273 }
274 },
275 "required": [
276 "userId"
277 ]
278 },
279 "symfony_assertions": {
280 "userId": [
281 {
282 "class": "Symfony\\Component\\Validator\\Constraints\\Uuid",
283 "context": {}
284 }
285 ]
286 }
287 },
288 "sendEmail": {
289 "name": "sendEmail",
290 "description": "Send mail",
291 "parameters": {
292 "email": {
293 "type": "string",
294 "name": "email",
295 "description": "",
296 "optional": false
297 },
298 "subject": {
299 "type": "string",
300 "name": "subject",
301 "description": "",
302 "optional": false
303 },
304 "text": {
305 "type": "string",
306 "name": "text",
307 "description": "",
308 "optional": false
309 }
310 },
311 "returns": "boolean",
312 "responseFormat": "boolean",
313 "json_schema": {
314 "$schema": "http://json-schema.org/draft-07/schema#",
315 "type": "object",
316 "properties": {
317 "email": {
318 "type": "string",
319 "format": "email"
320 },
321 "subject": {
322 "type": "string",
323 "minLength": 1,
324 "maxLength": 100
325 },
326 "text": {
327 "type": "string",
328 "minLength": 10
329 }
330 },
331 "required": [
332 "email",
333 "subject",
334 "text"
335 ]
336 },
337 "symfony_assertions": {
338 "email": [
339 {
340 "class": "Symfony\\Component\\Validator\\Constraints\\Email",
341 "context": {}
342 }
343 ],
344 "subject": [
345 {
346 "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
347 "context": {}
348 },
349 {
350 "class": "Symfony\\Component\\Validator\\Constraints\\Length",
351 "context": {}
352 }
353 ],
354 "text": [
355 {
356 "class": "Symfony\\Component\\Validator\\Constraints\\NotBlank",
357 "context": {}
358 },
359 {
360 "class": "Symfony\\Component\\Validator\\Constraints\\Length",
361 "context": {}
362 }
363 ]
364 }
365 }
366 }
367 }
368 {{/code}}