Версія 15.1 додана 2024/05/09 18:13 автором 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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72 == {{code language="none"}}clients_tokens{{/code}} ==
73
74 Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
75
76 Тут є певна варіативність.
77
78 === Токени в параметрах ===
79
80 (% class="box errormessage" %)
81 (((
82 **НЕ РЕКОМЕНДОВАНО!!!**
83 \\Цей підхід допускається лише для локального тестування API
84 )))
85
86 Є можливість прописати токени хардкодом прямо в файлі налаштувань.
87
88 Це погано з позиції безпеки, якщо код зберігається в публічному репозиторію, то до цього токену буде мати доступ кожен.
89
90 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
91 ufo_json_rpc:
92 security:
93 protected_methods: ['GET', 'POST']
94 token_key_in_header: 'Ufo-RPC-Token'
95 clients_tokens:
96 - 'ClientTokenExample' # hardcoded token example. Importantly!!! Replace or delete it!
97
98 {{/code}}
99
100 === Токени в змінних оточення ===
101
102 Це найбільш доцільний механізм у разі, якщо ви розробляєте сервіс для розподіленого бекенду, що написаний на SOA (Сервіс-Орієнтована Архітектура). Зазвичай, в такому випадку, вам треба відкрити доступ до апі одному або обмеженій кількості клієнтських додатків і оновлення ключів не буде відбуватися занадто часто.
103
104 В такому випадку можна прописати токени в змінних оточення (файл {{code language="none"}}.env.local{{/code}} під час локальної розробки). Цей механізм достатньо безпечний з боку збереження доступів.
105
106 (((
107 {{code language="ini" layout="LINENUMBERS" title=".env.local"}}
108 TOKEN_FOR_APP_1=9363074966579432364f8b73b3318f71
109 TOKEN_FOR_APP_2=456fg87g8h98jmnb8675r4445n8up365
110 {{/code}}
111
112 {{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
113 ufo_json_rpc:
114 security:
115 protected_methods: ['GET', 'POST']
116 token_key_in_header: 'Ufo-RPC-Token'
117 clients_tokens:
118 - '%env(resolve:TOKEN_FOR_APP_1)%' # token example from .env.local
119 - '%env(resolve:TOKEN_FOR_APP_2)%' # token example from .env.local
120 {{/code}}
121 )))
122
123 === Токени для користувача ===
124
125 Припускаю, що у вас може виникнути потреба зробити персональні ключі для користувачів вашого додатку, можливо ви захочете впровадити ліміти або інші обмеження.
126 В такому випадку вам не потрібно вказувати перелік токенів в конфігах, ви можете зберігати їх в базі даних або іншому місці згідно вашій бізнес-логіки. Єдина вимога, у вас має бути сервіс, який вміє перевіряти чи існує наданий токен.
127
128 Для того, щоб JsonRpcServer міг використовувати вашу логіку, доведеться реалізувати власний клас, що реалізує інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator{{/code}}
129
130 {{code language="php" layout="LINENUMBERS" title="Приклад власного валідатора токенів"}}
131 <?php
132
133 namespace App\Services\RpcSecurity;
134
135 use App\Services\UserService;
136 use Symfony\Component\Security\Core\Exception\UserNotFoundException;
137 use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
138 use Ufo\RpcError\RpcInvalidTokenException;
139
140 class UserTokenValidator implements ITokenValidator
141 {
142
143 public function __construct(protected UserService $userService) {}
144
145 public function isValid(string $token): bool
146 {
147 try {
148 $this->userService->getUserByToken($token);
149 return true;
150 } catch (UserNotFoundException $e) {
151 throw new RpcInvalidTokenException(previous: $e);
152 }
153 }
154 }
155 {{/code}}
156
157 (% class="box warningmessage" %)
158 (((
159 **ВАЖЛИВО!!!**
160 Метод {{code language="none"}}isValid{{/code}} має повертати {{code language="none"}}true{{/code}} якщо токен існує і валідний, або викидати {{code language="none"}}Ufo\RpcError\RpcInvalidTokenException{{/code}} в іншому разі.
161 )))
162
163 Після цього вам потрібно в файлі {{code language="none"}}config/services.yaml{{/code}} прописати що класи, що мають залежність від інтерфейса {{code language="none"}}ITokenValidator{{/code}} мають приймати ваш новий клас.
164
165 {{code language="yaml" layout="LINENUMBERS" title="config/services.yaml"}}
166 parameters:
167 # some parameters list
168 # ...
169
170 services:
171 # some services list
172 # ...
173
174 Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
175 class: App\Services\RpcSecurity\UserTokenValidator
176 {{/code}}