OAuth 2.0

این سند OAuth 2.0، زمان استفاده از آن، نحوه دریافت شناسه‌های کارخواه، و نحوه استفاده از آن با «کتابخانه کارخواه Google API» برای ‎ .NET را شرح می‌دهد.

پروتکل OAuth 2.0

‫OAuth 2.0 پروتکل مجوزی است که Google APIs از آن استفاده می‌کند. باید با خواندن پیوندهای زیر با این پروتکل آشنا شوید:

دریافت شناسه‌های کارخواه و رمزها

می‌توانید شناسه‌های مشتری و کلیدهای مخفی را در کنسول Google API دریافت کنید. انواع مختلفی از شناسه مشتری وجود دارد، بنابراین حتماً نوع صحیح را برای برنامه‌تان دریافت کنید:

در هریک از تکه‌کدهای نشان‌داده‌شده (به‌جز تکه‌کد «حساب خدمات»)، باید رمز کارخواه را بارگیری کنید و آن را به‌عنوان client_secrets.json در پروژه‌تان ذخیره کنید.

اطلاعات کاربری

اطلاعات کاربری

UserCredential یک کلاس کمکی ایمن ازنظر رشته برای استفاده از کد دسترسی جهت دسترسی به منابع محافظت‌شده است. کد دسترسی معمولاً پس‌از ۱ ساعت منقضی می‌شود، و پس‌از آن اگر بخواهید از آن استفاده کنید، خطا دریافت خواهید کرد.

UserCredential و AuthorizationCodeFlow به‌طور خودکار «بازآوری» کد را انجام می‌دهند، یعنی کد دسترسی جدیدی دریافت می‌کنند. این کار بااستفاده از ژتون بازآوری طولانی‌مدت انجام می‌شود که آن را همراه با کد دسترسی دریافت می‌کنید، اگر از پارامتر access_type=offline درطول جریان کد مجوز استفاده کنید.

در اکثر برنامه‌ها، توصیه می‌شود که کد دسترسی و کد بازآوری اعتبارنامه در فضای ذخیره‌سازی پایدار ذخیره شود. درغیراین‌صورت، باید هر ساعت صفحه مجوز را در مرورگر به کاربر نهایی نشان دهید، زیرا کد دسترسی یک ساعت پس‌از دریافت منقضی می‌شود.

برای اطمینان از اینکه ژتون‌های دسترسی و بازآوری باقی می‌مانند، می‌توانید پیاده‌سازی خودتان را از IDataStore ارائه دهید، یا می‌توانید از یکی از پیاده‌سازی‌های زیر که توسط کتابخانه ارائه شده است استفاده کنید:

  • FileDataStore برای ‎ .NET تضمین می‌کند که اعتبارنامه در فایل ماندگار خواهد بود.

ServiceAccountCredential

ServiceAccountCredential شبیه UserCredential است، اما هدف متفاوتی دارد. Google OAuth 2.0 از تعامل‌های سروربه‌سرور مانند تعامل‌های بین برنامه وب و Google Cloud Storage پشتیبانی می‌کند. برنامه درخواست‌کننده باید هویت خود را برای دسترسی به میانای برنامه‌سازی کاربردی اثبات کند و نیازی به مشارکت کاربر نهایی نیست. ServiceAccountCredential کلید خصوصی را ذخیره می‌کند که برای امضای درخواست دریافت کد دسترسی جدید استفاده می‌شود.

UserCredential و ServiceAccountCredential هر دو IConfigurableHttpClientInitializer را پیاده‌سازی می‌کنند، بنابراین می‌توانید هرکدام از آن‌ها را به‌صورت زیر ثبت کنید:

  • یک کنترل‌کننده پاسخ ناموفق، بنابراین اگر کد وضعیت HTTP 401 را دریافت کند، توکن را بازآوری می‌کند.
  • یک رهگیر، برای رهگیری Authorization سرصفحه در هر درخواست.

برنامه‌های کاربردی نصب شده

نمونه کد بااستفاده از Books API:

using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Books.v1;
using Google.Apis.Books.v1.Data;
using Google.Apis.Services;
using Google.Apis.Util.Store;

