OAuth 2.0

इस दस्तावेज़ में, OAuth 2.0 के बारे में बताया गया है. साथ ही, यह भी बताया गया है कि इसका इस्तेमाल कब करना चाहिए, क्लाइंट आईडी कैसे हासिल करें, और .NET के लिए Google API क्लाइंट लाइब्रेरी के साथ इसका इस्तेमाल कैसे करें.

OAuth 2.0 प्रोटोकॉल

OAuth 2.0, अनुमति देने वाला प्रोटोकॉल है. इसका इस्तेमाल Google API करते हैं. आपको इन लिंक पर जाकर, प्रोटोकॉल के बारे में जानकारी मिल सकती है:

क्लाइंट आईडी और सीक्रेट पाना

क्लाइंट आईडी और पासवर्ड, Google API कंसोल से लिए जा सकते हैं. क्लाइंट आईडी अलग-अलग तरह के होते हैं, इसलिए अपने ऐप्लिकेशन के लिए सही टाइप का आईडी चुनें:

दिखाए गए हर कोड स्निपेट में (सेवा खाते के अलावा), आपको क्लाइंट पासकोड डाउनलोड करना होगा और उसे अपने प्रोजेक्ट में client_secrets.json के तौर पर सेव करना होगा.

क्रेडेंशियल

उपयोगकर्ता के क्रेडेंशियल

UserCredential यह थ्रेड-सेफ़ हेल्पर क्लास है. इसका इस्तेमाल, सुरक्षित संसाधनों को ऐक्सेस करने के लिए ऐक्सेस टोकन का इस्तेमाल करने के लिए किया जाता है. आम तौर पर, ऐक्सेस टोकन एक घंटे के बाद खत्म हो जाता है. इसके बाद, इसका इस्तेमाल करने पर आपको गड़बड़ी का मैसेज दिखेगा.

UserCredential और AuthorizationCodeFlow टोकन को अपने-आप "रीफ़्रेश" करने की सुविधा चालू करें. इसका मतलब है कि आपको एक नया ऐक्सेस टोकन मिलेगा. ऐसा लंबे समय तक चलने वाले रीफ़्रेश टोकन का इस्तेमाल करके किया जाता है. यह टोकन, ऑथराइज़ेशन कोड फ़्लो के दौरान access_type=offline पैरामीटर का इस्तेमाल करने पर, ऐक्सेस टोकन के साथ मिलता है.

ज़्यादातर ऐप्लिकेशन में, हमारा सुझाव है कि आप क्रेडेंशियल के ऐक्सेस टोकन और रीफ़्रेश टोकन को पर्सिस्टेंट स्टोरेज में सेव करें. ऐसा न करने पर, आपको असली उपयोगकर्ता को हर घंटे ब्राउज़र में अनुमति वाला पेज दिखाना होगा. ऐसा इसलिए, क्योंकि ऐक्सेस टोकन मिलने के एक घंटे बाद उसकी समयसीमा खत्म हो जाती है.

ऐक्सेस और रीफ़्रेश टोकन के बने रहने की पुष्टि करने के लिए, IDataStore को लागू करने का अपना तरीका दिया जा सकता है. इसके अलावा, लाइब्रेरी में दिए गए इनमें से किसी एक तरीके का इस्तेमाल भी किया जा सकता है:

  • .NET के लिए FileDataStore यह पक्का करता है कि क्रेडेंशियल, फ़ाइल में हमेशा मौजूद रहेगा.

ServiceAccountCredential

ServiceAccountCredential UserCredential से मिलता-जुलता है, लेकिन इसका मकसद अलग है. Google OAuth 2.0, सर्वर-टू-सर्वर इंटरैक्शन के साथ काम करता है. जैसे, वेब ऐप्लिकेशन और Google Cloud Storage के बीच इंटरैक्शन. एपीआई का ऐक्सेस पाने के लिए, अनुरोध करने वाले ऐप्लिकेशन को अपनी पहचान साबित करनी होगी. इसमें असली उपयोगकर्ता की ज़रूरत नहीं होती. ServiceAccountCredential में एक निजी कुंजी सेव होती है. इसका इस्तेमाल, नया ऐक्सेस टोकन पाने के अनुरोध पर हस्ताक्षर करने के लिए किया जाता है.

