OAuth 2.0

Client

Application

client یک برنامه (application) است که می خواهد به حساب کاربر دسترسی داشته باشد و برای این منظور باید ابتدا دسترسی آن توسط کاربر تائید شود و سپس درخواست احراز هویت (authorization) توسط سرور انجام شود . (کلاینت ها)

چرخه دسترسی

1. برنامه (application) درخواست احراز هویت (authorization) را برای دسترسی به اطلاعات کاربر ارسال می کند .

2. اگر کاربر دسترسی برنامه (application) را تائید کند کد (code) تائید برای برنامه ارسال می شود .

3. برنامه درخواست access token را همراه با کد تائید (code) به سرور ارسال می کند .

4. اگر اطلاعات برنامه و کد صحیح باشد دسترسی برنامه به اطلاعات کاربر میسر می شود و access token به برنامه داده می شود .

5. برنامه از طریق access token درخواست خود را به وبسرویس (API) ارسال می کند .

6. در صورت صحت access token ، درخواست بروی وبسرویس انجام شده و پاسخ بر گردانده می شود .

Authorization

درخواست دسترسی

برای درخواست دسترسی به اطلاعات کاربر ، مقادیر را در آدرس زیر قرار دهید و کاربر را به این آدرس بفرستید :

        
https://www.hesabit.com/oauth2/authorize
        
    

client_id	شناسه client که زمان ایجاد آن در پنل کاربری دریافت کرده اید. (کلاینت ها) مانند : 06fea353-98cc-4aac-9acf-3eb82e65ec48
response_type	نوع پاسخ که همیشه برابر با مقدار زیر است . مانند : code
scope	یک رشته از مقادیر که با کاما "," از هم جدا شده اند و بیانگر سطح و نوع دسترسی شما به اطلاعات است. (جدول scope) مانند : read,write
access_type	نوع دسترسی شما به دو صورت آنلاین و آفلاین امکان پذیر است . مانند : online
redirect_uri	آدرسی که پس از authorization کاربر به آن فرستاده می شود. (این مقدار باید با آنچه در پنل کاربری هنگام ایجاد client تنظیم کرده اید برابر باشد) مانند : http://sample.com/verify.php
state	یک رشته غیر تکراری که از جانب شما برای امنیت و CSRF استفاده می شود. مانند : AbdeFGf45F13sdfEef172

توضیحات :

• scope بیانگیر نوع دسترسی شما به اطلاعات است که با نام های مختلف از قبل تنظیم شده و لیست آنها را می توانید در این جدول مشاهده کنید . اگر به چند scope همزمان نیاز دارید کافی است با گذاشتن کاما بین آنها ، این مقادیر را در درخواست قرار دهید. برای تغییر سطح دسترسی و یا scope شما نیاز به دریافت مجدد تائید کاربر دارید و متد authorize را باید با درخواست scope جدید تکرار کنید.

• access_type بیانگر نوع دسترسی شما به صورت آنلاین و یا آفلاین است. با توجه به اینکه access token پس از ۱۰ ساعت منقضی می شود در دسترسی آفلاین شما یک کلید دیگر به نام refresh token دریافت میکنید که بوسیله آن می توانید access token جدید دریافت کنید. بدیهی است در مدل آنلاین فقط تا زمان انقضای access token به اطلاعات دسترسی دارید ، متد آنلاین برای لاگین و دسترسی های موقت طراحی شده است.

• state یک رشته تصادفی است که توسط درخواست کننده و یا سرور شما تنظیم می شود و برای کنترل پاسخ ها استفاده می شود ، با این روش شما قادر به تشخیص پاسخ هایی که از جانب خودتان ارسال شده خواهید بود، این مدل برای CSRF کاربرد دارد.

نمونه کامل درخواست :

        
https://www.hesabit.com/oauth2/authorize?client_id=06fea353-98cc-4aac-9acf-3eb82e65ec48&response_type=code&scope=write&access_type=offline&state=AbdeFGf45F13sdfEef172&redirect_uri=http://sample.com/verify.php
        
    

در آدرس authorize کاربر صفحه ای را مبنی بر درخواست client برای دسترسی به اطلاعات خود مشاهده می کند و امکان تائید و یا رد دسترسی وجود دارد و پس از انتخاب هر یک از دو مورد با پاسخ متناسب به آدرس redirect uri بازگردانده می شود .

تائید دسترسی

