]>
Commit | Line | Data |
---|---|---|
53ed6d7d | 1 | ## Usage |
2 | ||
3 | See the [REST API documentation](http://shaarli.github.io/api-documentation/). | |
4 | ||
5 | ## Authentication | |
6 | ||
7 | All requests to Shaarli's API must include a JWT token to verify their authenticity. | |
8 | ||
9 | This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`. | |
10 | ||
11 | JWT resources : | |
12 | ||
13 | * [jwt.io](https://jwt.io) (including a list of client per language). | |
14 | * RFC : https://tools.ietf.org/html/rfc7519 | |
15 | * https://float-middle.com/json-web-tokens-jwt-vs-sessions/ | |
16 | * HackerNews thread: https://news.ycombinator.com/item?id=11929267 | |
17 | ||
18 | ||
19 | ### Shaarli JWT Token | |
20 | ||
21 | JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: | |
22 | ||
23 | ``` | |
24 | [header].[payload].[signature] | |
25 | ``` | |
26 | ||
27 | #### Header | |
28 | ||
29 | Shaarli only allow one hash algorithm, so the header will always be the same: | |
30 | ||
31 | ```json | |
32 | { | |
33 | "typ": "JWT", | |
34 | "alg": "HS512" | |
35 | } | |
36 | ``` | |
37 | ||
38 | Encoded in base64, it gives: | |
39 | ||
40 | ``` | |
41 | ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== | |
42 | ``` | |
43 | ||
44 | #### Payload | |
45 | ||
46 | **Validity duration** | |
47 | ||
48 | To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes. | |
49 | ||
50 | ```json | |
51 | { | |
52 | "iat": 1468663519 | |
53 | } | |
54 | ``` | |
55 | ||
56 | See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6). | |
57 | ||
58 | ||
59 | #### Signature | |
60 | ||
61 | The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page. | |
62 | ||
63 | Signature example with PHP: | |
64 | ||
65 | ```php | |
66 | $content = base64_encode($header) . '.' . base64_encode($payload); | |
67 | $signature = hash_hmac('sha512', $content, $secret); | |
68 | ``` | |
69 | ||
70 | ||
71 | ### Complete example | |
72 | ||
73 | #### PHP | |
74 | ||
75 | ```php | |
76 | function generateToken($secret) { | |
77 | $header = base64_encode('{ | |
78 | "typ": "JWT", | |
79 | "alg": "HS512" | |
80 | }'); | |
81 | $payload = base64_encode('{ | |
82 | "iat": '. time() .' | |
83 | }'); | |
84 | $signature = hash_hmac('sha512', $header .'.'. $payload , $secret); | |
85 | return $header .'.'. $payload .'.'. $signature; | |
86 | } | |
87 | ||
88 | $secret = 'mysecret'; | |
89 | $token = generateToken($secret); | |
90 | echo $token; | |
91 | ``` | |
92 | ||
93 | > `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68` | |
94 | ||
95 | ```php | |
96 | $options = [ | |
97 | 'http' => [ | |
98 | 'method' => 'GET', | |
99 | 'jwt' => $token, | |
100 | ], | |
101 | ]; | |
102 | $context = stream_context_create($options); | |
103 | file_get_contents($apiEndpoint, false, $context); | |
104 | ``` |