OAuth 2.0

Bu belgede OAuth 2.0 açıklanmaktadır. ne zaman kullanılacağını nasıl edinileceğini, ve .NET için Google API İstemci Kitaplığı ile nasıl kullanılacağını anlatacağım.

OAuth 2.0 Protokolü

OAuth 2.0, Google API'leri tarafından kullanılan yetkilendirme protokolüdür. Aşağıdaki bağlantıları okuyarak protokolü daha iyi öğrenebilirsiniz:

İstemci kimliklerini ve gizli anahtarları edinme

İstemci kimliklerini ve gizli anahtarları Google API Konsolu'ndan alabilirsiniz. Farklı türde istemci kimlikleri, Bu nedenle, uygulamanız için doğru türü seçtiğinizden emin olun:

ziyaret edin.

Aşağıdaki kod snippet'lerinin her birinde (birinci Hizmet hesabı hariç), istemci gizli anahtarını oluşturun ve projenizde client_secrets.json olarak depolayın.

Kimlik bilgileri

Kullanıcı kimlik bilgileri

UserCredential korumalı kaynaklara erişmek üzere erişim jetonu kullanmaya yönelik iş parçacığı açısından güvenli bir yardımcı sınıftır. Erişim jetonunun süresi genellikle 1 saat sonra dolar. Sonrasında, kullanmaya çalışırsanız bir hata alırsınız.

UserCredential ve AuthorizationCodeFlow otomatik olarak "yenilenen" Bu da yeni web sitesi oluşturmak için yeni bir erişim jetonu ekleyebilirsiniz. Bu, access_type=offline parametresini kontrol edin.

Çoğu uygulamada, varsayılan olarak kimlik bilgisinin erişim jetonu ve yenileme jetonunun kalıcı depolama alanında depolanmasını sağlar. Aksi takdirde, son kullanıcıya bir her saat başı bir yetkilendirme sayfası görüntülenir. Çünkü jetonun süresi, alındıktan bir saat sonra dolar.

Erişim ve yenileme jetonlarının kalıcı olduğundan emin olmak için kendi uygulamanızı kullanabilir IDataStore veya kitaplık tarafından sağlanan aşağıdaki uygulamalardan birini kullanabilirsiniz:

  • FileDataStore için .NET, kimlik bilgisinin dosyada kalıcı olmasını sağlar.

ServiceAccountCredential

ServiceAccountCredential UserCredential ile benzer ancak farklı bir amaca hizmet eder. Google OAuth 2.0, bir web uygulaması ile Google Cloud Storage arasındaki etkileşimler gibi, sunucular arası etkileşimleri destekler. İstekte bulunan uygulamanın bir API'ye erişmek için kendi kimliğini kanıtlaması gerekir ve son kullanıcının bu sürece dahil olması gerekmez. ServiceAccountCredential, yeni bir erişim jetonu almak amacıyla isteği imzalamak için kullanılan bir özel anahtar depolar.

Hem UserCredential hem de ServiceAccountCredential uygulaması IConfigurableHttpClientInitializer Dolayısıyla bunların her birini aşağıdaki şekilde kaydedebilirsiniz:

  • Başarısız bir yanıt işleyici, Bu nedenle, HTTP 401 durum kodu aldığında jetonu yeniler.
  • Authorization noktasına müdahale etmek için bir müdahale aracı başlığını kullanın.

Yüklü uygulamalar

Books API'nin kullanıldığı örnek kod: 

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();
            ...
        }
    }
}

  • Bu örnek koddaUserCredential GoogleWebAuthorizationBroker.AuthorizeAsync yöntemini çağırın. Bu statik yöntem şunları alır:

    • İstemci gizli anahtarı (veya istemci gizli anahtarının akışı).
    • Gerekli kapsamlar.
    • Kullanıcı tanımlayıcısı.
    • Bir işlemi iptal etmek için kullanılan iptal jetonu.
    • İsteğe bağlı bir veri deposu. Veri deposu belirtilmezse varsayılan olarak FileDataStore değeri kullanılır. varsayılan bir Google.Apis.Auth klasörüyle. Klasör Environment.SpecialFolder.ApplicationData konumunda oluşturulur.

  • Bu yöntemle döndürülen UserCredential, HttpClientInitializer olarak ayarlanır. BooksService (başlatıcıyı kullanarak) üzerinde görebilirsiniz. Yukarıda açıklandığı gibi, UserCredential, HTTP istemci başlatıcı.

  • Yukarıdaki örnek kodda, istemci gizli anahtarı bilgilerinin bir dosyadan yüklendiğine dikkat edin. ancak aşağıdakileri de yapabilirsiniz: 

    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"));

Kitaplar örneğimize göz atın.

Web uygulamaları (ASP.NET Core 3)

Google API'leri desteği Web Sunucusu Uygulamaları için OAuth 2.0.

Google.Apis.Auth.AspNetCore3, Google tabanlı çoğu cihazda kullanılması önerilen kitaplıktır ASP.NET Core 3 uygulamalarında OAuth 2.0 senaryoları. Bu, Google'a özel bir OpenIdConnect kimlik doğrulama işleyici. Artımlı kimlik doğrulamayı destekler ve Google API'leriyle kullanılabilecek Google kimlik bilgilerini sağlamak için IGoogleAuthProvider.

Bu bölümde, Google.Apis.Auth.AspNetCore3'ü nasıl yapılandırıp kullanacağınız açıklanmaktadır. Gösterilen kod Burada, Tamamen çalışan standart bir ASP.NET olan Google.Apis.Auth.AspNetCore3.IntegrationTests Core 3 uygulaması.

Bu dokümanları eğitim olarak takip etmek istiyorsanız kendi ASP.NET'inize ihtiyacınız olacaktır. ve bu adımları tamamlamanızı öneririz.

