Halaman ini diterjemahkan oleh Cloud Translation API.

OAuth 2.0

Dokumen ini menjelaskan OAuth 2.0, kapan harus menggunakannya, cara mendapatkan client ID, dan cara menggunakannya dengan Library Klien Google API untuk .NET.

Protokol OAuth 2.0

OAuth 2.0 adalah protokol otorisasi yang digunakan oleh Google API. Anda harus membiasakan diri dengan protokol ini dengan membaca tautan berikut:

Memperoleh client ID dan secret klien

Anda bisa mendapatkan client ID dan secret di Konsol API Google. Ada berbagai jenis client ID, jadi pastikan untuk mendapatkan jenis yang tepat untuk aplikasi Anda:

Client ID aplikasi web
Client ID aplikasi terinstal
Client ID Akun layanan

Di setiap cuplikan kode di bawah ini (kecuali di akun Layanan), Anda harus mendownload rahasia klien dan simpan sebagai client_secrets.json dalam project Anda.

Catatan: Anda harus mengubah tindakan Build menjadi "Content" dan kolom Copy to Output Direktori ke "Salin jika lebih baru" di IDE untuk client_secrets.json. Untuk informasi selengkapnya tentang rahasia klien, lihat di Rahasia Klien.

Kredensial

Kredensial pengguna

UserCredential adalah kelas helper thread-safe untuk menggunakan token akses guna mengakses resource yang dilindungi. Token akses biasanya berakhir masa berlakunya setelah 1 jam, dan setelah itu Anda akan mendapatkan pesan {i>error<i} jika Anda mencoba menggunakannya.

UserCredential dan AuthorizationCodeFlow melakukan "penyegaran" otomatis token, yang berarti mendapatkan token akses baru. Hal ini dilakukan menggunakan token refresh yang berumur panjang, yang Anda terima bersama dengan jika Anda menggunakan access_type=offline selama alur kode otorisasi.

Dalam sebagian besar aplikasi, disarankan untuk menyimpan token akses kredensial dan token refresh dalam penyimpanan persisten. Jika tidak, Anda harus memberi pengguna akhir sebuah halaman otorisasi di browser setiap jam, karena akses masa berlaku token habis satu jam setelah Anda menerimanya.

Untuk memastikan token akses dan penyegaran tetap ada, Anda dapat menerapkan sendiri IDataStore, atau Anda dapat menggunakan salah satu implementasi berikut yang disediakan oleh library:

FileDataStore untuk .NET memastikan bahwa kredensial akan tetap ada dalam file.

ServiceAccountCredential

ServiceAccountCredential mirip dengan UserCredential, tetapi memiliki tujuan yang berbeda. Google OAuth 2.0 mendukung interaksi server-ke-server seperti interaksi antara aplikasi web dan Google Cloud Storage. Aplikasi yang meminta harus membuktikan identitasnya sendiri untuk mendapatkan akses ke API, dan pengguna akhir tidak perlu terlibat. ServiceAccountCredential menyimpan kunci pribadi, yang digunakan untuk menandatangani permintaan guna mendapatkan token akses baru.

UserCredential dan ServiceAccountCredential mengimplementasikan IConfigurableHttpClientInitializer sehingga Anda dapat mendaftarkannya masing-masing sebagai:

Pengendali respons yang gagal, sehingga token akan dimuat ulang jika menerima kode status HTTP 401.
Intersepsi, untuk mencegat Authorization {i>header<i} di setiap permintaan.

Aplikasi terpasang

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

Dalam kode contoh ini, instance UserCredential baru dibuat dengan memanggil Metode GoogleWebAuthorizationBroker.AuthorizeAsync. Metode statis ini mendapatkan hal berikut:
- Rahasia klien (atau streaming ke rahasia klien).
- Cakupan yang diperlukan.
- ID pengguna.
- Token pembatalan untuk membatalkan operasi.
- Penyimpanan data opsional. Jika penyimpanan data tidak ditentukan, defaultnya adalah FileDataStore dengan folder Google.Apis.Auth default. Folder dibuat di Environment.SpecialFolder.ApplicationData.
UserCredential yang ditampilkan oleh metode ini disetel sebagai HttpClientInitializer di BooksService (menggunakan penginisialisasi). Seperti yang dijelaskan di atas, UserCredential mengimplementasikan Penginisialisasi klien HTTP.

Perhatikan bahwa dalam kode contoh di atas, informasi rahasia klien dimuat dari file, tetapi Anda juga dapat melakukan hal berikut:

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

Lihat contoh Buku kami.

Aplikasi web (ASP.NET Core 3)

Dukungan Google API OAuth 2.0 untuk Aplikasi Server Web.

Google.Apis.Auth.AspNetCore3 adalah library yang direkomendasikan untuk digunakan oleh sebagian besar aplikasi berbasis Skenario OAuth 2.0 dalam aplikasi ASP.NET Core 3. Alat ini menerapkan Pengendali autentikasi OpenIdConnect. Mendukung autentikasi inkremental, dan menentukan injection yang dapat IGoogleAuthProvider untuk menyediakan kredensial Google yang dapat digunakan dengan Google API.

Bagian ini menjelaskan cara mengonfigurasi dan menggunakan Google.Apis.Auth.AspNetCore3. Kode yang ditampilkan didasarkan pada Google.Apis.Auth.AspNetCore3.IntegrationTests yang merupakan ASP.NET standar yang berfungsi sepenuhnya Aplikasi Core 3.

Jika Anda ingin mengikuti dokumentasi ini sebagai tutorial, Anda memerlukan ASP.NET sendiri Core 3 dan menyelesaikan langkah-langkah ini sebagai prasyarat.

Prasyarat

