Skip to content

Commit

Permalink
Update documentation based on auth2 deprecation
Browse files Browse the repository at this point in the history 
Remove auth2 references and replace with links to deprecation notice
Remove cors information
Update/remove samples
  • Loading branch information
@dvanderb
dvanderb committed Dec 21, 2022
1 parent 63ed219 commit 59e86b2
Show file tree
Hide file tree
Showing 9 changed files with 5 additions and 369 deletions.
3 changes: 0 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,6 @@ developers. It offers simple, flexible access to many Google APIs.

The JavaScript client library [supports these Google APIs](https://developers.google.com/apis-explorer/#p/).

The library supports [OAuth 2 authentication](docs/auth.md).

If you use TypeScript, you can install [`@types/gapi`](https://www.npmjs.com/package/@types/gapi) for autocompletion.

# Documentation
Expand All @@ -24,7 +22,6 @@ If you use TypeScript, you can install [`@types/gapi`](https://www.npmjs.com/pac

- [Auth](docs/auth.md)
- [Batch](docs/batch.md)
- [CORS](docs/cors.md)
- [Discovery Documents](docs/discovery.md)
- [FAQ](docs/faq.md)
- [Promises](docs/promises.md)
Expand Down
1 change: 0 additions & 1 deletion docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ access to many Google APIs.
- [Getting Started](start.md)
- [Auth](auth.md)
- [Batch](batch.md)
- [CORS](cors.md)
- [Discovery Documents](discovery.md)
- [FAQ](faq.md)
- [Promises](promises.md)
Expand Down
122 changes: 1 addition & 121 deletions docs/auth.md
View file
Original file line number Diff line number Diff line change
@@ -1,123 +1,3 @@
# Authentication

[](#top_of_page)Overview
------------------------

To access a user's private data, your application must work with Google's policies for authentication and authorization.

Google defines two levels of API access:

<table>
<tr>
<th>
Level
</th>
<th>
Description
</th>
<th>
Requires:
</th>
</tr>
<tr>
<td>
Simple
</td>
<td>
API calls do not access any private user data
</td>
<td>
API key
</td>
</tr>
<tr>
<td>
Authorized
</td>
<td>
API calls can read and write private user data, or the
application's own data
</td>
<td>
API key plus OAuth 2.0 credentials (different for
different application types)
</td>
</tr>
</table>

[](#top_of_page)Getting access keys for your application
--------------------------------------------------------

To get access keys, go to the [Google Developers Console](https://console.developers.google.com) and specify your application's name and the Google APIs it will access. For simple access, Google generates an API key that uniquely identifies your application in its transactions with the Google Auth server.

For authorized access, you must also tell Google your website's protocol and domain. In return, Google generates a client ID. Your application submits this to the Google Auth server to get an OAuth 2.0 access token.

For detailed instructions for this process, see the [Getting started](start.md) page.

See below for details and examples of how to use these credentials in your application.

[](#top_of_page)Simple access using the API key
-----------------------------------------------

The API key identifies your application for requests that don't require authorization.

Whether or not your application requires authorized access, your code should call `gapi.client.init` with the `apiKey` parameter.

```js
gapi.client.init({ 'apiKey': 'YOUR_API_KEY', ...
}).then(...)
```

For a complete example of simple API access, follow [this link](samples.md#LoadinganAPIandMakingaRequest).

[](#top_of_page)Authorized access
---------------------------------

To access a user's personal information, your application must work with Google's OAuth 2.0 mechanism.

### OAuth 2.0 basics

You may want to start with this overview of [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/accounts/docs/OAuth2).

Behind the scenes, the OAuth 2.0 mechanism performs a complex operation to authenticate the user, the application, and the Google Auth server. The components of the JavaScript client library manage this process for you, so that all your code has to do is pass in the following objects:

* The client ID you received when you registered your application
* The scope object that specifies which data your application will use

### About scope

The scope object defines the level of access to a particular API that your application will use. For more information about how scopes work, refer to [this OAuth 2.0 documentation](https://developers.google.com/accounts/docs/OAuth2.html). The scope is a **space delimited string**. The following example represents read-only access to a user's Google Drive:

https://www.googleapis.com/auth/drive.readonly

### OAuth 2.0 authorization flow

The JavaScript client library uses the [OAuth 2.0 client-side flow](https://developers.google.com/accounts/docs/OAuth2UserAgent) for making requests that require authorization. If you would like to see what this looks like in action, check out [Google's OAuth 2.0 Playground](https://developers.google.com/oauthplayground/).

OAuth 2.0 authorization in the JavaScript client library proceeds as follows:

1. The user clicks a "login" link.
2. The browser shows a popup that allows the user to authenticate and authorize the web application.
3. After successful authorization, the browser redirects the user back to the calling application (your application).
4. The callback saves the authorization token and closes the popup.

After this, the user is signed in to your application, and the application is authorized to access the user's personal data. The user's sign-in state is persistent across sessions, so the next time the user opens your application, the user is automatically signed in.

[](#top_of_page)Auth example
----------------------------

See the [auth example](samples.md#authorizing-and-making-authorized-requests) on the Samples page.

[](#top_of_page)Making a request with CORS
------------------------------------------

To make an authenticated [CORS](http://www.w3.org/TR/cors/) request, you can add the OAuth 2.0 access token to the request header or add it as a URL parameter. For details, read the [CORS documentation](cors.md).

[](#top_of_page)The standalone auth client
------------------------------------------

Your application can also use a subset of the full JavaScript client library that performs authentication and nothing else. It includes only the `gapi.auth` methods.

Use the standalone auth client in web applications that will run in environments with full CORS support, such as Chrome extensions and mobile browsers. If your application may run on browsers which do not support CORS, or if you want to use other features of the JavaScript library, use the standard JavaScript client.

For information about how to load and use the auth client, see the [CORS documentation](cors.md).
gapi.auth2 has been deprecated and replaced with Google Identity Services. Please see https://developers.googleblog.com/2021/08/gsi-jsweb-deprecation.html for more information. If you have questions related to authentication/authorization please look at the associated documentation or post questions on Stack Overflow with the google-oauth tag.
95 changes: 0 additions & 95 deletions docs/cors.md
View file

This file was deleted.

27 changes: 0 additions & 27 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,6 @@

The JavaScript client library does not support local pages and the `file://` protocol. The application must be hosted on a server (can be localhost).

### Does the JavaScript client library set authentication cookies?

The JavaScript client library does not write any auth cookies. `gapi.auth.getToken` and `gapi.auth.setToken` provide access to the auth token.

### How do I refresh the auth token, and how often should I do it?

Refresh the token by calling `gapi.auth.authorize` with the client ID, the scope and `immediate:true` as parameters.

Currently, the auth token expires after one hour. A common practice is to refresh the auth token after 45 minutes. If you refresh the auth token too often (every five minutes, for example) you will run into the refresh rate limit. (The rate limit is per-user, so the number of user connections is not an issue.)

The auth token's `expires_in` field will tell you the token's time to expiration.

The [authSample.html file](https://github.com/google/google-api-javascript-client/blob/master/samples/authSample.html) contains one example of code that handles signin and signout but not token refreshes.

### Is it possible to use the JavaScript client library in an installed application?

At this time, the JavaScript client library supports web applications only. For mobile devices you can use one of our other client libraries like the one for [Objective-C](http://code.google.com/p/google-api-objectivec-client/)

### How can I use the JavaScript client library to log the user out of my application?

The JavaScript client library does not directly support logging the user out of the application. Typically, developers include a logout link to https://accounts.google.com/logout.

Since logging out of the application also logs the user out of the Google account, it is not recommended to log the user out unless the user requests this explicitly.

For a workaround that allows your application to log the user out programatically, see [this topic](https://groups.google.com/forum/?fromgroups=#!topic/google-api-javascript-client/PCs8xXV4wxk) in the JavaScript client library discussion group.


### Is it possible to use the JavaScript client library in a Chrome Extension?

Chrome Extensions using Manifest v3 do not allow [remotely hosted code](https://developer.chrome.com/docs/extensions/mv3/intro/mv3-overview/#remotely-hosted-code), so the Javascript client library cannot be used in this case.
12 changes: 2 additions & 10 deletions docs/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
</td>
<td>
A colon (<code>:</code>) separated list of gapi libraries. Ex:
<code>"client:auth2"</code>.
<code>"client:iframes"</code>.
</td>
</tr>
<tr>
Expand Down Expand Up @@ -148,12 +148,6 @@ alert('gapi.client could not load in a timely manner!');
<p>
Initializes the JavaScript client with API key, OAuth client ID, scope, and
<a href="/docs/discovery.md">API discovery document(s)</a>.
If OAuth client ID and scope are provided, this function will load the
<code>gapi.auth2</code> module to perform OAuth. The <code>gapi.client.init</code> function
can be run multiple times, such as to set up more APIs, to change API key, or initialize
OAuth lazily. Note that the <code>scope</code> and <code>clientId</code> parameters cannot
be provided multiple times, since the <code>gapi.auth2</code> module can only be initialized
once.
</p>
<p>
<b>Arguments:</b>
Expand Down Expand Up @@ -458,9 +452,7 @@ alert('gapi.client could not load in a timely manner!');
<code>gapi.client.setToken(<var class="apiparam">tokenObject</var>)</code>
</h3>
<p>
Sets the authentication token to use in requests. This should be used if the token was
obtained without using the <code>gapi.auth2</code> authentication library (for instance,
when using Firebase to authenticate users).
Sets the authentication token to use in requests.
</p>
<p>
<b>Arguments:</b>
Expand Down
50 changes: 1 addition & 49 deletions docs/samples.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Samples

This page provides three detailed examples which demonstrate the library's functionality. Browse the [project source](https://github.com/google/google-api-javascript-client/tree/master/samples) for additional samples.
This page provides three detailed examples which demonstrate the library's functionality. Additional samples(including authenticated/authorized requests) can be found in API specific documentation such as the [Google Drive API Quick Start](https://developers.google.com/drive/api/quickstart/js).

Loading an API and Making a Request
-----------------------------------
Expand Down Expand Up @@ -41,51 +41,3 @@ This snippet shows how to load an API and make a request. In this case, the requ
</body>
</html>
```

## Authorizing and Making Authorized Requests

The following sample demonstrates how to get "authorized" access to a Google API using OAuth 2.0. See the full sample at [authSample.html](https://github.com/google/google-api-javascript-client/blob/master/samples/authSample.html).

It's called "authorized" access because the user must give the application direct authorization to use personal data. Simple web-based applications using JavaScript usually get this authorization the way this example does: by displaying button for the user to click. This action triggers a call to a Google auth server, which pops up a standard authorization dialog. For details, see the [Authentication page](auth.md).

**Note:** The full sample uses `gapi.load('client:auth2', ...)` to load both the `client` module (for dealing with API requests) and the `auth2` module (for dealing with OAuth 2.0) upfront. The `gapi.client.init` fuction lazily loads `auth2` if it is needed. If you are sure your app needs auth, loading the two modules `'client:auth2'` together before you call `gapi.client.init` will save one script load request.

To make `gapi.client.init` set up OAuth correctly, you would have to assign the `clientID` variable the client ID generated when you registered your application (for instructions see [Integrating Google Sign-In into your web app](https://developers.google.com/identity/sign-in/web/sign-in)). The other parameter is `scope`, which in this case is just the scope for user profile permission.

When the user clicks **Authorize**, the `gapi.auth2.getAuthInstance().signIn()` function is called, which shows user a popup window to let user authorize. Note that the `gapi.auth2.getAuthInstance().signIn()` can be only called from a user interaction context for most browsers (i.e. do not call it when your app starts, but call it in a button click handler).

**Note:** When you authorize your application using Oauth 2.0, you do not also need to set the API key as in the first example. However, it is a good practice to do so, in case your code ever expands to handle unauthorized requests.

## Loading the Library Asychronously

The following code snippet shows how to load the library without blocking UI loading. (The `onreadystatechange` is used to support old versions of IE.)

```html
<html>
<head>
<script>
function start() {
gapi.client.init({
'apiKey': '...',
'discoveryDocs': [...],
...
}).then(...)
};
function loadClient() {
gapi.load('client', start);
}
</script>
<script async defer src="https://apis.google.com/js/api.js"
onload="this.onload=function(){};loadClient()"
onreadystatechange="if (this.readyState === 'complete') this.onload()"></script>
</head>
<body>
<div id="body-to-be-shown-before-gapi-load"></div>
</body>
</html>
```

## Putting it all together

The file [authSample.html](https://github.com/google/google-api-javascript-client/blob/master/samples/authSample.html) expands on the concepts on this page and provides a more complete example of making an authenticated call to the Google People API.

1 comment on commit 59e86b2

@ytrezq
Copy link

@ytrezq ytrezq commented on 59e86b2 Apr 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dvanderb does it means cors is no longer supported?

Please sign in to comment.