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_