docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/rest-bundle/security.md
new file +40
β0
1
+
# Security
2
+
3
+
The bundle uses JsonRpcBundle security (`ufo_json_rpc.security`, see [Bundle configuration](/docs/api/json-rpc-bundle/config)); there is no separate REST configuration.
4
+
5
+
```yaml
6
+
# config/packages/ufo_json_rpc.yaml
7
+
ufo_json_rpc:
8
+
security:
9
+
protected_api: true # default: calls require a token
10
+
protected_doc: false # default: documentation is open
11
+
token_name: 'Ufo-RPC-Token'
12
+
clients_tokens:
13
+
- '%env(resolve:UFO_API_TOKEN)%'
14
+
providers:
15
+
partners:
16
+
api_groups: [partners]
17
+
clients_tokens: ['%env(PARTNERS_TOKEN)%']
18
+
internal:
19
+
api_groups: [internal]
20
+
service: App\Security\InternalTokenValidator # implements ITokenValidator
21
+
```
22
+
23
+
| Request | Check | Error |
24
+
| --- | --- | --- |
25
+
| REST call | `protected_api`: the token from the `token_name` header is checked by the provider of the entry point's API group, and for groups without a provider, by `clients_tokens` | `401` |
26
+
| OpenAPI / Postman | `protected_doc`: the same check for the document's group | `401` |
27
+
28
+
```bash
29
+
curl https://example.com/internal/catalog/list -H 'Ufo-RPC-Token: internal-secret'
30
+
```
31
+
32
+
* The group is defined by the route (the import's `defaults.api_group`), so a token of one group does not open another group's entry point. An `api_group` parameter in the request does not change the group.
33
+
* A provider sets either `clients_tokens` or `service` implementing `Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator` ([Providers for API groups](/docs/api/json-rpc-bundle/config)).
34
+
* JSON-RPC returns `403` for an invalid token; REST returns `401` for both a missing and an invalid one.
35
+
* `protected_doc` does not protect calls, and `protected_api` does not protect documentation: they are two independent flags.
36
+
* Symfony Security firewalls apply to REST paths the same way as to any other routes.
37
+
38
+
:::warning
39
+
REST routes do not handle CORS preflight (`OPTIONS`): if `OPTIONS` is not in the `methods` of the `#[Route]` attribute, the response is `405`. Configure CORS at the web server level or with a separate bundle.
40
+
:::