Instal Google.Apis.Auth.AspNetCore3.
Kami menggunakan Google Drive API sehingga Anda akan juga perlu menginstal Google.Apis.Drive.v3 paket.
Buat project Google Cloud jika Anda belum memilikinya. Ikuti petunjuk ini untuk melakukannya. Ini akan menjadi project yang diidentifikasi dengan aplikasi Anda.
Pastikan untuk mengaktifkan Google Drive API. Untuk mengaktifkan API, ikuti petunjuk ini.
Buat kredensial otorisasi yang akan mengidentifikasi aplikasi Anda ke Google. Ikuti petunjuk ini untuk membuat kredensial otorisasi dan mendownload File client_secrets.json. Dua sorotan:
- Perhatikan bahwa kredensial' harus Web application.
- Untuk menjalankan aplikasi ini, satu-satunya URI pengalihan yang perlu Anda tambahkan adalah https://localhost:5001/signin-oidc.

Konfigurasikan aplikasi Anda untuk menggunakan Google.Apis.Auth.AspNetCore3

Google.Apis.Auth.AspNetCore3 dikonfigurasi dalam kelas Startup atau yang serupa alternatif yang mungkin Anda gunakan. Cuplikan berikut diekstrak dari Startup.cs dalam project Google.Apis.Auth.AspNetCore3.IntegrationTests.

Tambahkan perintah berikut menggunakan perintah ke file Startup.cs Anda.
```
using Google.Apis.Auth.AspNetCore3;
```

Dalam metode Startup.ConfigureServices, tambahkan kode berikut, ubah Placeholder Client ID dan Rahasia Klien dengan nilai yang terdapat dalam File client_secrets.json. Anda dapat memuat nilai ini langsung dari file JSON atau Anda dapat menyimpannya dengan cara aman lainnya. Lihat ClientInfo.Load dalam Google.Apis.Auth.AspNetCore3.IntegrationTests untuk contoh tentang cara memuat nilai ini langsung dari file JSON.

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

Di metode Startup.Configure, pastikan Anda menambahkan autentikasi ASP.NET Core 3 dan otorisasi komponen middleware ke pipeline, serta pengalihan HTTPS:
```
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...
    app.UseHttpsRedirection();
    ...

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

    ...
}
      
```
Catatan: Untuk memahami alasan Anda perlu menggunakan pengalihan HTTPS, baca dokumen tentang Perubahan cookie SameSite diperkenalkan di ASP.NET Core 3.1. Pada dasarnya, agar skenario otentikasi OpenId dapat berfungsi, cookie yang dipertukarkan dengan server identitas harus disetel ke SameSite=None yang juga mengharuskan pengamanan cookie tersebut. Jika aplikasi Anda mendukung permintaan HTTP, maka cara termudah untuk menjamin bahwa cookie identitas telah diamankan adalah dengan mendukung HTTPS dan kemudian mengonfigurasi pengalihan HTTPS.

Menggunakan kredensial pengguna untuk mengakses Google API atas nama mereka

Anda sekarang siap untuk menambahkan metode tindakan ke pengontrol yang memerlukan kredensial pengguna untuk mengakses Google API atas nama mereka. Cuplikan berikut menunjukkan cara menampilkan daftar file pada akun Google Drive pengguna yang diautentikasi. Perhatikan dua hal terutama:

Pengguna tidak hanya perlu diotentikasi, tetapi mereka juga harus memberikan izin https://www.googleapis.com/auth/drive.readonly cakupan ke aplikasi Anda, yang yang Anda tentukan melalui atribut GoogleScopedAuthorize.
Kami menggunakan mekanisme injeksi dependensi standar ASP.NET Core 3 untuk menerima IGoogleAuthProvider yang kita gunakan untuk mendapatkan kredensial pengguna.

Kode:

Pertama-tama, tambahkan berikut ini menggunakan perintah ke pengontrol Anda.

using Google.Apis.Auth.AspNetCore3;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

Menambahkan tindakan pengontrol, sebagai berikut (dan menyertainya dengan tampilan sederhana yang menerima model 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);
}

Dan inilah dasar-dasarnya. Anda dapat melihat HomeController.cs dari project Google.Apis.Auth.AspNetCore3.IntegrationTests untuk mengetahui cara mencapai:

Hanya autentikasi pengguna, tanpa cakupan spesifik
Fungsi logout
Otorisasi inkremental melalui kode. Perhatikan bahwa cuplikan di atas menunjukkan perubahan otorisasi melalui atribut.
Memeriksa cakupan yang saat ini diberikan
Memeriksa akses dan token refresh
Muat ulang token akses secara paksa. Perhatikan bahwa Anda tidak perlu melakukan ini sendiri karena Google.Apis.Auth.AspNetCore3 akan mendeteksi apakah token akses telah kedaluwarsa atau hampir kedaluwarsa dan akan memperbaruinya secara otomatis.

Akun layanan

Google API juga mendukung Akun layanan. Tidak seperti skenario di mana aplikasi klien meminta akses ke data pengguna akhir, akun layanan memberikan akses ke data aplikasi klien itu sendiri.

Aplikasi klien menandatangani permintaan token akses menggunakan kunci pribadi yang didownload dari Konsol API Google. Setelah membuat client ID baru, Anda harus memilih “Akun Layanan” jenis aplikasi dan kemudian Anda dapat mengunduh kunci pribadi. Lihat contoh akun layanan menggunakan 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();
        }
    }
}

Kode contoh di atas membuat ServiceAccountCredential Cakupan yang diperlukan telah ditetapkan dan ada panggilan ke FromCertificate, yang memuat kunci pribadi dari X509Certificate2 yang diberikan. Seperti dalam semua kode contoh lainnya, kredensial ditetapkan sebagai HttpClientInitializer.