new Service_(serviceName)
Creates a new OAuth2 service.
Parameters:
| Name | Type | Description |
|---|---|---|
serviceName |
string | The name of the service. |
Methods
exchangeGrant_()
Obtain an access token using the custom grant type specified. Most often
this will be "client_credentials", and a client ID and secret are set an
"Authorization: Basic ..." header will be added using those values.
fetchToken_(payload, optUrlopt) → {Object}
Fetches a new token from the OAuth server.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
payload |
Object | The token request payload. | |
optUrl |
string |
<optional> |
The URL of the token endpoint. |
Returns:
The parsed token.
- Type
- Object
getAccessToken() → {string}
Gets an access token for this service. This token can be used in HTTP
requests to the service's endpoint. This method will throw an error if the
user's access was not granted or has expired.
Returns:
An access token.
- Type
- string
getAuthorizationUrl(optAdditionalParameters) → {string}
Gets the authorization URL. The first step in getting an OAuth2 token is to
have the user visit this URL and approve the authorization request. The
user will then be redirected back to your application using callback function
name specified, so that the flow may continue.
Parameters:
| Name | Type | Description |
|---|---|---|
optAdditionalParameters |
Object | Additional parameters that should be stored in the state token and made available in the callback function. |
Returns:
The authorization URL.
- Type
- string
getIdToken() → {string}
Gets an id token for this service. This token can be used in HTTP
requests to the service's endpoint. This method will throw an error if the
user's access was not granted or has expired.
Returns:
An id token.
- Type
- string
getLastError() → {Exception}
Gets the last error that occurred this execution when trying to automatically
refresh or generate an access token.
Returns:
An error, if any.
- Type
- Exception
getRedirectUri() → {string}
Returns the redirect URI that will be used for this service. Often this URI
needs to be entered into a configuration screen of your OAuth provider.
Returns:
The redirect URI.
- Type
- string
getStorage() → {Storage_}
Gets the storage layer for this service, used to persist tokens.
Custom values associated with the service can be stored here as well.
The key
null is used to to store the token and should not
be used.
Returns:
The service's storage.
- Type
- Storage_
getToken(optSkipMemoryChecknullable) → {Object}
Gets the token from the service's property store or cache.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
optSkipMemoryCheck |
boolean |
<nullable> |
If true, bypass the local memory cache when fetching the token. |
Returns:
The token, or null if no token was found.
- Type
- Object
handleCallback(callbackRequest) → {boolean}
Completes the OAuth2 flow using the request data passed in to the callback
function.
Parameters:
| Name | Type | Description |
|---|---|---|
callbackRequest |
Object | The request data recieved from the callback function. |
Returns:
True if authorization was granted, false if it was denied.
- Type
- boolean
hasAccess() → {boolean}
Determines if the service has access (has been authorized and hasn't
expired). If offline access was granted and the previous token has expired
this method attempts to generate a new token.
Returns:
true if the user has access to the service, false
otherwise.
- Type
- boolean
refresh()
Refreshes a token that has expired. This is only possible if offline access
was requested when the token was authorized.
reset()
Resets the service, removing access and requiring the service to be
re-authorized. Also removes any additional values stored in the service's
storage.
setAdditionalClaims(additionalClaims) → (non-null) {Service_}
Sets additional JWT claims to use for Service Account authorization.
Parameters:
| Name | Type | Description |
|---|---|---|
additionalClaims |
Object.<string, string> | The additional claims, as key-value pairs. |
Returns:
This service, for chaining.
- Type
- Service_
setAuthorizationBaseUrl(authorizationBaseUrl) → (non-null) {Service_}
Sets the service's authorization base URL (required). For Google services
this URL should be
https://accounts.google.com/o/oauth2/auth.
Parameters:
| Name | Type | Description |
|---|---|---|
authorizationBaseUrl |
string | The authorization endpoint base URL. |
Returns:
This service, for chaining.
- Type
- Service_
setCache(cache) → (non-null) {Service_}
Sets the cache to use when persisting credentials (optional). Using a cache
will reduce the need to read from the property store and may increase
performance. In most cases this should be a private cache, but a public cache
may be appropriate if you want to share access across users.
Parameters:
| Name | Type | Description |
|---|---|---|
cache |
CacheService.Cache | The cache to use when persisting credentials. |
Returns:
This service, for chaining.
- Type
- Service_
setCallbackFunction(callbackFunctionName) → (non-null) {Service_}
Sets the name of the authorization callback function (required). This is the
function that will be called when the user completes the authorization flow
on the service provider's website. The callback accepts a request parameter,
which should be passed to this service's
handleCallback() method
to complete the process.
Parameters:
| Name | Type | Description |
|---|---|---|
callbackFunctionName |
string | The name of the callback function. |
Returns:
This service, for chaining.
- Type
- Service_
setClientId(clientId) → (non-null) {Service_}
Sets the client ID to use for the OAuth flow (required). You can create
client IDs in the "Credentials" section of a Google Developers Console
project. Although you can use any project with this library, it may be
convinient to use the project that was created for your script. These
projects are not visible if you visit the console directly, but you can
access it by click on the menu item "Resources > Advanced Google services" in
the Script Editor, and then click on the link "Google Developers Console" in
the resulting dialog.
Parameters:
| Name | Type | Description |
|---|---|---|
clientId |
string | The client ID to use for the OAuth flow. |
Returns:
This service, for chaining.
- Type
- Service_
setClientSecret(clientSecret) → (non-null) {Service_}
Sets the client secret to use for the OAuth flow (required). See the
documentation for
setClientId() for more information on how to
create client IDs and secrets.
Parameters:
| Name | Type | Description |
|---|---|---|
clientSecret |
string | The client secret to use for the OAuth flow. |
Returns:
This service, for chaining.
- Type
- Service_
setExpirationMinutes(expirationMinutes) → (non-null) {Service_}
Sets number of minutes that a token obtained through Service Account
authorization should be valid. Default: 60 minutes.
Parameters:
| Name | Type | Description |
|---|---|---|
expirationMinutes |
string | The expiration duration in minutes. |
Returns:
This service, for chaining.
- Type
- Service_
setGrantType(grantType) → (non-null) {Service_}
Sets the OAuth2 grant_type to use when obtaining an access token. This does
not need to be set when using either the authorization code flow (AKA
3-legged OAuth) or the service account flow. The most common usage is to set
it to "client_credentials" and then also set the token headers to include
the Authorization header required by the OAuth2 provider.
Parameters:
| Name | Type | Description |
|---|---|---|
grantType |
string | The OAuth2 grant_type value. |
Returns:
This service, for chaining.
- Type
- Service_
setIssuer(issuer) → (non-null) {Service_}
Sets the issuer (iss) value to use for Service Account authorization.
If not set the client ID will be used instead.
Parameters:
| Name | Type | Description |
|---|---|---|
issuer |
string | This issuer value |
Returns:
This service, for chaining.
- Type
- Service_
setLock(lock) → (non-null) {Service_}
Sets the lock to use when checking and refreshing credentials (optional).
Using a lock will ensure that only one execution will be able to access the
stored credentials at a time. This can prevent race conditions that arise
when two executions attempt to refresh an expired token.
Parameters:
| Name | Type | Description |
|---|---|---|
lock |
LockService.Lock | The lock to use when accessing credentials. |
Returns:
This service, for chaining.
- Type
- Service_
setParam(name, value) → (non-null) {Service_}
Sets an additional parameter to use when constructing the authorization URL
(optional). See the documentation for your service provider for information
on what parameter values they support.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string | The parameter name. |
value |
string | The parameter value. |
Returns:
This service, for chaining.
- Type
- Service_
setPrivateKey(privateKey) → (non-null) {Service_}
Sets the private key to use for Service Account authorization.
Parameters:
| Name | Type | Description |
|---|---|---|
privateKey |
string | The private key. |
Returns:
This service, for chaining.
- Type
- Service_
setPropertyStore(propertyStore) → (non-null) {Service_}
Sets the property store to use when persisting credentials (required). In
most cases this should be user properties, but document or script properties
may be appropriate if you want to share access across users.
Parameters:
| Name | Type | Description |
|---|---|---|
propertyStore |
PropertiesService.Properties | The property store to use when persisting credentials. |
Returns:
This service, for chaining.
- Type
- Service_
setRedirectUri(redirectUri) → (non-null) {Service_}
Sets the URI to redirect to when the OAuth flow has completed. By default the
library will provide this value automatically, but in some rare cases you may
need to override it.
Parameters:
| Name | Type | Description |
|---|---|---|
redirectUri |
string | The redirect URI. |
Returns:
This service, for chaining.
- Type
- Service_
setRefreshUrl(refreshUrl) → (non-null) {Service_}
Sets the service's refresh URL. Some OAuth providers require a different URL
to be used when generating access tokens from a refresh token.
Parameters:
| Name | Type | Description |
|---|---|---|
refreshUrl |
string | The refresh endpoint URL. |
Returns:
This service, for chaining.
- Type
- Service_
setScope(scope, optSeparatoropt) → (non-null) {Service_}
Sets the scope or scopes to request during the authorization flow (optional).
If the scope value is an array it will be joined using the separator before
being sent to the server, which is is a space character by default.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
scope |
string | Array.<string> | The scope or scopes to request. | |
optSeparator |
string |
<optional> |
The optional separator to use when joining multiple scopes. Default: space. |
Returns:
This service, for chaining.
- Type
- Service_
setSubject(subject) → (non-null) {Service_}
Sets the subject (sub) value to use for Service Account authorization.
Parameters:
| Name | Type | Description |
|---|---|---|
subject |
string | This subject value |
Returns:
This service, for chaining.
- Type
- Service_
setTokenFormat(tokenFormat) → (non-null) {Service_}
Sets the format of the returned token. Default: OAuth2.TOKEN_FORMAT.JSON.
Parameters:
| Name | Type | Description |
|---|---|---|
tokenFormat |
OAuth2.TOKEN_FORMAT | The format of the returned token. |
Returns:
This service, for chaining.
- Type
- Service_
setTokenHeaders(tokenHeaders) → (non-null) {Service_}
Sets the additional HTTP headers that should be sent when retrieving or
refreshing the access token.
Parameters:
| Name | Type | Description |
|---|---|---|
tokenHeaders |
Object.<string, string> | A map of header names to values. |
Returns:
This service, for chaining.
- Type
- Service_
setTokenMethod(tokenMethod) → (non-null) {Service_}
Sets the HTTP method to use when retrieving or refreshing the access token.
Default: "post".
Parameters:
| Name | Type | Description |
|---|---|---|
tokenMethod |
string | The HTTP method to use. |
Returns:
This service, for chaining.
- Type
- Service_
setTokenPayloadHandler(tokenHandler) → (non-null) {Service_}
Sets an additional function to invoke on the payload of the access token
request.
Parameters:
| Name | Type | Description |
|---|---|---|
tokenHandler |
tokenHandler | tokenHandler A function to invoke on the payload of the request for an access token. |
Returns:
This service, for chaining.
- Type
- Service_
setTokenUrl(tokenUrl) → (non-null) {Service_}
Sets the service's token URL (required). For Google services this URL should
be https://accounts.google.com/o/oauth2/token.
Parameters:
| Name | Type | Description |
|---|---|---|
tokenUrl |
string | The token endpoint URL. |
Returns:
This service, for chaining.
- Type
- Service_