本文档介绍了 OAuth 2.0, 何时使用 如何获取客户端 ID 以及如何将其与适用于 .NET 的 Google API 客户端库结合使用。
OAuth 2.0 协议
OAuth 2.0 是 Google API 使用的授权协议。 请参阅以下链接,熟悉该协议:
获取客户端 ID 和密钥
您可以在 Google API 控制台上获取客户端 ID 和密钥。 客户端 ID 有多种类型 因此请务必获取正确的应用类型:
。 <ph type="x-smartling-placeholder">
在下面每个代码段(服务账号除外)中,您必须下载
客户端密钥并将其存储为 client_secrets.json
在您的项目中。
凭据
用户凭据
UserCredential
是一个线程安全辅助类,用于使用访问令牌访问受保护的资源。
访问令牌通常会在 1 小时后过期
之后,如果您尝试使用它,将会收到错误消息。
UserCredential
和
AuthorizationCodeFlow
负责自动“刷新”也就是获取
一个新的访问令牌。
为此,您需要接收长期刷新令牌以及
访问令牌(如果使用
access_type=offline
参数的值。
在大多数应用中,建议将 凭据的访问令牌和刷新令牌(位于永久性存储空间中)。 否则,您需要向最终用户展示 授权页面,因为其 令牌将在您收到一个小时后过期。
为了确保访问令牌和刷新令牌仍然存在
则可以提供自己的
IDataStore
、
或者,您也可以使用库提供的以下实现之一:
-
FileDataStore
可确保该凭据在文件中永久有效。
ServiceAccountCredential
ServiceAccountCredential
与 UserCredential
类似,但用途不同。
Google OAuth 2.0 支持服务器到服务器的互动,例如 Web 应用和 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(); ... } } }
-
此示例代码创建了一个新的
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"));
请查看我们的图书示例。
Web 应用 (ASP.NET Core 3)
Google API 支持 <ph type="x-smartling-placeholder"></ph> 适用于网络服务器应用的 OAuth 2.0。
推荐使用 Google.Apis.Auth.AspNetCore3 的库
ASP.NET Core 3 应用中的 OAuth 2.0 场景。它会实施 Google 专有的
OpenIdConnect
身份验证处理程序。它支持增量身份验证,并定义了可注入的
IGoogleAuthProvider
,用于提供可用于 Google API 的 Google 凭据。
本部分介绍了如何配置和使用 Google.Apis.Auth.AspNetCore3。显示的代码 依据的是 <ph type="x-smartling-placeholder"></ph> Google.Apis.Auth.AspNetCore3.IntegrationTests 是一个完全正常运行的标准 ASP.NET Core 3 应用。
如果您想按照本文档的教程进行操作,则需要使用自己的 ASP.NET 核心 3 应用,并完成这些步骤作为前提条件。
前提条件
- 安装 <ph type="x-smartling-placeholder"></ph> Google.Apis.Auth.AspNetCore3 软件包。
- 我们使用的是 Google Drive API,因此您将 还需要安装 Google.Apis.Drive.v3 软件包。
- 如果您还没有 Google Cloud 项目,请先创建一个。关注 <ph type="x-smartling-placeholder"></ph> 这些说明来执行此操作。这将是标识您的应用的项目。
- 请务必启用 Google Drive API。如需启用 API,请按照 <ph type="x-smartling-placeholder"></ph> 这些说明。
-
创建授权凭据,以便 Google 识别您的应用。关注
<ph type="x-smartling-placeholder"></ph>
按照说明创建授权凭据,并下载
client_secrets.json
文件。有两大亮点: <ph type="x-smartling-placeholder">- </ph>
- 请注意,凭据的类型必须是 Web 应用。
- 要运行此应用,您需要添加的唯一重定向 URI 是
https://localhost:5001/signin-oidc
。
将您的应用配置为使用 Google.Apis.Auth.AspNetCore3
Google.Apis.Auth.AspNetCore3 在 Startup
类或类似类中配置
您可能使用的替代方案以下代码段提取自
<ph type="x-smartling-placeholder"></ph>
Google.Apis.Auth.AspNetCore3.IntegrationTests 项目中的 Startup.cs
。
-
将以下 using 指令添加到
Startup.cs
文件中。using Google.Apis.Auth.AspNetCore3;
-
在
Startup.ConfigureServices
方法中,添加以下代码,更改 客户端 ID 和客户端密钥占位符,其中包含client_secrets.json
文件。您可以直接从 JSON 文件加载这些值 您也可以采用任何其他安全方式存储它们。请参阅 <ph type="x-smartling-placeholder"></ph> 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(); ... }
使用用户凭据代表他们访问 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); }
以上就是基本知识您可以参阅
<ph type="x-smartling-placeholder"></ph>
来自 Google.Apis.Auth.AspNetCore3.IntegrationTests 项目的 HomeController.cs
了解如何实现以下目标:
- 仅限用户身份验证,无特定范围
- 退出功能
- 通过代码进行增量授权。请注意,上面的代码段显示的是 通过属性进行授权。
- 检查当前授予的范围
- 检查访问令牌和刷新令牌
- 强制刷新访问令牌。请注意,您不必自行创建 Google.Apis.Auth.AspNetCore3 将检测访问令牌是否已过期或即将过期 并会自动刷新
服务账号
Google API 还支持 服务账号。 与客户端应用请求访问最终用户数据的场景不同, 服务账号提供对客户端应用自身数据的访问权限。
您的客户端应用使用下载的私钥对访问令牌请求进行签名 访问 Google API 控制台。 创建新的客户端 ID 后,您应选择“Service Account”(服务账号) 然后您可以下载私钥。 请查看我们的 <ph type="x-smartling-placeholder"></ph> 使用 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
。