OAuth2
Money S5 API využívá autentizaci pomocí standardu OAuth2. Klíče se generují v prostředí Money v sekci Administrace – Výměna dat – REST API – Klíče API. Klíč je vázaný na uživatele Money, kterým jsou definovány jeho práva na koncové body.
Jako typ autentizace je možné použít následující metody:
- Client credentials flow
- Authorization code flow
Každý request musí obsahovat hlavičku:
Authorization: Bearer [access_token]
Klíče lze vytvořit pomocí tlačítka Generovat v horní liště nebo jen napsat ručně.
Práva pro API se řeší pomocí samostatného uživatele Money a jeho Role pro API. Práva pro starší REST API je řešeno samostaně v záložce Role v API, kde lze definovat možnosti příkazů na jednotlivé REST API endpointy. Pro GraphQL jsou řešeny práva dle standardní role Money. Pomocí práv lze omezit obvyklé práva zobrazit, přidat, editovat, smazat včetně hlubších filtrů pro jednotlivé seznamy.
1.) Client credentials flow
Request na /token endpoint
POST http(s)://[adresa API]/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=[vygenerované Client ID]&client_secret=[vygenerované Client Secret]&scope=S5Api
Identity server vrátí vygenerovaný token (JSON):
{„access_token“:“[vygenerovaný token]“,“expires_in“:3600,“token_type“:“Bearer“}
Pozn. Pokud je v requestu použit nesprávný token, resp. token, jemuž vypršela platnost, vrátí S5API na daný dotaz chybu 401 Unauthorized. Token je pevně generován s platností 3600 sekund tedy 1 hodinu.
Token
Token lze dekódovat a zobrazit jeho obsah, např. zde: https://jwt.io/.
Hlavička (header)
alg algoritmus použitý pro dekódování
typ media type (MIME)
Tělo (payload)
iss (issuer) vydavatel
sub (subject) subjekt, kterého se týkají přenášené údaje
aud (audience) příjemci
exp (expiration) čas platnosti (do) – datum a čas ve formátu dle POSIX (počet sekund od počátku epochy) =
okamžik, od kterého je token neplatný
nbf (not before) čas platnosti (od) – datum a čas ve formátu dle POSIX (počet sekund od počátku epochy) =
okamžik, od kterého je token platný
2.) Authorization code flow
Request na /authorize endpoint
GET http(s)://[adresa API]/connect/authorize?client_id=[vygenerované Client ID]&response_type=code&redirect_uri=http://[adresa API]/oauth2-redirect.html&scope=S5Api offline_access
redirect_uri – adresa, na kterou přijde po přihlášení uživatele autorizační kód, který se vymění za access token; adresa musí být přiřazena ke klientovi v S5
Request na /token endpoint
POST http(s)://[adresa API]/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=[vygenerované Client ID]&client_secret=[vygenerované Client Secret]&scope=S5Api&code=[autorizační kód vrácený v předchozím kroku]&redirect_uri=http://[adresa API]/oauth2-redirect.html
Identity server vrátí vygenerovaný token (JSON):
{„access_token“:“[vygenerovaný token]“,“expires_in“:3600,“token_type“:“Bearer“,“refresh_token“: „[vygenerovaný refresh token]“}
code – autorizační kód vrácený po přesměrování na redirect_uri (kód lze použít jen jednou)
redirect_uri – adresa, která byla specifikována při requestu na authorize endpoint
Scope: S5Api offline_access
Obnovení platnosti tokenu
POST http(s)://[adresa API]/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=[vygenerované Client ID]&client_secret=[vygenerované Client Secret]&scope=S5Api&redirect_uri=http://[adresa API]/oauth2-redirect.html&refresh_token=[vygenerovaný refresh token]