Зміни в документі 2. Налаштування бандла

Остання зміна 2024/07/11 11:49 автором Ashterix
Від версії 1.1
редаговано Ashterix
дата 2024/07/11 09:57
Змінити коментар: Немає коментарів для цієї версії
До версії 4.1
редаговано Ashterix
дата 2024/07/11 11:41
Змінити коментар: Немає коментарів для цієї версії

Підсумок

Подробиці

Властивості сторінки
Назва
... ... @@ -1,1 +1,1 @@
1 -2. Налаштування бандлу (актуальна версія)
1 +2. Налаштування бандла
Вміст
... ... @@ -1,0 +1,318 @@
1 +{{box cssClass="floatinginfobox" title="**Зміст**"}}
2 +{{toc/}}
3 +{{/box}}
4 +
5 +{{info}}
6 +Конфігурація зазнала суттєвих змін і не має зворотної сумісності з версією 6.
7 +{{/info}}
8 +
9 +(% class="wikigeneratedid" %)
10 +Всі налаштування бандла знаходяться в файлі {{code language="none"}}config/packages/ufo_json_rpc.yaml{{/code}}.
11 +
12 +(% class="wikigeneratedid" %)
13 +Є можливість налаштувати параметри захисту API та деякі параметри формату даних, що віддається при запиті документації.
14 +
15 += Блок {{code language="none"}}security{{/code}} =
16 +
17 +Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
18 +
19 +== Параметри {{code language="none"}}protected_api{{/code}} та {{code language="none"}}protected_doc{{/code}} (boolean) ==
20 +
21 +(% class="wikigeneratedid" %)
22 +Ці параметри вказує чи мають бути захищені API методи та документація, відповідно.
23 +
24 +(% class="wikigeneratedid" %)
25 +За замовченням апі методи захищені, а документація відкрита.
26 +
27 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
28 +ufo_json_rpc:
29 + security:
30 + protected_api: true # Protection API requests
31 + protected_doc: false # Protection API documentation
32 +{{/code}}
33 +
34 +(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_api{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
35 +
36 +Перш за все, треба визначитися з назвою токену.
37 +
38 +== Параметр {{code language="none"}}token_name{{/code}} ==
39 +
40 +Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_name: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
41 +
42 +{{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
43 +Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
44 +
45 +- Капіталізація: Зазвичай назви HTTP заголовків пишуться з використанням CamelCase, де кожне слово починається з великої літери, наприклад, Content-Type, User-Agent, Accept-Encoding. Це не впливає на технічну обробку заголовків, але робить їх легше читати.
46 +- Унікальність: Кожен заголовок повинен мати унікальну назву у контексті одного HTTP запиту або відповіді. Не можна використовувати однакові назви для різних заголовків у тому самому запиті чи відповіді.
47 +- Спеціальні заголовки: Існують заголовки, які використовуються специфічно для контролю поведінки кешування (Cache-Control), безпеки (Strict-Transport-Security), аутентифікації (Authorization), тощо.
48 +- Норми RFC: Вимоги до заголовків регулюються документами RFC, які визначають стандарти для протоколів Інтернету. Наприклад, загальні заголовки і їхнє використання описані в RFC 7231.
49 +{{/spoiler}}
50 +
51 +
52 +
53 +
54 +
55 +
56 +
57 +
58 +
59 +
60 +
61 +
62 +
63 +
64 +
65 +
66 +
67 +
68 +
69 +Параметр {{code language="none"}}clients_tokens{{/code}}
70 +
71 +Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
72 +
73 +Тут є певна варіативність.
74 +
75 +=== Токени в параметрах ===
76 +
77 +(% class="box errormessage" %)
78 +(((
79 +**НЕ РЕКОМЕНДОВАНО!!!**
80 +\\Цей підхід допускається лише для локального тестування API
81 +)))
82 +
83 +Є можливість прописати токени хардкодом прямо в файлі налаштувань.
84 +
85 +Це погано з позиції безпеки, якщо код зберігається в публічному репозиторію, то до цього токену буде мати доступ кожен.
86 +
87 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
88 +ufo_json_rpc:
89 + security:
90 + token_name: '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 + token_key_in_header: 'Ufo-RPC-Token'
112 + clients_tokens:
113 + - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
114 + - '%env(resolve:TOKEN_FOR_APP_2)%' # token example from .env.local
115 +{{/code}}
116 +)))
117 +
118 +=== Токени для користувача ===
119 +
120 +Припускаю, що у вас може виникнути потреба зробити персональні ключі для користувачів вашого додатку, можливо ви захочете впровадити ліміти або інші обмеження.
121 +В такому випадку вам не потрібно вказувати перелік токенів в конфігах, ви можете зберігати їх в базі даних або іншому місці згідно вашій бізнес-логіки. Єдина вимога, у вас має бути сервіс, який вміє перевіряти чи існує наданий токен.
122 +
123 +Для того, щоб JsonRpcServer міг використовувати вашу логіку, доведеться реалізувати власний клас, що реалізує інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator{{/code}}
124 +
125 +{{code language="php" layout="LINENUMBERS" title="==== Приклад власного валідатора токенів ===="}}
126 +<?php
127 +
128 +namespace App\Services\RpcSecurity;
129 +
130 +use App\Services\UserService;
131 +use Symfony\Component\Security\Core\Exception\UserNotFoundException;
132 +use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
133 +use Ufo\RpcError\RpcInvalidTokenException;
134 +
135 +class UserTokenValidator implements ITokenValidator
136 +{
137 +
138 + public function __construct(protected UserService $userService) {}
139 +
140 + public function isValid(string $token): true
141 + {
142 + try {
143 + $this->userService->getUserByToken($token);
144 + return true;
145 + } catch (UserNotFoundException $e) {
146 + throw new RpcInvalidTokenException(previous: $e);
147 + }
148 + }
149 +}
150 +{{/code}}
151 +
152 +(% class="box warningmessage" %)
153 +(((
154 +**ВАЖЛИВО!!!**
155 +Метод {{code language="none"}}isValid{{/code}} має повертати {{code language="none"}}true{{/code}} якщо токен існує і валідний, або викидати {{code language="none"}}Ufo\RpcError\RpcInvalidTokenException{{/code}} в іншому разі.
156 +)))
157 +
158 +Після цього вам потрібно в файлі {{code language="none"}}config/services.yaml{{/code}} прописати що класи, що мають залежність від інтерфейса {{code language="none"}}ITokenValidator{{/code}} мають приймати ваш новий клас.
159 +
160 +{{code language="yaml" layout="LINENUMBERS" title="config/services.yaml"}}
161 +parameters:
162 + # some parameters list
163 + # ...
164 +
165 +services:
166 + # some services list
167 + # ...
168 +
169 + Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
170 + class: App\Services\RpcSecurity\UserTokenValidator
171 +{{/code}}
172 +
173 += Блок {{code language="none"}}async{{/code}} =
174 +
175 +Цей блок для налаштування [[асинхронного транспорту>>doc:docs.JsonRpcBundle.functionality.async.WebHome]].
176 +
177 +Додайте параметр {{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]].
178 +
179 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
180 +ufo_json_rpc:
181 + async:
182 + rpc_async: '%env(resolve:RPC_TRANSPORT_DSN)%'
183 +
184 +{{/code}}
185 +
186 +(% class="box warningmessage" %)
187 +(((
188 +Це налаштування має на увазі, що у вас в змінних оточення встановлена змінна RPC_TRANSPORT_DSN що містить DSN рядок.
189 +)))
190 +
191 += Блок {{code language="none"}}docs{{/code}} =
192 +
193 +Цей блок налаштовує деякі параметри генерації документації коли ви робите GET запит на RPC Server.
194 +
195 +(% class="box infomessage" %)
196 +(((
197 +Починаючи з версії 7, JsonRpcBundle генерує API документацію, що відповідає специфікації [[OpenRpc>>https://spec.open-rpc.org/]]
198 +)))
199 +
200 +* {{code language="none"}}project_name{{/code}}: Назва проєкту, що буде відображена в документації
201 +* {{code language="none"}}project_description{{/code}}: Опис проєкту
202 +* {{code language="none"}}project_version{{/code}}: Поточна версія вашого API
203 +* {{code language="none"}}async_dsn_info{{/code}}: Відповідає за відображення в документації інформації про асинхронний транспорт
204 +* (% id="cke_bm_826282S" style="display:none" %){{code language="none"}}validations.symfony_asserts{{/code}}(%%): <bool> Відповідає за відображення рядку очікувань валідації для параметра (якщо ви використовуєте [[валідацію>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]])
205 +
206 +{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
207 +ufo_json_rpc:
208 + docs:
209 + project_name: 'My Project'
210 + project_description: 'My project description'
211 + project_version: '1.0'
212 + # Optional response details
213 + async_dsn_info: false # Provide information about API that work asynchronously
214 + validations:
215 + symfony_asserts: false # Indicates if an array of Symfony validation constraints is used
216 +
217 +{{/code}}
218 +
219 +{{info}}
220 +Не переймайтеся щодо безпеки ваших авторизаційних даних, що містяться в DSN.
221 +
222 +Документатор побудований таким чином, що перед виводом інформації про DSN він видаляє дані про користувача і його пароль, а також інші секретні дані, як то токени, секретні ключі, тощо.
223 +
224 +Шаблон, по якому відбувається захист {{code language="none"}}/([\w\d_]*(?:secret|access|token|key)[_\w]*)=((?:\w|\d)+(?=&?))/{{/code}}.
225 +
226 +Приклад:
227 +
228 +{{code language="json" layout="LINENUMBERS" title="RPC_TRANSPORT_DSN=https://sqs.eu-west-3.amazonaws.com/123456789012/messages?access_key=AKIAIOSFODNN7EXAMPLE&secret_key=j17M97ffSVoKI0briFoo9a"}}
229 +{
230 + "async": {
231 + "scheme": "https",
232 + "host": "sqs.eu-west-3.amazonaws.com",
233 + "path": "/123456789012/messages",
234 + "query": "access_key={access_key}&secret_key={secret_key}"
235 + }
236 +}
237 +{{/code}}
238 +{{/info}}
239 +
240 +=== Приклад документації ===
241 +
242 +{{code language="json" layout="LINENUMBERS" title="GET: /api"}}
243 +{
244 + "openrpc":"1.2.6",
245 + "info":{
246 + "title":"My Project",
247 + "description":"My project description",
248 + "contact":{
249 + "name":"ufo-tech/json-rpc-bundle",
250 + "url":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
251 + },
252 + "license":{
253 + "name":"MIT"
254 + },
255 + "version":"1.0"
256 + },
257 + "servers":[
258 + {
259 + "url":"https://mysite.com/api",
260 + "description":"Json-RPC api server from UFO Tec\n\nUFO Tech, or Universal Flexible Open Technologies, is an initiative aimed at providing PHP developers with tools to create complex yet user-friendly solutions for modern web applications and service-oriented architectures.",
261 + "name":"UFO Json-RPC Server v.7.0.0",
262 + "x-method":"POST",
263 + "x-ufo":{
264 + "envelop":"JSON-RPC-2.0/UFO-RPC-7.0.0",
265 + "transport":{
266 + "sync":{
267 + "scheme":"https",
268 + "host":"mysite.com",
269 + "path":"/api",
270 + "method":"POST"
271 + },
272 + "async":{
273 + "scheme":"amqp",
274 + "user":"{user}",
275 + "pass":"{pass}",
276 + "host":"mysite.com",
277 + "port":5672,
278 + "path":"/%2f/json-rpc"
279 + }
280 + },
281 + "documentation":{
282 + "json-rpc":"https://www.jsonrpc.org/specification",
283 + "ufo-tech/json-rpc-bundle":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
284 + }
285 + }
286 + }
287 + ],
288 + "methods":[
289 + {
290 + "name":"getUserNameByUuid",
291 + "tags":[
292 + {
293 + "name":"App\\Api\\UserApiService"
294 + }
295 + ],
296 + "summary":"Get username by id",
297 + "params":[
298 + {
299 + "name":"userId",
300 + "description":"User Id format uuid",
301 + "required":true,
302 + "schema":{
303 + "type":"string"
304 + },
305 + "x-ufo-assertions": "new Assert\\Uuid()"
306 + }
307 + ],
308 + "result":{
309 + "name":"string",
310 + "description":"User Name",
311 + "schema":{
312 + "type":"string"
313 + }
314 + }
315 + }
316 + ]
317 +}
318 +{{/code}}