Skip to content

Commit 053d3e7

Browse files
author
Eric Koleda
committed
1.36.0
1 parent e590134 commit 053d3e7

File tree

7 files changed

+51
-190
lines changed

7 files changed

+51
-190
lines changed

‎dist/OAuth2.gs‎

Lines changed: 12 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -32,23 +32,6 @@ var TOKEN_FORMAT = {
3232
FORM_URL_ENCODED: 'application/x-www-form-urlencoded'
3333
};
3434

35-
/**
36-
* The supported locations for passing the state parameter.
37-
* @enum {string}
38-
*/
39-
var STATE_PARAMETER_LOCATION = {
40-
/**
41-
* Pass the state parameter in the authorization URL.
42-
* @default
43-
*/
44-
AUTHORIZATION_URL: 'authorization-url',
45-
/**
46-
* Pass the state token in the redirect URL, as a workaround for APIs that
47-
* don't support the state parameter.
48-
*/
49-
REDIRECT_URL: 'redirect-url'
50-
};
51-
5235
/**
5336
* Creates a new OAuth2 service with the name specified. It's usually best to
5437
* create and configure your service once at the start of your script, and then
@@ -692,9 +675,6 @@ Service_.prototype.refresh = function() {
692675
* @return {Storage} The service's storage.
693676
*/
694677
Service_.prototype.getStorage = function() {
695-
validate_({
696-
'Property store': this.propertyStore_
697-
});
698678
if (!this.storage_) {
699679
var prefix = 'oauth2.' + this.serviceName_;
700680
this.storage_ = new Storage_(prefix, this.propertyStore_, this.cache_);
@@ -894,14 +874,14 @@ Service_.prototype.exchangeGrant_ = function() {
894874
* related information.
895875
* @param {string} prefix The prefix to use for keys in the properties and
896876
* cache.
897-
* @param {PropertiesService.Properties} properties The properties instance to
898-
* use.
877+
* @param {PropertiesService.Properties} optProperties The optional properties
878+
* instance to use.
899879
* @param {CacheService.Cache} [optCache] The optional cache instance to use.
900880
* @constructor
901881
*/
902-
function Storage_(prefix, properties, optCache) {
882+
function Storage_(prefix, optProperties, optCache) {
903883
this.prefix_ = prefix;
904-
this.properties_ = properties;
884+
this.properties_ = optProperties;
905885
this.cache_ = optCache;
906886
this.memory_ = {};
907887
}
@@ -953,7 +933,8 @@ Storage_.prototype.getValue = function(key, optSkipMemoryCheck) {
953933
}
954934

955935
// Check properties.
956-
if (jsonValue = this.properties_.getProperty(prefixedKey)) {
936+
if (this.properties_ &&
937+
(jsonValue = this.properties_.getProperty(prefixedKey))) {
957938
if (this.cache_) {
958939
this.cache_.put(prefixedKey,
959940
jsonValue, Storage_.CACHE_EXPIRATION_TIME_SECONDS);
@@ -981,7 +962,9 @@ Storage_.prototype.getValue = function(key, optSkipMemoryCheck) {
981962
Storage_.prototype.setValue = function(key, value) {
982963
var prefixedKey = this.getPrefixedKey_(key);
983964
var jsonValue = JSON.stringify(value);
984-
this.properties_.setProperty(prefixedKey, jsonValue);
965+
if (this.properties_) {
966+
this.properties_.setProperty(prefixedKey, jsonValue);
967+
}
985968
if (this.cache_) {
986969
this.cache_.put(prefixedKey, jsonValue,
987970
Storage_.CACHE_EXPIRATION_TIME_SECONDS);
@@ -995,7 +978,9 @@ Storage_.prototype.setValue = function(key, value) {
995978
*/
996979
Storage_.prototype.removeValue = function(key) {
997980
var prefixedKey = this.getPrefixedKey_(key);
998-
this.properties_.deleteProperty(prefixedKey);
981+
if (this.properties_) {
982+
this.properties_.deleteProperty(prefixedKey);
983+
}
999984
if (this.cache_) {
1000985
this.cache_.remove(prefixedKey);
1001986
}

‎docs/Service_.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5074,13 +5074,13 @@ <h5>Returns:</h5>
50745074
</div>
50755075

50765076
<nav>
5077-
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
5077+
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
50785078
</nav>
50795079

50805080
<br class="clear">
50815081

50825082
<footer>
5083-
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
5083+
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
50845084
</footer>
50855085

50865086
<script> prettyPrint(); </script>

‎docs/Storage_.html‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ <h1 class="page-title">Class: Storage_</h1>
2828

2929
<header>
3030

31-
<h2><span class="attribs"><span class="type-signature"></span></span>Storage_<span class="signature">(prefix, properties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h2>
31+
<h2><span class="attribs"><span class="type-signature"></span></span>Storage_<span class="signature">(prefix, optProperties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h2>
3232

3333

3434
</header>
@@ -41,7 +41,7 @@ <h2><span class="attribs"><span class="type-signature"></span></span>Storage_<sp
4141

4242

4343

44-
<h4 class="name" id="Storage_"><span class="type-signature"></span>new Storage_<span class="signature">(prefix, properties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
44+
<h4 class="name" id="Storage_"><span class="type-signature"></span>new Storage_<span class="signature">(prefix, optProperties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
4545

4646

4747

@@ -120,7 +120,7 @@ <h5>Parameters:</h5>
120120

121121
<tr>
122122

123-
<td class="name"><code>properties</code></td>
123+
<td class="name"><code>optProperties</code></td>
124124

125125

126126
<td class="type">
@@ -144,8 +144,8 @@ <h5>Parameters:</h5>
144144

145145

146146

147-
<td class="description last">The properties instance to
148-
use.</td>
147+
<td class="description last">The optional properties
148+
instance to use.</td>
149149
</tr>
150150

151151

@@ -757,13 +757,13 @@ <h5>Parameters:</h5>
757757
</div>
758758

759759
<nav>
760-
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
760+
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
761761
</nav>
762762

763763
<br class="clear">
764764

765765
<footer>
766-
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
766+
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
767767
</footer>
768768

769769
<script> prettyPrint(); </script>

‎docs/global.html‎

Lines changed: 2 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -98,149 +98,6 @@ <h3 class="subsection-title">Members</h3>
9898

9999

100100

101-
<h4 class="name" id="STATE_PARAMETER_LOCATION"><span class="type-signature"></span>STATE_PARAMETER_LOCATION<span class="type-signature"> :string</span></h4>
102-
103-
104-
105-
106-
<div class="description">
107-
The supported locations for passing the state parameter.
108-
</div>
109-
110-
111-
112-
<h5>Type:</h5>
113-
<ul>
114-
<li>
115-
116-
<span class="param-type">string</span>
117-
118-
119-
</li>
120-
</ul>
121-
122-
123-
124-
125-
126-
<h5 class="subsection-title">Properties:</h5>
127-
128-
129-
130-
<table class="props">
131-
<thead>
132-
<tr>
133-
134-
<th>Name</th>
135-
136-
137-
<th>Type</th>
138-
139-
140-
141-
142-
143-
<th class="last">Description</th>
144-
</tr>
145-
</thead>
146-
147-
<tbody>
148-
149-
150-
<tr>
151-
152-
<td class="name"><code>AUTHORIZATION_URL</code></td>
153-
154-
155-
<td class="type">
156-
157-
158-
<span class="param-type">string</span>
159-
160-
161-
162-
</td>
163-
164-
165-
166-
167-
168-
<td class="description last">Pass the state parameter in the authorization URL.</td>
169-
</tr>
170-
171-
172-
173-
<tr>
174-
175-
<td class="name"><code>REDIRECT_URL</code></td>
176-
177-
178-
<td class="type">
179-
180-
181-
<span class="param-type">string</span>
182-
183-
184-
185-
</td>
186-
187-
188-
189-
190-
191-
<td class="description last">Pass the state token in the redirect URL, as a workaround for APIs that
192-
don't support the state parameter.</td>
193-
</tr>
194-
195-
196-
</tbody>
197-
</table>
198-
199-
200-
201-
202-
<dl class="details">
203-
204-
205-
206-
207-
208-
209-
210-
211-
212-
213-
214-
215-
216-
217-
218-
219-
220-
221-
222-
223-
224-
225-
226-
227-
228-
229-
230-
231-
232-
233-
234-
235-
</dl>
236-
237-
238-
239-
240-
241-
242-
243-
244101
<h4 class="name" id="TOKEN_FORMAT"><span class="type-signature"></span>TOKEN_FORMAT<span class="type-signature"> :string</span></h4>
245102

246103

@@ -1355,13 +1212,13 @@ <h5>Returns:</h5>
13551212
</div>
13561213

13571214
<nav>
1358-
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
1215+
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
13591216
</nav>
13601217

13611218
<br class="clear">
13621219

13631220
<footer>
1364-
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
1221+
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
13651222
</footer>
13661223

13671224
<script> prettyPrint(); </script>

‎docs/index.html‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -133,14 +133,14 @@ <h3>1. Create the OAuth2 service</h3><p>The OAuth2Service class contains the con
133133

134134
// Sets the login hint, which will prevent the account chooser screen
135135
// from being shown to users logged in with multiple accounts.
136-
.setParam('login_hint', Session.getActiveUser().getEmail())
136+
.setParam('login_hint', Session.getEffectiveUser().getEmail())
137137

138138
// Requests offline access.
139139
.setParam('access_type', 'offline')
140140

141-
// Forces the approval prompt every time. This is useful for testing,
142-
// but not desirable in a production application.
143-
.setParam('approval_prompt', 'force');
141+
// Consent prompt is required to ensure a refresh token is always
142+
// returned when requesting offline access.
143+
.setParam('prompt', 'consent');
144144
}</code></pre><h3>2. Direct the user to the authorization URL</h3><p>Apps Script UI's are not allowed to redirect the user's window to a new URL, so
145145
you'll need to present the authorization URL as a link for the user to click.
146146
The URL is generated by the service, using the function <code>getAuthorizationUrl()</code>.</p>
@@ -189,7 +189,26 @@ <h3>4. Get the access token</h3><p>Now that the service is authorized you can us
189189
<pre class="prettyprint source lang-js"><code>function logout() {
190190
var service = getDriveService()
191191
service.reset();
192-
}</code></pre><h2>Best practices</h2><h3>Caching</h3><p>Scripts that use the library heavily should enable caching on the service, so as
192+
}</code></pre><h2>Best practices</h2><h3>Token storage</h3><p>In almost all cases you'll want to persist the OAuth tokens after you retrieve
193+
them. This prevents having to request access from the user every time you want
194+
to call the API. To do so, make sure you set a properties store when you define
195+
your service:</p>
196+
<pre class="prettyprint source lang-js"><code>return OAuth2.createService('Foo')
197+
.setPropertyStore(PropertiesService.getUserProperties())
198+
// ...</code></pre><p>Apps Script has <a href="https://developers.google.com/apps-script/reference/properties/properties-service">property stores</a> scoped to the user, script,
199+
or document. In most cases you'll want to choose user-scoped properties, as it
200+
is most common to have each user of your script authorize access to their own
201+
account. However there are uses cases where you'd want to authorize access to
202+
a shared resource and then have all users of the script (or on the same
203+
document) share that access.</p>
204+
<p>When using a service account or 2-legged OAuth flow, where users aren't prompted
205+
for authorization, storing tokens is still beneficial as there can be rate
206+
limits on generating new tokens. However there are edge cases where you need to
207+
generate lots of different tokens in a short amount of time, and persisting
208+
those tokens to properties can exceed your <code>PropertiesService</code> quota. In those
209+
cases you can omit any form of token storage and just retrieve new ones as
210+
needed.</p>
211+
<h3>Caching</h3><p>Scripts that use the library heavily should enable caching on the service, so as
193212
to not exhaust their <code>PropertiesService</code> quotas. To enable caching, simply add
194213
a <code>CacheService</code> cache when configuring the service:</p>
195214
<pre class="prettyprint source lang-js"><code>return OAuth2.createService('Foo')
@@ -699,13 +718,13 @@ <h2>Utilities.js</h2>
699718
</div>
700719

701720
<nav>
702-
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
721+
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
703722
</nav>
704723

705724
<br class="clear">
706725

707726
<footer>
708-
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
727+
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
709728
</footer>
710729

711730
<script> prettyPrint(); </script>

‎package-lock.json‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "apps-script-oauth2",
3-
"version": "1.35.0",
3+
"version": "1.36.0",
44
"description": "OAuth2 for Apps Script is a library for Google Apps Script that provides the ability to create and authorize OAuth2 tokens as well as refresh them when they expire.",
55
"repository": {
66
"type": "git",

0 commit comments

Comments
 (0)