Community connectors support the following authentication methods:
- OAuth 2.0
- Path/Username/Password
- Path/Key
- Username/Password
- Username/Token
- Key
- None
Depending on which method you are using, you must provide additional functions in your connector.
The following table indicates which functions you must define depending on the authentication type of your connector.
OAUTH2 | PATH_USER_PASS PATH_KEY USER_PASS USER_TOKEN KEY |
NONE | |
---|---|---|---|
required | required | required | |
required | required | ||
required | required | ||
required | |||
required | |||
required |
getAuthType()
This function should return the authentication type for the connector.
OAUTH2
PATH_USER_PASS
/**
*
Returns
the
Auth
Type
of
this
connector
.
*
@
return
{
object
}
The
Auth
type
.
*/
function
getAuthType
()
{
var
cc
=
DataStudioApp
.
createCommunityConnector
();
return
cc
.
newAuthTypeResponse
()
.
setAuthType
(
cc
.
AuthType
.
PATH_USER_PASS
)
.
setHelpUrl
(
'https://www.example.org/connector-auth-help'
)
.
build
();
}
PATH_KEY
/**
*
Returns
the
Auth
Type
of
this
connector
.
*
@
return
{
object
}
The
Auth
type
.
*/
function
getAuthType
()
{
var
cc
=
DataStudioApp
.
createCommunityConnector
();
return
cc
.
newAuthTypeResponse
()
.
setAuthType
(
cc
.
AuthType
.
PATH_KEY
)
.
setHelpUrl
(
'https://www.example.org/connector-auth-help'
)
.
build
();
}
USER_PASS
USER_TOKEN
KEY
NONE
resetAuth()
This function will clear any credentials stored for the user for the third-party service.
OAUTH2
PATH_USER_PASS
/**
*
Resets
the
auth
service
.
*/
function
resetAuth
()
{
var
userProperties
=
PropertiesService
.
getUserProperties
();
userProperties
.
deleteProperty
(
'dscc.path'
);
userProperties
.
deleteProperty
(
'dscc.username'
);
userProperties
.
deleteProperty
(
'dscc.password'
);
}
PATH_KEY
/**
*
Resets
the
auth
service
.
*/
function
resetAuth
()
{
var
userProperties
=
PropertiesService
.
getUserProperties
();
userProperties
.
deleteProperty
(
'dscc.path'
);
userProperties
.
deleteProperty
(
'dscc.key'
);
}
USER_PASS
USER_TOKEN
KEY
isAuthValid()
This function is called to determine if the authentication for the third-party
service is valid. If authentication is valid then it is expected that calls to getData()
and getSchema()
will not fail due to
unauthorized access. If the auth is not valid then the user may receive a
notification to start the authorization flow.
OAUTH2
PATH_USER_PASS
/**
*
Returns
true
if
the
auth
service
has
access
.
*
@
return
{
boolean
}
True
if
the
auth
service
has
access
.
*/
function
isAuthValid
()
{
var
userProperties
=
PropertiesService
.
getUserProperties
();
var
path
=
userProperties
.
getProperty
(
'dscc.path'
);
var
userName
=
userProperties
.
getProperty
(
'dscc.username'
);
var
password
=
userProperties
.
getProperty
(
'dscc.password'
);
//
This
assumes
you
have
a
validateCredentials
function
that
//
can
validate
if
the
path
,
userName
and
password
are
correct
.
return
validateCredentials
(
path
,
userName
,
password
);
}
PATH_KEY
/**
*
Returns
true
if
the
auth
service
has
access
.
*
@
return
{
boolean
}
True
if
the
auth
service
has
access
.
*/
function
isAuthValid
()
{
var
userProperties
=
PropertiesService
.
getUserProperties
();
var
path
=
userProperties
.
getProperty
(
'dscc.path'
);
var
key
=
userProperties
.
getProperty
(
'dscc.key'
);
//
This
assumes
you
have
a
validateCredentials
function
that
//
can
validate
if
the
path
and
key
are
correct
.
return
validateCredentials
(
path
,
key
);
}
USER_PASS
USER_TOKEN
KEY
OAUTH2
Add and setup OAuth2 for Apps Script Library
Follow the setup instructions for the OAuth2 for Apps Script library to add it to your connector project. Then follow the first step in the usage guide to create an OAuth2 service in your connector project. Your OAuth2 service can have any valid function name but make sure to use the same name while referring to the OAuth2 service in your code.
For example, an OAuth2 service named exampleService
:
authCallback()
This function is called to complete the OAuth 2.0 flow. The callback response from the third-party auth service is provided as an argument and should be handled by this function.
Example of handling the OAuth 2.0 callback using the OAuth2 for Apps Script library:
get3PAuthorizationUrls()
This function is called to get the URL that is required to initiate the auth
flow for the third-party service. If isAuthValid
returns false
then the URL
returned will be displayed to the user as a button or link so that they can
authorize access to the third-party service. See the reference for get3PAuthorizationUrls()
.
Example of returning the authorization Url using the OAuth2 for Apps Script library:
USER_PASS
, USER_TOKEN
, KEY
, PATH_USER_PASS
, and PATH_KEY
The following is only needed for the USER_PASS
, USER_TOKEN
, KEY
, PATH_USER_PASS
, and PATH_KEY
authentication flows.
setCredentials()
setCredentials
is called after the user enters either their credential
information on the community connector configuration page. You should use the Properties Service
to save the credentials on a per-user
basis using UserProperties
.
PATH_USER_PASS
/**
* Sets the credentials.
* @param {Request} request The set credentials request.
* @return {object} An object with an errorCode.
*/
function
set
Credentials
(
request
)
{
var
creds
=
request
.
pathUserPass
;
var
path
=
creds
.
path
;
var
username
=
creds
.
username
;
var
password
=
creds
.
password
;
//
Optional
//
Check
if
the
provided
path
,
username
and
password
are
valid
through
//
a
call
to
your
service
.
You
would
have
to
have
a
`checkForValidCreds`
//
function
defined
for
this
to
work
.
var
validCreds
=
checkForValidCreds
(
path
,
username
,
password
);
if
(
!
validCreds
)
{
return
{
errorCode
:
'INVALID_CREDENTIALS'
}
;
}
var
userProperties
=
PropertiesService
.
getUserProperties
();
userProperties
.
set
Property
(
'dscc.path'
,
path
);
userProperties
.
set
Property
(
'dscc.username'
,
username
);
userProperties
.
set
Property
(
'dscc.password'
,
password
);
return
{
errorCode
:
'NONE'
}
;
}
PATH_KEY
/**
* Sets the credentials.
* @param {Request} request The set credentials request.
* @return {object} An object with an errorCode.
*/
function
set
Credentials
(
request
)
{
var
creds
=
request
.
pathKey
;
var
path
=
creds
.
path
;
var
key
=
creds
.
key
;
//
Optional
//
Check
if
the
provided
path
and
key
are
valid
through
//
a
call
to
your
service
.
You
would
have
to
have
a
`checkForValidCreds`
//
function
defined
for
this
to
work
.
var
validCreds
=
checkForValidCreds
(
path
,
key
);
if
(
!
validCreds
)
{
return
{
errorCode
:
'INVALID_CREDENTIALS'
}
;
}
var
userProperties
=
PropertiesService
.
getUserProperties
();
userProperties
.
set
Property
(
'dscc.path'
,
path
);
userProperties
.
set
Property
(
'dscc.key'
,
key
);
return
{
errorCode
:
'NONE'
}
;
}