pátek 17. října 2008

Google Account Authentication API

Pokud vyvíjíte aplikaci (ať už běžnou či webovou), můžete pochopitelně využívat aplikací, které poskytuje Google.
Při takovém využití Google aplikací však dříve či později narazíte na nutnost se ke službám Google přihlásit, resp. uživatelé Vaší aplikace se budou muset přihlásit ke svému Google Account.

... Pokračování

Klasická aplikace
Klasickou aplikací se myslí kterákoliv aplikace, kterou si uživatel nainstaluje na svém počítači a přes kterou se přistupuje ke službám poskytovaných Google.

ClientLogin
ClientLogin je jedním ze způsobů jak přistupovat ke Google službám.
Narozdíl od "obyčejného" přístupu, kdy se přihlašovací údaje zasílají při každém požadavku, má ClientLogin několik výhod:
  • Vyšší výkon – údaje jsou zkontrolovány pouze jednou
  • Vyšší bezpečnost – údaje nejsou přenášeny při každém požadavku
  • Lze použít další bezpečnostní prvky (Captcha apod.)
  • Proces přihlášení lze dále nastavit nebo rozšířit

Použití ClientLogin
ClinetLogin pracuje s požadavky HTTP POST, které jsou posílány Google.
Ukázkový požadavek na přihlášení vypadá takto:

POST /accounts/ClientLogin HTTP/1.0
Content-type: application/x-www-form-urlencoded

accountType=HOSTED_OR_GOOGLE&Email=EMAIL@gmail.com&Passwd=HESLO&service=cl&source=Gulp-CalGulp-1.05

Co to je

Hlavička požadavku POST:
POST /accounts/ClientLogin HTTP/1.0

A obsah – používejte "application/x-www-form-urlencoded":
Content-type: application/x-www-form-urlencoded

Parametry
Typ účtu - accountType:
  • GOOGLE – klasický Google účet
  • HOSTED – Google účet pro použití s aplikacemi Google
  • HOSTED_OR_GOOGLE – prvně proběhne pokus o přihlášení k HOSTED účtu, pokud tento pokus selže, následuje pokus o přihlášení k GOOGLE účtu. Tento typ používejte, pokud si nejste jistí, který typ použít.

Email: celý email (včetně domény)

Passwd – heslo: heslo k účtu

Service – služba: služba, ke které se chcete přihlásit. Každá služba má svůj kód (Google Calendar má "cl"), případně je možné použít obecné "xapi".

Source – zdroj: zdroj požadavku (tedy aplikace), doporučený tvar je: "společnost-jméno_aplikace-verze"

Pokud chcete použít Captcha, použijte následují dva parametry:

Logintoken – hodnotu dodá Google spolu s url Captcha obrázku s odpovědi s chybovým kódem "CaptchaRequired"

Logincaptcha – odpověď uživatele na Captchu (tedy obsah obrázku)

Požadavek s Captchou vypadá takto:

POST /accounts/ClientLogin HTTP/1.0
Content-type: application/x-www-form-urlencoded

accountType=HOSTED_OR_GOOGLE&Email=jondoe@gmail.com&Passwd=north23AZ&service=cl& source=Gulp-CalGulp-1.05&logintoken=DQAAAGgA...dkI1LK9&logincaptcha=brinmar


Požadavek se posílá na https://www.google.com/accounts/ClientLogin + parametry.
ClientLogin v současnosti neumí účty vytvářet, uživatel tedy musí mít účet u Google již vytvořen.

Odpoveď z ClientLogin
Po pokusu o přihlášení, Google vrátí buď HTTP 200 (přihlášení se podařilo) nebo HTTP 403 (přihlášení se nepodařilo):

Ukázky odpovědí

Úspěšné přihlášení:
HTTP/1.0 200 OK
Server: GFE/1.3
Content-Type: text/plain

SID=DQAAAGgA...7Zg8CTN
LSID=DQAAAGsA...lk8BBbG
Auth=DQAAAGgA...dk3fA5N

Důležitá je hodnota Auth – jde o identifikační hodnotu a musíte ji použít při každém požadavku, který se posílá směrem do Google.
SID a LSID v současné době nejsou nijak používány.

Neúspěšné přihlášení:

HTTP/1.0 403 Access Forbidden
Server: GFE/1.3
Content-Type: text/plain

Url=http://www.google.com/login/captcha
Error=CaptchaRequired
CaptchaToken=DQAAAGgA...dkI1LK9
CaptchaUrl=Captcha?ctoken=HiteT4b0Bk5Xg18_AcVoP6-yFkHPibe7O9EqxeiI7lUSN

Zde se vrací výše zmíněná chyba "CaptchaRequired".
Url je adresa stránky s chybou (můžete zvážit, zda ji zobrazit), Error je chybový kód, CaptchaToken je token pro použití v parametru "logintoken" a CaptchaUrl je adresa obrázku Captcha (celá adresa je "http://www.google.com/accounts/Captcha?ctoken=HiteT4b0Bk5Xg18_AcVoP6-yFkHPibe7O9EqxeiI7lUSN").