namespace Books.ListMyLibrary
{
    /// <summary>
    /// Sample which demonstrates how to use the Books API.
    /// https://developers.google.com/books/docs/v1/getting_started
    /// <summary>
    internal class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Books API Sample: List MyLibrary");
            Console.WriteLine("================================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            UserCredential credential;
            using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read))
            {
                credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
                    GoogleClientSecrets.Load(stream).Secrets,
                    new[] { BooksService.Scope.Books },
                    "user", CancellationToken.None, new FileDataStore("Books.ListMyLibrary"));
            }

            // Create the service.
            var service = new BooksService(new BaseClientService.Initializer()
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Books API Sample",
                });

            var bookshelves = await service.Mylibrary.Bookshelves.List().ExecuteAsync();
            ...
        }
    }
}
  
  • در این کد نمونه، نمونه UserCredential جدیدی با فراخوانی روش GoogleWebAuthorizationBroker.AuthorizeAsync ایجاد می‌شود. این روش ایستا موارد زیر را دریافت می‌کند:

    • رمز کارخواه (یا جریانی به رمز کارخواه).
    • دامنه‌های موردنیاز.
    • شناسه کاربر.
    • نشان لغو برای لغو کردن عملیات.
    • یک پایگاه داده اختیاری. اگر پایگاه داده مشخص نشده باشد، پیش‌فرض FileDataStore با پوشه پیش‌فرض Google.Apis.Auth است. پوشه در Environment.SpecialFolder.ApplicationData ایجاد می‌شود.
  • UserCredential که توسط این روش برگردانده می‌شود به‌عنوان HttpClientInitializer در BooksService (بااستفاده از مقداردهی اولیه) تنظیم می‌شود. همان‌طور که قبلاً توضیح داده شد، UserCredential یک مقداردهی اولیه کارخواه HTTP را پیاده‌سازی می‌کند.

  • توجه داشته باشید که در کد نمونه، اطلاعات رمز کارخواه از فایل بار می‌شود، اما می‌توانید کارهای زیر را نیز انجام دهید:

    credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
        new ClientSecrets
        {
            ClientId = "PUT_CLIENT_ID_HERE",
            ClientSecret = "PUT_CLIENT_SECRETS_HERE"
        },
        new[] { BooksService.Scope.Books },
        "user",
        CancellationToken.None,
        new FileDataStore("Books.ListMyLibrary"));
          

نمونه کتاب‌های ما را ببینید.

برنامه‌های وب (ASP.NET Core 3)

میاناهای برنامه‌سازی کاربردی Google از OAuth 2.0 برای برنامه‌های وب سرور پشتیبانی می‌کنند.

Google.Apis.Auth.AspNetCore3 کتابخانه توصیه‌شده برای استفاده در اکثر سناریوهای OAuth 2.0 مبتنی بر Google در برنامه‌های ASP.NET Core 3 است. این کلاس یک گرداننده اصالت‌سنجی OpenIdConnect مختص Google را پیاده‌سازی می‌کند. این کتابخانه از اصالت‌سنجی افزایشی پشتیبانی می‌کند و یک IGoogleAuthProvider قابل‌تزریق را برای ارائه اطلاعات کاربری Google تعریف می‌کند که می‌تواند با میاناهای برنامه‌سازی کاربردی Google استفاده شود.

این بخش نحوه پیکربندی و استفاده از Google.Apis.Auth.AspNetCore3 را شرح می‌دهد. کد نشان‌داده‌شده در اینجا براساس Google.Apis.Auth.AspNetCore3.IntegrationTests است که یک برنامه استاندارد ASP.NET Core 3 کاملاً فعال است.

اگر می‌خواهید این سند را به‌عنوان آموزش دنبال کنید، به برنامه ASP.NET Core 3 خودتان نیاز دارید و باید این مراحل را به‌عنوان پیش‌نیاز تکمیل کنید.

پیش‌نیازها

  • بسته Google.Apis.Auth.AspNetCore3 را نصب کنید.
  • ما از Google Drive API استفاده می‌کنیم، بنابراین باید بسته Google.Apis.Drive.v3 را نیز نصب کنید.
  • اگر پروژه Google Cloud ندارید، پروژه‌ای ایجاد کنید. برای انجام این کار، این دستورالعمل‌ها را دنبال کنید. این پروژه‌ای خواهد بود که برنامه‌تان با آن شناسایی می‌شود.
  • حتماً Google Drive API را فعال کنید. برای فعال کردن میاناهای برنامه‌سازی کاربردی، این دستورالعمل‌ها را دنبال کنید.
  • اعتبارنامه مجوزی ایجاد کنید که برنامه شما را برای Google شناسایی کند. این دستورالعمل‌ها را برای ایجاد اعتبارنامه مجوز و بارگیری فایل client_secrets.json دنبال کنید. دو نکته برجسته:
    • توجه داشته باشید که نوع اطلاعات کاربری باید برنامه وب باشد.
    • برای اجرای این برنامه، تنها شناسه منبع یکسان هدایت مجددی که باید اضافه کنید https://localhost:5001/signin-oidc است.

