本頁面由 Cloud Translation API 翻譯而成。

OAuth 2.0
透過集合功能整理內容你可以依據偏好儲存及分類內容。

本文件將說明 OAuth 2.0、使用時機、取得用戶端 ID 的方式，以及如何搭配 .NET 適用的 Google API 用戶端程式庫使用。

OAuth 2.0 通訊協定

OAuth 2.0 是 Google API 使用的授權通訊協定。請參閱下列連結，熟悉這個通訊協定：

取得用戶端 ID 和密鑰

您可以在 Google API 控制台取得用戶端 ID 和密鑰。用戶端 ID 有不同類型，因此請務必取得應用程式所需的正確類型：

網路應用程式用戶端 ID
已安裝應用程式的用戶端 ID
服務帳戶用戶端 ID

在每個顯示的程式碼片段中 (服務帳戶除外)，您都必須下載用戶端密鑰，並將其儲存在專案中，做為 client_secrets.json。

注意：您必須在 client_secrets.json 的 IDE 中將「Build」動作變更為「Content」，並將「Copy to Output Directory」變更為「Copy if newer」。如要進一步瞭解用戶端密鑰，請參閱「用戶端密鑰」頁面。

憑證

使用者憑證

UserCredential 是執行緒安全的輔助程式類別，可用來使用存取權存取金鑰存取受保護的資源。存取權杖通常會在 1 小時後過期，之後若嘗試使用此權杖將會出現錯誤。

UserCredential 和 AuthorizationCodeFlow 會自動「重新整理」憑證，也就是取得新的存取憑證。這項作業會使用長期有效的更新權杖完成，如果您在授權碼流程中使用 access_type=offline 參數，系統會隨存取權杖一併傳送這項權杖。

在大多數應用程式中，建議您將憑證的存取權杖和重新整理權杖儲存在永久性儲存空間中。否則，您必須每小時在瀏覽器中向使用者顯示授權頁面，因為存取權存證記號會在收到後一小時過期。

為確保存取權和重新整理權杖持續存在，您可以提供自己的 IDataStore 實作項目，也可以使用程式庫提供的下列任一實作項目：

FileDataStore 可確保 .NET 中的憑證會持續存在檔案中。

ServiceAccountCredential

ServiceAccountCredential 與 UserCredential 類似，但用途不同。Google OAuth 2.0 支援伺服器對伺服器的互動行為，例如網頁應用程式和 Google Cloud Storage 之間的互動。發出要求的應用程式必須證明其身分才能存取 API，而且使用者不需要採取任何行動。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();
            ...
        }
    }
}

在這個範例程式碼中，我們會透過呼叫 GoogleWebAuthorizationBroker.AuthorizeAsync 方法來建立新的 UserCredential 例項。這個靜態方法會取得下列項目：
- 用戶端密鑰 (或用戶端密鑰的串流)。
- 必要的範圍。
- 使用者 ID。
- 用於取消作業的取消權杖。
- 選用的資料儲存庫。如果未指定資料儲存庫，預設會使用含有預設 Google.Apis.Auth 資料夾的 FileDataStore。資料夾會在 Environment.SpecialFolder.ApplicationData 中建立。
這個方法傳回的 UserCredential 會設為 BooksService 上的 HttpClientInitializer (使用初始化器)。如先前所述，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 API 支援針對網路伺服器應用程式使用 OAuth 2.0。

在 ASP.NET Core 3 應用程式中， Google.Apis.Auth.AspNetCore3 是建議用於大多數 Google 架構 OAuth 2.0 情境的程式庫。實作 Google 專屬的 OpenIdConnect 驗證處理常式。它支援漸進式驗證，並定義可供注入的 IGoogleAuthProvider，以提供可與 Google API 搭配使用的 Google 憑證。

本節說明如何設定及使用 Google.Apis.Auth.AspNetCore3。這裡顯示的程式碼是根據 Google.Apis.Auth.AspNetCore3.IntegrationTests 所提供的標準 ASP.NET Core 3 應用程式，這也是完整運作的應用程式。