Chybové kódy, které mohou být vráceny:
  • BadAuthentication – Špatný email a/nebo heslo.
  • NotVerified – Uživatel zatím neověřil svůj email, dokud tak neučiní, nemůže služby Google využívat
  • TermsNotAgreed – Uživatel nesouhlasil s podmínkami použití služeb Google
  • CaptchaRequired – Je požadováno ověření Captcha
  • Unknown – neznámá chyba, nejspíše byl zaslán špatný parametr
  • AccountDeleted – Účet byl smazán
  • AccountDisabled – Účet je zablokován
  • ServiceDisabled – Přístup pro uživatele ke zvolené službě je zablokován
  • ServiceUnavailable – Služba není dostupná, zkuste to později

Přihlášení k Google účtu z webové aplikace
Stejně jako klasické aplikace, i webové aplikace mohou přistupovat ke službám poskytovaných Google. Pro přihlášení slouží rozhraní AuthSub. Toto rozhraní umožňuje aplikacím přistupovat ke službám bez nutnosti práce s údaji pro přihlášení, čímž je zajištěna vysoká bezpečnost.

Ověření uživatele probíhá buďto pomocí zabezpečených nebo nezabezpečených tokenů. Pro použití zabezpečených tokenů musíte Vaši aplikaci zaregistrovat (více informací na http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html). Po registraci získáte certifikát a možnost všechny požadavky digitálně podepsat.

Průběh
Před získáním přístupu ke zvolené službě, Vaše aplikace zavolá URL pro ověření uživatele a dodá některé informace. Následně je uživatel přesměrován na stránku Google, kde musí potvrdit, že souhlasí s přístupem ke svému účtu přes Vaši aplikaci. Pokud uživatel souhlasí, Google jej přesměruje zpět na Vaši aplikaci a dodá token pro ověření při požadavcích z Vaší aplikace.

Požadavek AuthSub
Ukázka požadavku:

https://www.google.com/accounts/AuthSubRequest?next=http%3A%2F%2Fwww.yourwebapp.com%2Fshowcalendar.html
&scope=http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2F&session=0&secure=0

Požadavek na ověření uživatele se posílá na https://www.google.com/accounts/AuthSubRequest a připojují se k němu následující parametry:
  • next – povinný parametr, udává adresu přesměrování po úspěšném přihlášení – mělo by tedy jít o Vaši stránku
  • hd – volitelný parametr, umožňuje specifikovat doménu pro Google aplikace. Můžete použít hodnotu "default" pro klasický Google účet (JMENO@gmail.com).
  • Scope – povinný parametr, udává URL služby, ke které se chcete přihlásit
  • Secure – volitelný parametr, udává, zda chcete použít zabezpečené (hodnota 0) nebo nezabezpečené tokeny (hodnota 1). Zabezpečené tokeny jsou k dispozici pouze pro registrované aplikace
  • session – volitelný parametr, udává, zda token pro jedno použití může být vyměněn za token pro session

Po odeslání požadavku na Google dojde k přesměrování uživatele na stránku, kde je souhrn toho, co se děje (že Vaše aplikace chce přistupovat ke službě Google přes uživatelův účet, míra zabezpečení apod.), uživatel zadá přihlašovací údaje a vše potvrdí.

Pokud vše proběhne dobře, Google uživatele přesměruje zpět na adresu udanou parametrem „next“ a navíc vrátí token:

http://www.domena.cz/kalendar.html?token=CKF50YzIHxCT85KMAg

Tento token dále použijte k přístupu ke službě.

Výše uvedený token však slouží jen pro jednorázový přístup. Pokud chcete přistupovat ke Google službě vícekrát, je potřeba token změnit na session token. To lze udělat následovně:

Při prvním požadavku je nutné nastavit parametr "session" na hodnotu "1", to umožní budoucí změnu tokenu.

Na adresu https://www.google.com/accounts/AuthSubSessionToken je potřeba odelsat požadavek HTTP GET:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="TOKEN"
User-Agent: Java/1.5.0_06
Host: https://www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

Pokud je v pořádku, dostanete zpět odpověď HTTP 200 a dvojici hodnot, např.:
Token=DQAA...7DCTN
Expiration=20061004T123456Z

První hodnota je nový token, který slouží pro přístup ke Google službě, druhá hodnota je datum expirace tokenu (zatím není využívána).
Protože token nikdy neexpiruje, je možné jej používat pořád.

Platnost tokenu je však možné zrušit "ručně". Token lze zrušit odesláním HTTP GET požadavku na https://www.google.com/accounts/AuthSubRevokeToken:

GET /accounts/AuthSubRevokeToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="TOKEN"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

Pokud dojde k úspěšnému zrušení platnosti tokenu, je vrácena hodnota HTTP 200.

Napojení na ASP.NET
Pokud vyvíjíte aplikaci v ASP.NET, může Vás zaujmout příspěvek z fóra komunity:
http://groups.google.com/group/Google-Accounts-API/browse_thread/thread/4d763ca21230d641#

Lze je možné také stáhnout kód pro ASP.Net, který obsahuje ukázku, jak napojit výše uvedené vlastnosti na ASP.NET.

Závěrem
V tomto článku jste mohli nalézt základní informace o přihlašování k účtům a službám Google. Pokud Vás téma zaujalo, neváhejte se také podívat na stránky v odkazech níže.

Zajímavé odkazy
Domovská stránka API: http://code.google.com/apis/accounts/
Komunita okolo API: http://groups.google.com/group/Google-Accounts-API

Zdroj: code.google.com

Autor: Jan Bradávka

Žádné komentáře: