概览
目的:本文档说明了如何使用 GoogleCredential 实用程序类对 Google 服务执行 OAuth 2.0 授权。对于 通用 OAuth 2.0 函数的相关信息,请参阅 适用于 Java 的 OAuth 2.0 和 Google OAuth 客户端库。
摘要:若要访问存储在 Google 服务的受保护数据,请使用 OAuth 2.0,用于授权。 Google API 支持适用于不同类型的客户端应用的 OAuth 2.0 流程。 在所有这些流程中,客户端应用请求一个访问令牌, 仅与您的客户端应用以及受保护数据的所有者相关联 资源。访问令牌还与有限范围相关联 定义您的客户端应用可以访问的数据类型(例如, “管理您的任务”)。OAuth 2.0 的一个重要目标是 访问受保护的数据,同时将潜在影响降至最低, 如果访问令牌被盗,则会发生该错误。
适用于 Java 的 Google API 客户端库中的 OAuth 2.0 软件包基于 是通用的 适用于 Java 的 Google OAuth 2.0 客户端库。
如需了解详情,请参阅以下软件包的 Javadoc 文档:
- com.google.api.client.googleapis.auth.oauth2 (来自 google-api-client)
- com.google.api.client.googleapis.extensions.appengine.auth.oauth2 (来自 google-api-client-appengine)
Google API 控制台
您需要先在 Google API 控制台,用于进行身份验证和结算 您的客户端是安装版应用、移动应用, 网络服务器或在浏览器中运行的客户端。
有关如何正确设置凭据的说明,请参阅 API 控制台帮助。
凭据
GoogleCredential
GoogleCredential 是适用于 OAuth 2.0 的线程安全帮助程序类,用于访问受保护的资源 使用访问令牌例如,如果您已经有一个访问令牌, 可以通过以下方式发出请求:
GoogleCredential credential = new GoogleCredential().setAccessToken(accessToken); Plus plus = new Plus.builder(new NetHttpTransport(), GsonFactory.getDefaultInstance(), credential) .setApplicationName("Google-PlusSample/1.0") .build();
Google App Engine 身份
此备用凭据基于 Google App Engine App Identity Java API。 这不同于客户端应用请求访问 最终用户的数据后,App Identity API 会提供对客户端数据的访问 应用自己的数据。
使用 AppIdentityCredential (来自 google-api-client-appengine)。 这个凭据要简单得多,因为 Google App Engine 会为您处理 了解详情您只需指定所需的 OAuth 2.0 范围。
摘自 urlshortener-robots-appengine-sample 的示例代码:
static Urlshortener newUrlshortener() { AppIdentityCredential credential = new AppIdentityCredential( Collections.singletonList(UrlshortenerScopes.URLSHORTENER)); return new Urlshortener.Builder(new UrlFetchTransport(), GsonFactory.getDefaultInstance(), credential) .build(); }
数据存储区
访问令牌的有效期通常为 1 小时,有效期为 1 小时
则会收到错误消息。
GoogleCredential
负责自动“刷新”也就是获取
一个新的访问令牌。这是通过长效刷新令牌实现的
如果您使用
access_type=offline
参数(请参阅
GoogleAuthorizationCodeFlow.Builder.setAccessType(String))。
大多数应用都需要保留凭据的访问令牌,并且/或者 刷新令牌。如需保留凭据的访问和/或刷新令牌,您可以 提供您自己的 DataStoreFactory 实现 使用 StoredCredential; 或者,您也可以使用库提供的以下实现之一:
- AppEngineDataStoreFactory: 使用 Google App Engine Data Store API 保留凭据。
- MemoryDataStoreFactory: “永久”将凭据存储在内存中,这只能用作进程生命周期的短期存储。
- FileDataStoreFactory: 会将凭据保留在文件中
AppEngine 用户: AppEngineCredentialStore 已被弃用,很快就会被移除。我们建议您使用 AppEngineDataStoreFactory 与 StoredCredential 搭配使用。 如果您以旧方式存储凭据,则可以使用新添加的 辅助方法 migrateTo(AppEngineDataStoreFactory) 或 migrateTo(DataStore) 进行迁移
您可以使用 DataStoreCredentialRefreshListener 并使用 GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener) 为凭据设置该窗格)。
授权代码流程
使用授权代码流程,让最终用户能够向您的应用授权 访问其在 Google API 上受保护的数据。此流程的协议为 指定 授权代码授权。
此流程是使用 GoogleAuthorizationCodeFlow 实现的。 具体步骤包括:
- 最终用户登录您的应用。您需要将该用户 唯一用户 ID。
- 调用 AuthorizationCodeFlow.loadCredential(String)) 检查最终用户的凭据是否已知。 如果是,就大功告成了。
- 如果没有,请调用 AuthorizationCodeFlow.newAuthorizationUrl() 并将最终用户的浏览器定向到授权页面, 以便应用访问其受保护的数据
- Google 授权服务器随后会将浏览器重定向回
由您的应用指定的重定向网址,以及
code
查询 参数。使用code
参数请求获取符合以下条件的访问令牌: AuthorizationCodeFlow.newTokenRequest(String))。 - 使用 AuthorizationCodeFlow.createAndStoreCredential(TokenResponse, String)) 来存储并获取用于访问受保护资源的凭据。
或者,如果您没有使用 GoogleAuthorizationCodeFlow,也可以使用较低级别的类:
- 使用 DataStore.get(String) 根据用户 ID 从存储区加载凭据。
- 使用 GoogleAuthorizationCodeRequestUrl 将浏览器定向到授权页面。
- 使用 AuthorizationCodeResponseUrl 处理授权响应并解析授权代码。
- 使用 GoogleAuthorizationCodeTokenRequest 请求一个访问令牌,还可能需要请求一个刷新令牌。
- 创建一个新的 GoogleCredential 并使用 DataStore.set(String, V) 存储它。
- 使用
GoogleCredential
访问受保护的资源。过期的访问令牌会使用刷新令牌(如适用)自动进行刷新。请务必使用 DataStoreCredentialRefreshListener,并使用 GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener) 为凭据设置该键。
当您在 Google API 控制台中设置项目时, 您可以根据自己使用的流程选择不同的凭据。 有关详情,请参阅设置 OAuth 2.0 和 OAuth 2.0 场景。 每个流程的代码段如下所示。
Web 服务器应用
有关此流程协议的说明 针对网络服务器应用使用 OAuth 2.0。
此库提供 servlet 帮助程序类,以显著简化 基本用例的授权代码流程。您只需提供具体的子类 属于 AbstractAuthorizationCodeServlet 和 AbstractAuthorizationCodeCallbackServlet (来自 google-oauth-client-servlet) 并将其添加到您的 web.xml 文件中请注意,您仍然需要处理 登录并提取用户 ID。
public class CalendarServletSample extends AbstractAuthorizationCodeServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { // do stuff } @Override protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { GenericUrl url = new GenericUrl(req.getRequestURL().toString()); url.setRawPath("/oauth2callback"); return url.build(); } @Override protected AuthorizationCodeFlow initializeFlow() throws IOException { return new GoogleAuthorizationCodeFlow.Builder( new NetHttpTransport(), GsonFactory.getDefaultInstance(), "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]", Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( DATA_STORE_FACTORY).setAccessType("offline").build(); } @Override protected String getUserId(HttpServletRequest req) throws ServletException, IOException { // return user ID } } public class CalendarServletCallbackSample extends AbstractAuthorizationCodeCallbackServlet { @Override protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential) throws ServletException, IOException { resp.sendRedirect("/"); } @Override protected void onError( HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse) throws ServletException, IOException { // handle error } @Override protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { GenericUrl url = new GenericUrl(req.getRequestURL().toString()); url.setRawPath("/oauth2callback"); return url.build(); } @Override protected AuthorizationCodeFlow initializeFlow() throws IOException { return new GoogleAuthorizationCodeFlow.Builder( new NetHttpTransport(), GsonFactory.getDefaultInstance() "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]", Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( DATA_STORE_FACTORY).setAccessType("offline").build(); } @Override protected String getUserId(HttpServletRequest req) throws ServletException, IOException { // return user ID } }
Google App Engine 应用
App Engine 上的授权代码流程与 servlet 几乎完全相同。 授权代码流程,只不过我们可以使用 Google App Engine 的 Users Java API。用户 需要登录以启用用户 Java API;了解 将用户重定向到登录页面,请参阅 安全和身份验证 (在 web.xml 中)。
与 servlet 方案的主要区别在于:您提供了
的子类
AbstractAppEngineAuthorizationCodeServlet 和 AbstractAppEngineAuthorizationCodeCallbackServlet
(来自 google-oauth-client-appengine。
它们扩展了抽象 Servlet 类并实现 getUserId
方法
帮助您使用用户 Java API。AppEngineDataStoreFactory
(来自 google-http-client-appengine)
是使用 Google App Engine 数据保留凭据的
Store API。
从 calendar-appengine-sample 中获取的示例(略微修改):
public class CalendarAppEngineSample extends AbstractAppEngineAuthorizationCodeServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { // do stuff } @Override protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { return Utils.getRedirectUri(req); } @Override protected AuthorizationCodeFlow initializeFlow() throws IOException { return Utils.newFlow(); } } class Utils { static String getRedirectUri(HttpServletRequest req) { GenericUrl url = new GenericUrl(req.getRequestURL().toString()); url.setRawPath("/oauth2callback"); return url.build(); } static GoogleAuthorizationCodeFlow newFlow() throws IOException { return new GoogleAuthorizationCodeFlow.Builder(HTTP_TRANSPORT, JSON_FACTORY, getClientCredential(), Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( DATA_STORE_FACTORY).setAccessType("offline").build(); } } public class OAuth2Callback extends AbstractAppEngineAuthorizationCodeCallbackServlet { private static final long serialVersionUID = 1L; @Override protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential) throws ServletException, IOException { resp.sendRedirect("/"); } @Override protected void onError( HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse) throws ServletException, IOException { String nickname = UserServiceFactory.getUserService().getCurrentUser().getNickname(); resp.getWriter().print("<h3>" nickname ", why don't you want to play with me?</h1>"); resp.setStatus(200); resp.addHeader("Content-Type", "text/html"); } @Override protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { return Utils.getRedirectUri(req); } @Override protected AuthorizationCodeFlow initializeFlow() throws IOException { return Utils.newFlow(); } }
如需更多示例,请参阅 storage-serviceaccount-appengine-sample.
服务账号
GoogleCredential 也支持服务账号。 这不同于客户端应用请求访问 最终用户的数据,可通过服务账号访问客户端应用的 自己的数据。您的客户端应用使用 从 Google API 控制台下载的私钥。
摘自 plus-serviceaccount-cmdline-sample 的示例代码:
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport(); JsonFactory jsonFactory = GsonFactory.getDefaultInstance(); ... // Build service account credential. GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json")) .createScoped(Collections.singleton(PlusScopes.PLUS_ME)); // Set up global Plus instance. plus = new Plus.Builder(httpTransport, jsonFactory, credential) .setApplicationName(APPLICATION_NAME).build(); ...
如需更多示例,请参阅 storage-serviceaccount-cmdline-sample.
冒充别人
您还可以使用服务账号流程来模拟 资源。这与上述服务账号流程非常相似 此外,还会调用 GoogleCredential.Builder.setServiceAccountUser(String)。
已安装的应用
这是对已安装的应用使用 OAuth 2.0 中所述的命令行授权代码流程。
来自 的代码段示例 plus-cmdline-sample:
public static void main(String[] args) { try { httpTransport = GoogleNetHttpTransport.newTrustedTransport(); dataStoreFactory = new FileDataStoreFactory(DATA_STORE_DIR); // authorization Credential credential = authorize(); // set up global Plus instance plus = new Plus.Builder(httpTransport, JSON_FACTORY, credential).setApplicationName( APPLICATION_NAME).build(); // ... } private static Credential authorize() throws Exception { // load client secrets GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY, new InputStreamReader(PlusSample.class.getResourceAsStream("/client_secrets.json"))); // set up authorization code flow GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder( httpTransport, JSON_FACTORY, clientSecrets, Collections.singleton(PlusScopes.PLUS_ME)).setDataStoreFactory( dataStoreFactory).build(); // authorize return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user"); }
客户端应用
要使用基于浏览器的客户端流程,请参阅 针对客户端应用使用 OAuth 2.0, 通常可以按照以下步骤进行操作:
- 使用以下网址将浏览器中的最终用户重定向到授权页面: GoogleBrowserClientRequestUrl 授权您的浏览器应用访问最终用户的受保护数据。
- 使用适用于 JavaScript 的 Google API 客户端库 处理在重定向 URI 的网址片段中找到的访问令牌 已在 Google API 控制台中注册。
Web 应用的用法示例:
public void doGet(HttpServletRequest request, HttpServletResponse response)throws IOException { String url = new GoogleBrowserClientRequestUrl("812741506391.apps.googleusercontent.com", "https://oauth2.example.com/oauthcallback", Arrays.asList( "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile")).setState("/profile").build(); response.sendRedirect(url); }
Android
要在 Android 中使用哪个库:
如果您是针对 Android 进行开发,并且包含您要使用的 Google API 在 Google Play 服务库, 请使用该库以获得最佳性能和体验。如果您通过 Google API 不属于 Google Play 服务库, 可以使用适用于 Java 的 Google API 客户端库,该库支持 Android 4.0 (Ice Cream Sandwich) (或更高版本),详见此处。Google Java 版 API 客户端库为 @Beta 版。
背景信息:
从 Eclair (SDK 2.1) 开始,用户账号需在 Android 设备上进行管理 使用账号管理器登录所有 Android 应用授权都集中在 由 SDK 管理 AccountManager。 您指定应用所需的 OAuth 2.0 范围,然后它会返回一个访问权限 令牌。
OAuth 2.0 范围是通过 authTokenType
参数指定为 oauth2:
的
以及范围。例如:
oauth2:https://www.googleapis.com/auth/tasks
此参数指定对 Google Tasks API 的读写权限。如果您需要 OAuth 2.0 范围,请使用以空格分隔的列表。
某些 API 具有同样有效的特殊 authTokenType
参数。例如:
“管理任务”是上面所示 authtokenType
示例的别名。
您还必须从 Google API 控制台。 否则,AccountManager 提供给您的令牌只会向您提供 匿名配额,通常很低。相比之下,通过指定一个 API 密钥,您会获得更高的免费配额,并且可以选择性地针对使用量设置结算信息 上方。
代码段示例来自 tasks-android-sample:
com.google.api.services.tasks.Tasks service; @Override public void onCreate(Bundle savedInstanceState) { credential = GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS)); SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null)); service = new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential) .setApplicationName("Google-TasksAndroidSample/1.0").build(); } private void chooseAccount() { startActivityForResult(credential.newChooseAccountIntent(), REQUEST_ACCOUNT_PICKER); } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); switch (requestCode) { case REQUEST_GOOGLE_PLAY_SERVICES: if (resultCode == Activity.RESULT_OK) { haveGooglePlayServices(); } else { checkGooglePlayServicesAvailable(); } break; case REQUEST_AUTHORIZATION: if (resultCode == Activity.RESULT_OK) { AsyncLoadTasks.run(this); } else { chooseAccount(); } break; case REQUEST_ACCOUNT_PICKER: if (resultCode == Activity.RESULT_OK && data != null && data.getExtras() != null) { String accountName = data.getExtras().getString(AccountManager.KEY_ACCOUNT_NAME); if (accountName != null) { credential.setSelectedAccountName(accountName); SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); SharedPreferences.Editor editor = settings.edit(); editor.putString(PREF_ACCOUNT_NAME, accountName); editor.commit(); AsyncLoadTasks.run(this); } } break; } }