Pre potreby mobilných a desktopových aplikácií bolo do Netquest API implementované OAuth rozšírenie pomenované Xauth (riešenie známe z API Twitteru). Implementácia OAuth protokolu v rôznych jazykoch sa nachádza na http://oauth.net/code/.
Získanie kľúča access_token
Pre prihlásenie do API použitím Xauth je potrebné mať kľúče consumer_key a consumer_secret.
Požiadavka musí byť zaslaná na adresu
https://www.netquest.sk/api/xauth/access-token
odovzdaním nasledujúcich dát použitím metódy POST:
$params = array( //uživatelske meno, pre ktoré má byť token získaný 'x_auth_username' => '[email protected]', //enkódované heslo pre užívateľa, pre ktorého má byť token získaný 'x_auth_md5_password' => md5('vaseheslo') //tento parametr musí mať rovnakú hodnotu 'x_auth_mode' => 'client_auth' );
Hlavička Authorization
musí mať následujúcu podobu
OAuth realm="", oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="79a44132c8fed1c2a15778941531c6a804ec60b2b", oauth_timestamp="1322083695", oauth_nonce="0790a4299979bbca1ee2882807448cd304ecd656f", oauth_signature="RudpQeTM8sHPg5EGxtm4N6hfkJ8%3D"
Po úspešnom autorizovaní budú ako odpoveď vrátené oauth_token
a oauth_token_secret
.
V tomto momente by mala aplikácia odstrániť dáta užívateľa
(x_auth_username
a x_auth_md5_password
) a použiť štandardné OAuth procedúry na overovanie na serveri.
Ukážka
$consumerKey = '79a44132c8fed1c2a15778941531c6a804ec60b2b'; $consumerSecret = '18f37873635e0f43dd81f69f2ecfba59'; $params = array( 'x_auth_username' => '[email protected]', 'x_auth_md5_password' => md5('vaseheslo'), 'x_auth_mode' => 'client_auth' ); $consumer = new Netquest_Api_Client($consumerKey, $consumerSecret); $consumer->setUri('/xauth/access-token'); $consumer->setParams($params); $result = $consumer->request(); Zend_Debug::dump($result); /** * { * "oauth_token":"54dbb76fe456b2d7126ccf232e37481e04ecd5fef", * "oauth_token_secret":"951afe99dc9c8215b3097706e9648dba", * "id_user":"9456" * } */
Aplikácia klienta by mala mať token
a token_secret
, ktoré spoločne s consumer_key
a consumer_secret
umožňujú správne overenie.
Ukážka – Posielanie požiadavky menom používateľa
Cieľ: Získanie zoznamu respondentov z konkrétneho dotazníka
Pre tento účel budeme používať oauth_token
a oauth_token_secret
Z dotazníka ID=1234
získame zoznam respondentov, ktorí vyplnili dotazník 1. júla, 2011 (2011-07-01
).
Dodatočne, máme záujem len o 10 respondentov.
Pre získanie zoznamu respondentov s vyššie uvedenými parametrami je nutné použiť operáciu vyhľadávania respondentov, dostupnú na
https://www.netquest.sk/api/respondents/search/:id
Požiadavka bude odoslaná použitím metódy POST za účelom odovzdania parametrov hľadania. Dodatočné parametre budú potrebné aj pre správne vykonanie OAuth/Xauth požiadavky. Všetky potrebné parametre sú uvedené nižšie.
Post body – date_survey_answer=2011-07-01&limit=10
oauth_consumer_key – 524c9e8f94b8eb676b95e94c59a844df04ec60cc0
oauth_nonce – oElnnMTQIZvqvlfXM56aBLAf5noGD0AQR3Fmi7Q6Y
oauth_signature_method -HMAC-SHA1
oauth_token – 14ee78ef86d8cca7a1a0661e290a76fa04ece90e9
oauth_timestamp -1272325550
oauth_version – 1.0
Následne vytvoríme signature base string
podľa rovnakých pravidiel, ako boli použité pre získanie tokena.
POST&https%3A%2F%2Fwww.netquest.sk%2Fapi%2Frespondents%2Fsearch%2F1234& date_survey_answer%3D2011-07-01%26limit%3D10%26oauth_consumer_key%3D 524c9e8f94b8eb676b95e94c59a844df04ec60cc0%26oauth_nonce%3D 82d06397567e5fe1fcc7f000d35f07be04ed10783%26oauth_signature_method%3DHMAC-SHA1%26 oauth_timestamp%3D1322321795%26oauth_token%3D14ee78ef86d8cca7a1a0661e290a76fa04ece90e9%26 oauth_version%3D1.0
Ďalší krok je vytvorenie šifrovacieho kľúča pre generovanie podpisu pomocou oauth_consumer_secret
a oauth_token_secret
07d740ac3613874f9528c3eab0279b98&ab8b78bbebb38b76f444c8a2ddf162ff
Použitím šifrovacieho kľúča 'podpíšeme' signature base string. Vo výsledku dostaneme:
JWrgkCsKm3OTpEQR5RI7kmtlpco%3D
Potom vytvoríme HTTP autorizačnú hlavičku Authorization
. Samozrejme, všetky tieto hodnoty musia byť enkódované (enkódovaná URL
)
OAuth realm="" oauth_nonce="oElnnMTQIZvqvlfXM56aBLAf5noGD0AQR3Fmi7Q6Y", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1272325550", oauth_consumer_key="524c9e8f94b8eb676b95e94c59a844df04ec60cc0", oauth_token="14ee78ef86d8cca7a1a0661e290a76fa04ece90e9", oauth_signature="JWrgkCsKm3OTpEQR5RI7kmtlpco", oauth_version="1.0"
Posledným prvkom je prevedenie POST požiadavky na Netquest API (koncový bod). Potom už iba držať palce, aby všetko pracovalo správne :-).
Po úspešnom vykonaní požiadavky by sme mali obdržať nasledujúcu odpoveď:
{ "total":"20", "list":[{ "id":100824, "token":"549E56", "date_token_generate":"2011-11-25 22:27:42", "date_invitaion_send":null, "date_survey_open":null, "date_survey_answer":null, "email":"[email protected]", "label1":"Petr", "label2":"Novak", "label3":"774 700 800", "label4":"", "label5":"", "answer_postponed":null },{ ... }] }
Podpisovanie HTTP požiadavky
Všetky OAuth 1.0 požiadavky používajú rovnaký základný algoritmus pre vytváranie reťazca podpisu (signature base string
) a vytváranie podpisu.
Vytvorenie signature base string
je jedna z najnáročnejších častí OAuth štandardu.
Text tvorí následujúce časti:
- použitý názov metódy (
GET
neboPOST
) - link-character ampersand (
"&"
) - enkódovaná URL s adresou operácie, napr.
https://www.netquest.sk/api/surveys
- link-character ampersand (
"&"
) - parametre zaslané prostredníctvom POST požiadavky a OAuth parametre nevyhnutné pre overenie i.
Vyššie uvedené parametre (POST i OAuth) musia byť radené v lexikografickom usporiadaní.
Obaja parametre a hodnoty musia byť enkódované (urlencode
).
Ak sa nachádza v hodnote parametra medzera, mala by byť odoslaná ako %20
Namiesto znaku pre rovná sa "="
(relácia kľúč/hodnota) by mala byť použitá enkódovaná podoba
– "%3D"
.
Hodnota každého parametra (kľúč/hodnota) by mala byť spojená enkódovaným & (ampersand) – "%26"
.
Vyššie uvedený algoritmus môže byť predložený ako pseudo-kód zobrazený nižšie:
httpMethod + "&" + url_encode( base_uri ) + "&" + sorted_query_params.each { | k, v | url_encode ( k ) + "%3D" + url_encode ( v ) }.join("%26")
Bez ohľadu na to, aký typ žiadosti vykonávate, pravidlá generovania signature base string
sú vždy rovnaké.
Netquest API vyžaduje OAuth/Xauth podpísanie požiadaviek s HMAC-SHA1 algoritmom.
Slovník
oauth_nonce
– Jedinečný identifikátor každej HTTP požiadavky generovanej aplikáciou klienta.
Netquest API umožňuje použiť jednu hodnotuoauth_nonce
pre jednu požiadavku. Cieľom je eliminovať opakujúce sa volanie rovnakej požiadavky.oauth_timestamp
– Celé číslo predstavujúce počet sekúnd, ktoré uplynuli od 1. januára 1970.
Hodnota klientovho TIMESTAMP sa nemôže líšiť od hodnoty TIMESTAMP servera o viac ako 600 sekúnd (10 minút)
Ak je rozdiel väčší, HTTP požiadavka bude ignorovaná.- signature base string – „Zostavený „text, podpísaný pomocou šifrovacieho kľúča pre generovanie podpisu HTTP požiadavky –
oauth_signature
Príklad vytvorenia podpisu je popísaný v časti Podpisovanie HTTP požiadavky - encryption key – Text (reťazce) použitý ako „tajný kľúč” pre podpisovanie HTTP požiadaviek.
Podľa OAuth 1.0 štandardu je šifrovací kľúč vypočítaný podľa nasledujúceho algoritmu:url_encode( consumer_secret ) + "&" + url_encode( oauth_token_secret || nil )
Niektoré z požiadavky OAuth vyžadujú použitie
oauth_token_secret
, zatiaľ čo ostatné nie.Šifrovací kľúč je vždy zložený z hodnôt
consumer_secret
aoauth_token_secret
,
oddelený ampersandom (&
)Ak nemáte
oauth_token_secret
hodnotu, ampersand (&
) musíte do šifrovacieho kľúča aj tak „pridať”.