در صورت تائید دسترسی ، کاربر همراه با پارامترهای code و state به آدرس redirect uri فرستاده می شود.

code	یک رشته منحصر به فرد است که فقط ۱۵ دقیقه معتبر است. مانند : 90fea353-98cc-4aac-9acf-3eb82e65ec50
state	در صورتی در درخواست وجود داشته باشد در پاسخ برگردانده می شود.

نمونه کامل پاسخ (responce) :

        
http://www.sample.com/verify.php?code=06fea353-98cc-4aac-9acf-3eb82e65ec48&state=AbdeFGf45F13sdfEef172
        
    

عدم تائید دسترسی

در صورت عدم تائید دسترسی ، کاربر همراه با پارامترهای error و state به آدرس redirect uri فرستاده می شود.

نمونه کامل پاسخ :

        
http://www.sample.com/verify.php?error=access_denied&error_description=The+user+has+denied+your+application+access.&state=AbdeFGf45F13sdfEef172
        
    

Access Token

Exchange Authorization Code

پس از دریافت code در مرحله قبل (authorization) ، برای دریافت access token یک درخواست از نوع POST با محتوی زیر به این آدرس ارسال کنید :

        
https://api.hesabit.com/oauth2/token
        
    

محتوی درخواست (body) :

code	کدی که در مرحله قبل دریافت کرده اید . مانند : 06fea353-98cc-4aac-9acf-3eb82e65ec48
client_id	شناسه client که زمان ایجاد آن در پنل کاربری دریافت کرده اید. (کلاینت ها) مانند : 06fea353-98cc-4aac-9acf-3eb82e65ec48
client_secret	رمز client که زمان ایجاد آن در پنل کاربری دریافت کرده اید. (کلاینت ها) مانند : 112ea353-98cc-4aac-9acf-3eb82e65e567
grant_type	این مقدار در این مرحله برابر با authorization_code است. مانند : authorization_code
redirect_uri	آدرس بازگشت که در زمان ایجاد client آن در پنل کاربری تنظیم کرده اید. (کلاینت ها) مانند : http://www.sample.com/verify.php

توضیحات :

• code یکبار قابل استفاده است و فقط برای ۱۵ دقیقه اعتبار دارد و در صورتی که در این مدت ارسال نشود باید مرحله authorization مجددا تکرار شود .

• redirect_uri باید عینا مانند آنچه در authorization ارسال شده باشد .

نمونه کامل پاسخ (responce) :

        
{
"access_token": "36fea351-18cc-4aac-9acf-1eb82e65ec33",
"token_type": "Bearer",
"expires_in": 36000,
"refresh_token": "122ea357-18cc-4aac-9acf-9eb82e65ec40",
"scope": "write"
}
        
    

Refresh Token

Refresh Access Tokens

پس از انقضای access_token با ارسال درخواست POST با محتوی زیر به این آدرس می توانید access_token جدید بگیرید :

        
https://api.hesabit.com/oauth2/token
        
    

محتوی درخواست (body) :

        
{
"client_id":"78aea351-18cc-4bac-1acf-1eb82e65ec341",
"grant_type":"refresh_token",
"client_secret":"36fea351-18cc-4aac-cdcf-1eb82e65ec33",
"refresh_token": "122ea357-18cc-4aac-9acf-9eb82e65ec40"
}
        
    

توضیحات :

• فقط در صورتی که access_type به صورت offline باشد در پاسخ مرحله قبل refresh_token ایجاد می شود .

• نکته بسیار مهم این است که refresh_token مجددا برای شما ارسال نخواهد شد و برای دریافت مجدد آن باید مراحل از ابتدا تکرار شود ، پس در حفط و نگه داری آن دقت کنید و به هیچ وجه آن را منتشر نکنید .

Scopes

سطوح دسترسی

سطح دسترسی به بخش های مختلف و همچنین نوع عملیات و متدها توسط scope کنترل می شود.

read	دسترسی به متد های خواندن اطلاعات. invoices, items, customers, profiles	GET
write	دسترسی به متدهای های خواندن و نوشتن اطلاعات. invoices, items, customers, profiles, transactions	GET POST
admin	دسترسی به متدهای های خواندن ، نوشتن ، ویرایش و حذف اطلاعات. invoices, items, customers, profiles, transactions	GET POST PUT DELETE

توضیحات :

• تعیین و تغییر scope فقط در مرحله درخواست authorization امکان پذیر است.