G4G GSuite Personal Registration

This process will allow you to set up a private application in your personal G Suite environment. Setting up a private/local environment for your G Suite uses and applications will allow you to bypass most of Google's ever increasingly strict security rules, mainly aimed at apps spanning more than one G Suite environment or normal "gmail.com" users.

This process will be documented without using a web interface callback. It will allow you to retrieve a security code which in turn will be exchanged for a token for a specific user and project. Once that is done, using the G4GBASE product you can automatically renew the OAuth 2.0 tokens within your applications.

If setting up a web callback is something you wish to do, please contact us and we can put something together for you if we don't already have such an application.

Set Up The Application

Step one is to set up the application in your GSuite Environment. This example will be done using the GMail Application APIs, but this can be substituted for any API available from Google.

Download and Install GreenTools for G Suite (G4G) v12.00 or higher

Visit https://www.bvstools.com/g4g.html to download the latest version of G4G. If you haven't licensed it yet, be sure to use the Quick Key feature to request a temporary key for G4G. This will automatically email you a temporary license key for the G4G base product, the G4G addons as well a GETURI.

Visit your GSuite API and Service Dashboard

Open a browser and visit https://console.developers.google.com. This will allow you to sign into your G Suite account.

Once you sign into your G Suite API and Service Dashboard you will see a drop down box at the top that says "Select a project".

Select the drop down arrow and select the NEW PROJECT option at the top right.

You will now see a screen that will allow you to create projects. You may have a quota, or you may not.

We will now name our project and select the CREATE button. In this case we named our project G4G - GMail as it will be specific to using GMail APIs.

Enable APIs Used for the Project

Now that our project is created, we need to enable the APIs we will be using for this project.

Click on the ENABLE APIS AND SERVICES link at the top of the new screen, making sure that the project we are working with is the one we just created.

You now will be at the Welcome screen for the API library. In the search box, type "gmail" and you should see the GMail APIs listed. Select this option by clicking on it.

Click on the ENABLE button. If this API is already enabled for your account, you can skip this part.

The GMail API will now be enabled for your project in your GSuite Account.

Create Application Credentials

We now need to create our API keys, secrets, etc. On the left menu, click the Credentials link:

At the right, select the CONFIGURE CONSENT SCREEN option.

We will now set up our application credentials.

• Under Application Type select Internal

• Under Application Name give your application a name. I called mine G4G - GMail Addon

• Under Application Logo you can choose to upload a logo or not.

• The Support Email should already contain the email address for support. If it is incorrect use the dropdown box to select the proper address.