Ön koşullar

  • Şunu yükleyin: Google.Apis.Auth.AspNetCore3 paketiyle senkronize edilir.
  • Google Drive API kullandığımızdan ayrıca Google.Apis.Drive.v3 paketinden yararlanın.
  • Henüz yoksa bir Google Cloud projesi oluşturun. Takip et bu talimatları uygulayın. Bu, uygulamanızın tanımlandığı proje olacaktır.
  • Google Drive API'yi etkinleştirdiğinizden emin olun. API'leri etkinleştirmek için şu talimatları uygulayın: inceleyin.
  • Uygulamanızı Google'a tanıtacak yetkilendirme kimlik bilgileri oluşturun. Takip et yetkilendirme bilgilerini oluşturmak ve client_secrets.json dosyası. Öne çıkan iki özellik:
    • Kimlik bilgilerinin type Web application (Web uygulaması) olmalıdır.
    • Bu uygulamayı çalıştırmak için eklemeniz gereken tek yönlendirme URI'si https://localhost:5001/signin-oidc

Uygulamanızı Google.Apis.Auth.AspNetCore3'ü kullanacak şekilde yapılandırın

Google.Apis.Auth.AspNetCore3, Startup sınıfında veya benzeri bir şekilde yapılandırılmıştır ya da mevcut bir alternatifi ifade eder. Aşağıdaki snippet'ler Startup.cs: Google.Apis.Auth.AspNetCore3.IntegrationTests projesi.

  • Aşağıdaki use yönergesini Startup.cs dosyanıza ekleyin. 
    using Google.Apis.Auth.AspNetCore3;
  • Startup.ConfigureServices yönteminde aşağıdaki kodu ekleyin, İstemci Kimliği ve İstemci Gizli Anahtarı yer tutucuları client_secrets.json dosya Bu değerleri doğrudan JSON dosyasından yükleyebilirsiniz ya da bunları başka güvenli yöntemlerle saklayabilirsiniz. Şu bölüme göz atın: Google.Apis.Auth.AspNetCore3.IntegrationTests içindeki ClientInfo.Load yöntemi projesindeki en iyi uygulamaları paylaşacağız. 
    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 yönteminde ASP.NET Core 3 kimlik doğrulamasını eklediğinizden emin olun. HTTPS yönlendirmelerinin yanı sıra ara katman yazılımı bileşenlerini ardışık düzende yetkilendirme: 
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...
    app.UseHttpsRedirection();
    ...

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

    ...
}

Kendi adına Google API'lerine erişmek için kullanıcı kimlik bilgisini kullanın

Artık denetleyicilerinize kullanıcı kimlik bilgilerinin girilmesini gerektiren işlem yöntemleri eklemeye hazırsınız. Google API'lerine kendi adlarına erişebilirler. Aşağıdaki snippet'te kimliği doğrulanmış kullanıcının Google Drive hesabı. Çoğunlukla iki şeye dikkat edin:

  • Kullanıcı kimliğinin doğrulanması, kullanıcının Bu, uygulamanızın https://www.googleapis.com/auth/drive.readonly kapsamında olmasını sağlar. GoogleScopedAuthorize özelliği ile belirtirsiniz.
  • ASP.NET Core 3'ün standart bağımlılık yerleştirme mekanizmasını kullanarak Kullanıcının kimlik bilgilerini almak için kullandığımız IGoogleAuthProvider.

Kod:

  • Öncelikle aşağıdaki kullanarak yönergeleri denetleyicinize ekleyin. 
    using Google.Apis.Auth.AspNetCore3;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;
  • Denetleyici işlemini aşağıdaki gibi ekleyin (ve basit bir görünümle ona eşlik edin) IList<string> modeli alan): 
    /// <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);
}

Bunlar en temel bilgilerdir. Web sitemiz g.co/newsinitiative/labs üzerinden Google.Apis.Auth.AspNetCore3.IntegrationTests projesinden HomeController.cs neler yapabileceğinizi öğrenebilirsiniz:

  • Belirli bir kapsam olmadan yalnızca kullanıcı kimlik doğrulaması
  • Çıkış işlevi
  • Kod aracılığıyla artımlı yetkilendirme. Yukarıdaki snippet'in artımlı özellikler aracılığıyla yetkilendirme.
  • Geçerli olarak izin verilen kapsamları inceleyin
  • Erişimi inceleyin ve jetonları yenileyin
  • Erişim jetonunu zorla yenileyin. Bunu sizin yapmanız gerekmez. Çünkü Google.Apis.Auth.AspNetCore3, erişim jetonunun süresinin dolup dolmadığını veya dolmak üzere olduğunu algılar otomatik olarak yeniler.

Hizmet hesabı

Google API'leri ayrıca, Hizmet hesapları. İstemci uygulamasının son kullanıcının verilerine erişim istediği senaryodan farklı olarak, hizmet hesapları, istemci uygulamasının kendi verilerine erişim sağlar.

İstemci uygulamanız, erişim jetonu isteğini, indirilen bir özel anahtarı kullanarak imzalar Google API Konsolu'ndan alabilirsiniz. Yeni bir istemci kimliği oluşturduktan sonra "Hizmet Hesabı"nı seçmelisiniz. özel anahtarı indirebilirsiniz. Şu bölüme göz atın: Google Plus API'yi kullanan hizmet hesabı örneği. 

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();
        }
    }
}

Yukarıdaki örnek kod, ServiceAccountCredential. Gerekli kapsamlar ayarlandı ve FromCertificate için bir çağrı var. Bu işlem, belirtilen X509Certificate2 öğesinden özel anahtarı yükler. Diğer tüm örnek kodlarında olduğu gibi kimlik bilgisi HttpClientInitializer olarak ayarlanır.