如果您想按照本說明文件中的教學課程操作，則必須先完成下列步驟，並使用自己的 ASP.NET Core 3 應用程式。

必要條件

安裝 Google.Apis.Auth.AspNetCore3 套件。
我們使用的是 Google 雲端硬碟 API，因此您還需要安裝 Google.Apis.Drive.v3 套件。
如果您還沒有 Google Cloud 專案，請建立一個。請按照這篇文章中的操作說明進行操作。這將是應用程式識別的專案。
請務必啟用 Google 雲端硬碟 API。如要啟用 API，請按照這些操作說明進行。
建立授權憑證，讓 Google 識別您的應用程式。請按照這些操作說明建立授權憑證，並下載 client_secrets.json 檔案。兩個重點：
- 請注意，憑證類型必須是「網頁應用程式」。
- 如要執行這個應用程式，您只需要新增 https://localhost:5001/signin-oidc 這個重新導向 URI。

將應用程式設為使用 Google.Apis.Auth.AspNetCore3

Google.Apis.Auth.AspNetCore3 會在 Startup 類別或您可能使用的類似替代方案中設定。以下程式碼片段是從 Google.Apis.Auth.AspNetCore3.IntegrationTests 專案的 Startup.cs 中擷取。

將下列 using 指令新增至 Startup.cs 檔案。
```
using Google.Apis.Auth.AspNetCore3;
```

在 Startup.ConfigureServices 方法中加入以下程式碼，將用戶端 ID 和用戶端密碼預留位置改為 client_secrets.json 檔案中包含的值。您可以直接從 JSON 檔案載入這些值，也可以以任何其他安全方式儲存這些值。請參閱 Google.Apis.Auth.AspNetCore3.IntegrationTests 專案中的 ClientInfo.Load 方法，瞭解如何直接從 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};
        });
}

在 Startup.Configure 方法中，請務必將 ASP.NET Core 3 驗證和授權中介軟體元件新增至管道，以及 HTTPS 重新導向：
```
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...
    app.UseHttpsRedirection();
    ...

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

    ...
}
      
```
注意： 如要瞭解為何需要使用 HTTPS 重新導向，請參閱 ASP.NET Core 3.1 中引進的 SameSite cookie 變更相關說明文件。基本上，為了讓 OpenId 驗證情境運作，與身分識別伺服器交換的 Cookie 必須設為 SameSite=None，而這也需要保護這些 Cookie。如果您的應用程式支援 HTTP 要求，您可以保護支援 HTTPS 的 ID cookie，並設定 HTTPS 重新導向。

使用使用者憑證代表使用者存取 Google API

您現在可以為控制器新增動作方法，這些方法需要使用者憑證才能代替使用者存取 Google API。以下程式碼片段示範如何在已驗證的使用者 Google 雲端硬碟帳戶中列出檔案。請注意以下兩點：

使用者不僅需要通過驗證，還必須將 https://www.googleapis.com/auth/drive.readonly 範圍授予您的應用程式，您可以使用 GoogleScopedAuthorize 屬性指定該範圍。
我們使用 ASP.NET Core 3 的標準依附元件插入機制來接收 IGoogleAuthProvider，用於取得使用者的憑證。

程式碼：

首先，請將下列 using 指令新增至控制器。

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 控制台下載的私密金鑰，為存取權存證要求簽署。建立新的用戶端 ID 後，請選擇服務帳戶應用程式類型，然後即可下載私密金鑰。請參閱使用 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。

OAuth 2.0 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

OAuth 2.0 通訊協定

取得用戶端 ID 和密鑰

憑證

使用者憑證

ServiceAccountCredential

已安裝的應用程式

網頁應用程式 (ASP.NET Core 3)

必要條件

將應用程式設為使用 Google.Apis.Auth.AspNetCore3

使用使用者憑證代表使用者存取 Google API

服務帳戶

OAuth 2.0
透過集合功能整理內容你可以依據偏好儲存及分類內容。