برنامه‌تان را برای استفاده از Google.Apis.Auth.AspNetCore3 پیکربندی کنید

‫Google.Apis.Auth.AspNetCore3 در کلاس Startup یا جایگزین مشابهی که ممکن است استفاده کنید پیکربندی شده است. قطعه‌های زیر از Startup.cs در پروژه Google.Apis.Auth.AspNetCore3.IntegrationTests استخراج شده‌اند.

  • دستورالعمل استفاده زیر را به فایل Startup.cs خود اضافه کنید.
    using Google.Apis.Auth.AspNetCore3;
  • در روش Startup.ConfigureServices، کد زیر را اضافه کنید و جای‌بان‌های «شناسه کارخواه» و «رمز کارخواه» را با مقادیر موجود در فایل client_secrets.json تغییر دهید. می‌توانید این مقادیر را مستقیماً از فایل JSON بار کنید یا می‌توانید آن‌ها را به هر روش ایمن دیگری ذخیره کنید. برای دیدن نمونه‌ای از نحوه بار کردن مستقیم این مقادیر از فایل JSON، به روش ClientInfo.Load در پروژه Google.Apis.Auth.AspNetCore3.IntegrationTests نگاهی بیندازید.
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    
        // This configures Google.Apis.Auth.AspNetCore3 for use in this app.
        services
            .AddAuthentication(o =>
            {
                // This forces challenge results to be handled by Google OpenID Handler, so there's no
                // need to add an AccountController that emits challenges for Login.
                o.DefaultChallengeScheme = GoogleOpenIdConnectDefaults.AuthenticationScheme;
                // This forces forbid results to be handled by Google OpenID Handler, which checks if
                // extra scopes are required and does automatic incremental auth.
                o.DefaultForbidScheme = GoogleOpenIdConnectDefaults.AuthenticationScheme;
                // Default scheme that will handle everything else.
                // Once a user is authenticated, the OAuth2 token info is stored in cookies.
                o.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
            })
            .AddCookie()
            .AddGoogleOpenIdConnect(options =>
            {
                options.ClientId = {YOUR_CLIENT_ID};
                options.ClientSecret = {YOUR_CLIENT_SECRET};
            });
    }
          
  • در روش Startup.Configure، حتماً مؤلفه‌های میان‌افزار اصالت‌سنجی و مجوزدهی ASP.NET Core 3 و همچنین تغییر مسیرهای HTTPS را به خط لوله اضافه کنید:
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
        app.UseHttpsRedirection();
        ...
    
        app.UseAuthentication();
        app.UseAuthorization();
    
        ...
    }
          

استفاده از اطلاعات کاربری کاربر برای دسترسی به Google APIs ازطرف او

اکنون آماده‌اید تا روش‌های کنش را به کنترل‌کننده‌هایی اضافه کنید که برای دسترسی به Google APIs ازطرف کاربر به اعتبارنامه کاربر نیاز دارند. قطعه کد زیر نحوه فهرست کردن فایل‌ها را در حساب Google Drive کاربر اصالت‌سنجی‌شده نشان می‌دهد. بیشتر متوجه دو چیز می‌شوید:

  • کاربر نه‌تنها باید اصالت‌سنجی شود، بلکه باید دامنه https://www.googleapis.com/auth/drive.readonly را نیز به برنامه شما اعطا کرده باشد، که شما آن را بااستفاده از مشخصه GoogleScopedAuthorize تعیین می‌کنید.
  • ما از سازوکار تزریق وابستگی استاندارد ASP.NET Core 3 برای دریافت IGoogleAuthProvider استفاده می‌کنیم که از آن برای دریافت اطلاعات کاربری کاربر استفاده می‌کنیم.

کد:

  • ابتدا دستورالعمل‌های استفاده زیر را به کنترل‌کننده خود اضافه کنید.
    using Google.Apis.Auth.AspNetCore3;
    using Google.Apis.Auth.OAuth2;
    using Google.Apis.Drive.v3;
    using Google.Apis.Services;
          
  • کنش کنترل‌کننده را به‌صورت زیر اضافه کنید (و آن را با نمایی همراه کنید که مدل IList<string> را دریافت می‌کند):
    /// <summary>
    /// Lists the authenticated user's Google Drive files.
    /// Specifying the <see cref="GoogleScopedAuthorizeAttribute"> will guarantee that the code
    /// executes only if the user is authenticated and has granted the scope specified in the attribute
    /// to this application.
    /// </summary>
    /// <param name="auth">The Google authorization provider.
    /// This can also be injected on the controller constructor.</param>
    [GoogleScopedAuthorize(DriveService.ScopeConstants.DriveReadonly)]
    public async Task<IActionResult> DriveFileList([FromServices] IGoogleAuthProvider auth)
    {
        GoogleCredential cred = await auth.GetCredentialAsync();
        var service = new DriveService(new BaseClientService.Initializer
        {
            HttpClientInitializer = cred
        });
        var files = await service.Files.List().ExecuteAsync();
        var fileNames = files.Files.Select(x => x.Name).ToList();
        return View(fileNames);
    }
          

