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