• Under the Scopes for Google APIs select the Add Scope button. Only scopes available for the APIs you have enabled for this project will be available. You can choose the scopes your project requires, or select the top level scope (in this case https://mail.google.com) to give your applications all the scopes. Once your scopes have been selected, click the Add button at the bottom of the window.

• Click the Save button at the bottom of the Credentials screen.

Create the Client ID and Client ID

You will now be presented with an option to create credentials. Select the OAuth Client ID option from the drop down box.

On the Create OAuth client ID screen, select and enter the following values:

• For Application Type select Web application

• For Name you can leave this as the default, or give it any name you want.

• Under Restrictions in the Authorized redirect URIs enter http://localhost and press Enter so it is added to the list of authorized redirect URIs.

• Click the Create button.

You will now be presented with your Client ID and Client Secret. Save these values somewhere for later. You can always go back and get them again if you need.

Create Your API Key

Select the Create Credentials drop down again, but this time select API Key.

Your API key is now created. Be sure to save this value as well. You can always go back to get the value from the Credentials screen as well.

Set Up the Application in the G4GSVCPF File in On Your IBM i

You will now want to set up your application in the G4G database. Using your favorite file update tool (UPDDTA, etc) add a new record to the G4GSVCPF file. The following fields should contain the following values:

• GGSSERVICE - This will be the service name. For this example, I called my *GMAILMAPLESTONE so I know it's for the GMail APIs and my MaplestoneMN.com domain that is set up in G Suite.

• GGSSCOPE - This is the scope of your project. This will be the same value we entered when setting up the application (https://mail.google.com/). If for some reason you needed to set up multiple scopes, you can list them all here separated by %20.

• GGSAPPID - This will be the application's Client ID (or application ID).

• GGSAPIKEY - This will be the application's API Key.

• GGSCSECRET - This will be the Client Secret.

• GGSAUTHURL - Leave this blank.

• GGSTKNURL - This will be the URL used to request a token from Google. The value to use (which could change in the future) is https://accounts.google.com:443/o/oauth2/token. If you choose, you can leave off the :443 portion of the URL. This is only hear in case for some reason you need to use a proxy for your HTTP requests.

• GGSCBURL - This is the callback URL. It needs to be the same callback URL (URI) that we set up for the application. In our case it was http://localhost.

Create a Link to Generate an OAuth Code from Google

You will now want to create a link to retrieve your OAuth Code. The link will be as follows:

https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=<your client id>&redirect_uri=http%3A%2F%2Flocalhost&access_type=offline&approval_prompt=force&scope=https://mail.google.com

Be sure to replace <your client id> with the client ID for your application. If for some reason you chose a different scope, or multiple scopes for your application, replace those after "scope=" in the URL. Again, use %20 to separate multiple scopes, if needed.

Once you have this link created, paste it into a browser. You should be presented with an option to sign on with an account. Sign on with the account from your organisation that you wish to set up.

You will then be presented with a screen that asks to grant permission for your application for your account. Click the Allow button.

You will now be redirected to a page that will appear to be an error. While it is and error (unless for some reason you have localhost set up on your PC in the hosts file to point to a web server), the OAuth code we need is in the URI at the top of the screen.

Copy and paste this code value to a text file. If you need to copy the entire URI to see the entire code, you can do that as well. The code will be following the "code=" text and ends before the next "&" as shown highlighted and circled in this screen shot:

The entire URI here is:

• http://localhost/?code=4/jwEcWFE3TXZ0vT6rObWw0-JkK7YfSYE53Kalzn9Es8p4EGTyd4HEt3-y5Pv6zRLIaadNI4zVCW0e7LM8CgyuIUk&scope=https://mail.google.com/

All we want is the data after "code=" and before the next "&". So in this case, the code we want is 4/jwEcWFE3TXZ0vT6rObWw0-JkK7YfSYE53Kalzn9Es8p4EGTyd4HEt3-y5Pv6zRLIaadNI4zVCW0e7LM8CgyuIUk.

Use the G4GTOKEN Command To Exchange the Code for a Token

We will now use this code to register the service for the user using the G4GTOKEN command. The code will be exchanged with Google for a token and refresh token. Once this is complete, all of the token renewal is done internally by the G4G application functions.

Retrieve Token (G4GTOKEN)

Type choices, press Enter.

Google ID . . . . . . . . . . . > bvstone@maplestonmn.com

Service . . . . . . . . . . . . > *GMAILMAPLESTONE

Google Authorization Code . . . > '4/jwEcWFE3TXZ0vT6rObWw0-JkK7YfSYE53Kalzn9Es8p4EGTyd4HEt3-y5Pv6zRLIaadNI4zVCW0e7LM8CgyuIUk'

For the Google ID, enter the ID that you used previously when granting permissions to your application.

For Service, enter the service name you created previously in the G4GSVCPF file.

For the Google Authorization Code, copy and paste the code retrieved from the URL in the previous step.

If the user is already set up, this will update the user with a new token and refresh token. This is useful in cases where you are having issues refreshing the user's token, changed scopes for your application, or changed other settings for the application.

If the user is not set up, this will set them up with their initial token and refresh token.

If for any reason there is an error returned, you may need to visit the page with the code, select the back button and re-confirm your choice to grant permissions. A new code will be generated. The code is only active for a little while, so these last steps should all be done in sequence in a short period of time.

Set Up Your Applications To Retrieve/Refresh the OAuth 2.0 Tokens

You can now call the Google APIs that you enabled for the user that was set up. Before the call to each Google API, you will want to call the g4g_refreshToken() function which will either return the current valid token, or if the token is expired (or soon to be), the G4G application will automatically refresh to the token with Google and return the new token to your application.

Example:

id = 'bvstone@maplestonemn.com';

service = '*GMAILMAPLESTONE';

token = ' ';

errMsg = ' ';

rc = g4g_refreshToken(id:service:token:errMsg);

if (rc < 0);

//error!

else;

// call your Google API here, using the token returned

endif;

Sample Application

Following is a sample application that retrieves labels from a GMail Account.

**FREE

ctl-opt DFTACTGRP(*NO) ACTGRP('G4G') BNDDIR('G4G');

// Imports

/COPY QCOPYSRC,P.G4G

/COPY QCOPYSRC,GETURICOPY

//Prototypes

dcl-pr GetUriRG extpgm('GETURIRG');

PR_In like(GetUri_In);

PR_Out like(GetUri_Out);

PR_Head like(GetUri_Head);

PR_Data like(GetUri_Data);

PR_MsgCd like(GetUri_MsgCd);

PR_Msg like(GetUri_Msg);

end-pr;

// Work Variables

dcl-s id char(256) INZ('bvstone@maplestonemn.com');

dcl-s service char(256) INZ('*GMAILMAPLESTONE');

dcl-s token char(256);

dcl-s errMsg char(256);

dcl-s jsonFile char(256);

dcl-s rc int(10);

jsonFile = '/tmp/gmailtest_output.json';

rc = g4g_refreshToken(id:service:token:errMsg);

if (rc < 0) or (token = '');

//error!

endif;

Clear GetUri_In;

GI_URI = 'https://www.googleapis.com:443' +

'/gmail/v1/users/me/labels';

GI_Data = 'key=' + %trimr(g4g_getAPIKey(service));

GI_Port = 443;

GI_ReqMeth = 'GET';

GI_NbrHdrs = 1;

GI_UsrHdr(1) = 'Authorization';

GI_UsrHdrDta(1) = 'Bearer ' + %trim(token);

GI_SSL = '*YES';

GI_SprHead = '*YES';

GI_HTTPVer = '1.1';

GI_Debug = '*YES';

GI_DebugFile = '/tmp/gmailtest_debug.txt';

GI_OutType = '*STMF';

GI_STMF = jsonFile;

callp(e) GetUriRG(GetUri_In:GetUri_Out:GetUri_Head:GetUri_Data:

GetUri_MsgCd:GetUri_Msg);

if (%error);

// process error

endif;

*INLR = *ON;

return;

Once this programs runs you should have a file in the IFS named /tmp/gmailtest_output.json (plus possibly other files especially if you have debug turned on with GETURI).

The file should be a JSON file containing a list of labels from the specified GMail account and will look like the following:

{

"labels": [

{

"id": "CATEGORY_PERSONAL",

"name": "CATEGORY_PERSONAL",

"type": "system"

},

{

"id": "CATEGORY_SOCIAL",

"name": "CATEGORY_SOCIAL",

"type": "system"

},

{

"id": "IMPORTANT",

"name": "IMPORTANT",

"type": "system"

},

{

"id": "CATEGORY_UPDATES",

"name": "CATEGORY_UPDATES",

"type": "system"

},

{

"id": "CATEGORY_FORUMS",

"name": "CATEGORY_FORUMS",

"type": "system"

},

{

"id": "CHAT",

"name": "CHAT",

"messageListVisibility": "hide",

"labelListVisibility": "labelHide",

"type": "system"

},

{

"id": "SENT",

"name": "SENT",

"type": "system"

},

{

"id": "INBOX",

"name": "INBOX",

"messageListVisibility": "hide",

"labelListVisibility": "labelShow",

"type": "system"

},

{

"id": "TRASH",

"name": "TRASH",

"messageListVisibility": "hide",

"labelListVisibility": "labelHide",

"type": "system"

},

{

"id": "CATEGORY_PROMOTIONS",

"name": "CATEGORY_PROMOTIONS",

"type": "system"

},

{

"id": "DRAFT",

"name": "DRAFT",

"type": "system"

},

{

"id": "SPAM",

"name": "SPAM",

"messageListVisibility": "hide",

"labelListVisibility": "labelHide",

"type": "system"

},

{

"id": "STARRED",

"name": "STARRED",

"type": "system"

},

{

"id": "UNREAD",

"name": "UNREAD",

"type": "system"

}

]

}

So, once you have this you can use your favorite JSON parser to read through the data to process it.