و این‌ها اصول اولیه هستند. می‌توانید به HomeController.cs از پروژه Google.Apis.Auth.AspNetCore3.IntegrationTests نگاهی بیندازید تا ببینید چگونه می‌توانید به موارد زیر دست پیدا کنید:

  • فقط اصالت‌سنجی کاربر، بدون گستره‌های خاص
  • خروج کاربر از سیستم
  • مجوز افزایشی با کد. توجه داشته باشید که نمونه، مجوز افزایشی را با مشخصه‌ها نشان می‌دهد.
  • بررسی دامنه‌های اعطاشده
  • بررسی کردن ژتون‌های دسترسی و بازآوری
  • کد دسترسی را به‌اجبار بازآوری کنید. توجه داشته باشید که لازم نیست خودتان این کار را انجام دهید زیرا Google.Apis.Auth.AspNetCore3 تشخیص می‌دهد که کد دسترسی منقضی شده است یا نزدیک به انقضا است و به‌طور خودکار آن را بازآوری می‌کند.

حساب سرویس

Google API از حساب‌های سرویس نیز پشتیبانی می‌کند. برخلاف سناریویی که در آن برنامه کارخواه درخواست دسترسی به داده‌های کاربر نهایی را دارد، حساب‌های سرویس دسترسی به داده‌های خود برنامه کارخواه را فراهم می‌کنند.

برنامه کارخواه شما درخواست کد دسترسی را بااستفاده از کلید خصوصی بارگیری‌شده از کنسول Google API امضا می‌کند. پس‌از ایجاد شناسه مشتری جدید، باید نوع برنامه «حساب خدمات» را انتخاب کنید و سپس می‌توانید کلید خصوصی را بارگیری کنید. به نمونه حساب سرویس ما که از Google Plus API استفاده می‌کند نگاهی بیندازید.

using System;
using System.Security.Cryptography.X509Certificates;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Plus.v1;
using Google.Apis.Plus.v1.Data;
using Google.Apis.Services;

namespace Google.Apis.Samples.PlusServiceAccount
{
    /// <summary>
    /// This sample demonstrates the simplest use case for a Service Account service.
    /// The certificate needs to be downloaded from the Google API Console
    /// <see cref="https://console.cloud.google.com/">
    ///   "Create another client ID..." -> "Service Account" -> Download the certificate,
    ///   rename it as "key.p12" and add it to the project. Don't forget to change the Build action
    ///   to "Content" and the Copy to Output Directory to "Copy if newer".
    /// </summary>
    public class Program
    {
        // A known public activity.
        private static String ACTIVITY_ID = "z12gtjhq3qn2xxl2o224exwiqruvtda0i";

        public static void Main(string[] args)
        {
            Console.WriteLine("Plus API - Service Account");
            Console.WriteLine("==========================");

            String serviceAccountEmail = "SERVICE_ACCOUNT_EMAIL_HERE";

            var certificate = new X509Certificate2(@"key.p12", "notasecret", X509KeyStorageFlags.Exportable);

            ServiceAccountCredential credential = new ServiceAccountCredential(
               new ServiceAccountCredential.Initializer(serviceAccountEmail)
               {
                   Scopes = new[] { PlusService.Scope.PlusMe }
               }.FromCertificate(certificate));

            // Create the service.
            var service = new PlusService(new BaseClientService.Initializer()
            {
                HttpClientInitializer = credential,
                ApplicationName = "Plus API Sample",
            });

            Activity activity = service.Activities.Get(ACTIVITY_ID).Execute();
            Console.WriteLine("  Activity: " + activity.Object.Content);
            Console.WriteLine("  Video: " + activity.Object.Attachments[0].Url);

            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }
    }
}

این نمونه یک ServiceAccountCredential ایجاد می‌کند. دامنه‌های لازم تنظیم شده‌اند و تماسی با FromCertificate برقرار شده است، که کلید خصوصی را از X509Certificate2 داده‌شده بار می‌کند. مانند همه کدهای نمونه دیگر، اعتبارنامه به‌صورت HttpClientInitializer تنظیم شده است.