UserCredential और ServiceAccountCredential, दोनों में IConfigurableHttpClientInitializer लागू होता है इसलिए, इनमें से हर एक को इन तौर पर रजिस्टर किया जा सकता है:

  • रिस्पॉन्स हैंडलर काम नहीं कर रहा है, इसलिए अगर उसे एचटीटीपी 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();
            ...
        }
    }
}

  • इस सैंपल कोड में, GoogleWebAuthorizationBroker.AuthorizeAsync मेथड को कॉल करके एक नया UserCredential इंस्टेंस बनाया गया है. इस स्टैटिक तरीके में ये चीज़ें मिलती हैं:

    • क्लाइंट सीक्रेट (या क्लाइंट सीक्रेट की स्ट्रीम).
    • ज़रूरी स्कोप.
    • उपयोगकर्ता आइडेंटिफ़ायर.
    • किसी कार्रवाई को रद्द करने के लिए रद्द करने का टोकन.
    • डेटास्टोर (ज़रूरी नहीं). अगर डेटास्टोर की जानकारी नहीं दी गई है, तो डिफ़ॉल्ट रूप से FileDataStore का इस्तेमाल किया जाता है. साथ ही, डिफ़ॉल्ट Google.Apis.Auth फ़ोल्डर भी इस्तेमाल किया जाता है. फ़ोल्डर Environment.SpecialFolder.ApplicationData में बनाया गया है.

  • इस तरीके से मिलने वाला UserCredential, BooksService पर HttpClientInitializer के तौर पर सेट किया जाता है. इसके लिए, initializer का इस्तेमाल किया जाता है. जैसा कि पहले बताया गया है, UserCredential एक एचटीटीपी क्लाइंट को शुरू करने वाला टूल लागू करता है.

  • ध्यान दें कि सैंपल कोड में, क्लाइंट सेक्रेट की जानकारी किसी फ़ाइल से लोड की गई है, लेकिन ये काम भी किए जा सकते हैं: 

    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 API, वेब सर्वर ऐप्लिकेशन के लिए OAuth 2.0 के साथ काम करते हैं.

ASP.NET Core 3 ऐप्लिकेशन में, Google के आधार पर OAuth 2.0 के ज़्यादातर मामलों में, Google.Apis.Auth.AspNetCore3 लाइब्रेरी का इस्तेमाल करने का सुझाव दिया जाता है. यह Google के हिसाब से OpenIdConnect पुष्टि करने वाला हैंडलर लागू करता है. यह इंक्रीमेंटल पुष्टि की सुविधा के साथ काम करता है. साथ ही, Google के क्रेडेंशियल देने के लिए, इंजेक्शन के तौर पर इस्तेमाल होने वाला IGoogleAuthProvider तय करता है. इन क्रेडेंशियल का इस्तेमाल, Google API के साथ किया जा सकता है.

इस सेक्शन में, 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 क्लास या मिलते-जुलते किसी ऐसे विकल्प में कॉन्फ़िगर किया गया है जिसका इस्तेमाल किया जा सकता है. यहां दिए गए स्निपेट, Google.Apis.Auth.AspNetCore3.IntegrationTests प्रोजेक्ट में मौजूद Startup.cs से निकाले गए हैं.

  • अपनी Startup.cs फ़ाइल में, डायरेक्टिव का इस्तेमाल करके ये जोड़ें. 
    using Google.Apis.Auth.AspNetCore3;
  • Startup.ConfigureServices तरीके में, नीचे दिया गया कोड जोड़ें. साथ ही, क्लाइंट आईडी और क्लाइंट सीक्रेट प्लेसहोल्डर को client_secrets.json फ़ाइल में मौजूद वैल्यू से बदलें. इन वैल्यू को सीधे JSON फ़ाइल से लोड किया जा सकता है या इन्हें किसी भी सुरक्षित तरीके से सेव किया जा सकता है. इन वैल्यू को सीधे JSON फ़ाइल से लोड करने का उदाहरण देखने के लिए, Google.Apis.Auth.AspNetCore3.IntegrationTests प्रोजेक्ट में ClientInfo.Load तरीके को देखें. 
    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 मिडलवेयर कॉम्पोनेंट को ज़रूर जोड़ें: 
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...
    app.UseHttpsRedirection();
    ...

    app.UseAuthentication();
    app.UseAuthorization();

    ...
}

उपयोगकर्ता की ओर से Google API ऐक्सेस करने के लिए, उसके क्रेडेंशियल का इस्तेमाल करना

अब आपके पास अपने कंट्रोलर में कार्रवाई के ऐसे तरीके जोड़ने का विकल्प है जिनके लिए उपयोगकर्ता के क्रेडेंशियल की ज़रूरत होती है, ताकि उपयोगकर्ता की ओर से Google API को ऐक्सेस किया जा सके. नीचे दिए गए स्निपेट में, पुष्टि किए गए उपयोगकर्ता के 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);
}

ये बुनियादी बातें हैं. Google.Apis.Auth.AspNetCore3.IntegrationTests प्रोजेक्ट में, HomeController.cs को देखकर यह पता लगाया जा सकता है कि ये काम कैसे किए जा सकते हैं:

  • सिर्फ़ उपयोगकर्ता की पुष्टि, बिना किसी खास दायरे के
  • उपयोगकर्ता का लॉग आउट
  • कोड की मदद से, धीरे-धीरे अनुमति देना. ध्यान दें कि सैंपल में एट्रिब्यूट के साथ, ऐक्सेस की अनुमति को बढ़ाने का तरीका दिखाया गया है.
  • ऐक्सेस के लिए दिए गए स्कोप की जांच करना
  • ऐक्सेस और रीफ़्रेश टोकन की जांच करना
  • ऐक्सेस टोकन को ज़बरदस्ती रीफ़्रेश करें. ध्यान दें कि आपको ऐसा खुद करने की ज़रूरत नहीं है, क्योंकि 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 के तौर पर सेट किया गया है.