If you want to read or modify any data on a Google user account (like spreadsheets, files on drive, youtube videos etc.) with your actors, you have to authorize yourself and allow Apify to access and modify the data on your behalf. For this process Google uses OAuth 2, a web standard for granting rights to 3rd party applications (like Apify actors) to act on user's behalf.
The big advantage of using OAuth is that you don't need to share your credentials or any kind of token with Apify and you can always instantly revoke the rights you gave to Apify at any time. The only requirement for you is to login and allow Apify on the first usage of specific service (like spreadsheets) and specific Google account. Let's explain how do we implement it with Apify actors.
Using OAuth in premade Apify actors
When using public actors like Google Sheets Import & Export you won't need to implement the authorization function or deal with the code in any way. You only set a proper input for the actor you want to use, run it and follow the instructions from the log.
Lets show the example with the Google Sheets Import & Export actor. You can read a short tutorial how to run it in our blog.
First of all, we need to setup a valid input for the actor. Then we just press run.
Then if we run the actor for the first time, we get prompted in the log to open an authorization URL and another Apify URL where we will paste the result of the authorization one.
Since we wanted to make everything secure for you, every proper Google actor requires your authentication and authorization. Basically, you need to prove to Google that you are who you are by logging in and allowing Apify to work with the specified service on your account.
This is the only time you need to run it directly. Once you authorize it, future uses will be authorized automatically and you can use the actor programmatically. So just press “Run” and watch the log.
The log will prompt you to open a live view tab. Open it and press Authorize. If you are running it locally, open localhost:3000.
It will open a new tab in your browser where you need to log in to Google with the account where your spreadsheet is saved. Allow Apify to access your spreadsheet and you will get to a page displaying a long token.
Copy it and paste it to the input field in live view tab and press “submit”.
And that is all you need to do! Now Apify will exchange the code with Google for a token and that token is saved into your key-value store (by default this store is called 'google-oauth-tokens' but you can change the name which is useful if you want to use multiple Google accounts). If you will use other service/scope, it will require another authorization and will save another file with tokens. But for each service you need to authorize only once (unless you didn't use it for a six months).
At any time, you can disallow Apify in your Google account and/or delete the tokens file in your key-value store.
If you don't plan to write your own actors using Google authorization, you don't need to read any further and you can just start using our public actors or write to our support what would you like to see implemented.
Creating your own actor with Google OAuth
It may happen that there is no public actor for a service you want to use or you want to simply build your own version. Even in that case, you still don't need to implement everything from scratch and can use the exact same workflow as above.
Let's look how we implement in the google-spreadsheet actor.
First we need to import the npm pachage. It is not a part of the 'apify' package but depends on it (has it as a peer dependency) so you need to have 'apify' installed too.
Locally you do:
npm install apify-google-auth
Then in the code you import the authorization function:
const Apify = require('apify');
const {apifyGoogleAuth} = require('apify-google-auth');This function takes an option object as parameter that has a default 'scope' parameter and few other optional. After going through the process explained above it will return with a promise of a authorization client that you can pass to any Google service API client.
The simplest usage for spreadsheets scope is:
Apify.main(async()=>{
const auth = await apifyGoogleAuth({scope: 'spreadsheets'});
const sheets = google.sheets({version: 'v4', auth});
})Now you have the authorized sheets client and you can use it to perform any kind of API calls within the spreadsheets scopes. Here is a list of scopes Google defines. Currently Apify supports only the main ones so if you find your scope not enables, just contact Apify support and we will enable it for you.
You can also specify a 'tokensStore' parameter so that the function will save the tokens exactly where you want them. This is mainly useful when you want to use multiple Google accounts from the same Apify account.
const auth = await apifyGoogleAuth({
scope: 'drive',
tokensStore: 'my-second-email-google-auth'
});Automatic mode
Note: You shouldn't use this mode unless you exactly know why you need to as it has serious disadvantages over the default mode.
What we now explained was a default usage where you need to interact with the actor for the first time you use it. But there is also a second mode how to run 'apifyGoogleAuth' function - in an automatic authorization mode. The main difference is that where in the default mode the user itself authorizes and allows Apify use the account on his behalf, here it is done by an automatic Puppeteer script.
If you want to use this mode, you have to pass in an object with your Google credentials.
const googleCredentials = {
email: lukas@apify.com,
password: 123456789,
secondEmail: lukas2@apify.com // this is optional
}Instead of passing them as input, you can also add the credentials as environment variables which is useful if you want them to be secure (invisible).
Optionally you can also pass in a 'puppeteerProxy' to define how will Puppeteer connect to your Google account. By default it uses a static US proxy so it always connects just from this IP but you can also set it to any proxy URL or as 'local'. Valid auth function can look like this:
const auth = await apifyGoogleAuth({
scope: 'youtube',
googleCredentials: googleCredentials,
puppeteerProxy: 'local'
});In this case Puppeteer will try to authorize for the Youtube scope with the IP address of its own server. This doesn't make much sense at Apify platform because the IP can be any in the AWS range but locally it will connect directly from your computer.
The advantage of this mode is of course that you don't need to do anything else than add your credentials to the input or env variables and run the actor. This works nicely locally (if puppeteerProxy is set to 'local') where you usually connect to your Google account but if you run it on Apify platform or from foreign computer, Google will start complaining that you want to connect from unknown computer and/or IP address. It then requires your consent that it was really you who connected. Then it is important to let the default value of 'puppeteerProxy' so it will always connect from the same IP. Using this mode with two-factor login then doesn't make any sense at all.
So unless you have a really strong need to use automatic mode, stick to the default 'user' mode as it takes just about few seconds to authorize and set everything up.