GAM Open-Source Project
How GAM interacts with Google
GAM is an open source tool. This means anyone can use GAM and anyone can make it better. However it also presents some challenges in allowing admins to securly setup their GAM instance. Google uses projects to provide developrs with Google API quota, credentials, service accounts and client IDs. Because GAM is open source, it's not possible to share one Google project among all GAM users and installations. For this reason when you first install GAM, it walks you through and automates a significant portion of the project creation process. GAM setup automates the following steps with your new project:
- Creating a Google Cloud project
- Creating a service account user
- Creating a private key to authenticate the service account (stored in the oauth2service.json file)
- Enabling Google APIs such as Admin SDK, Gmail API and Drive API for your new project
Some project setup steps cannot be automated, thus GAM walks you through the following steps:
- Creating an installed app client ID and secret for your project (stored in the client_secrets.json file)
- Entering your project name for the OAuth consent screen.
In order to automate the process of creating a new Google project, GAM needs authorization from your Google user to make the API calls necessary for the above steps. To do this, GAM prompts you to approve temporary (1 hour) access to make changes to your Google Acconts Cloud Platform projects and settings. GAM uses a single, special Google project (owned and managed by Jay Lee to authorize and perform the above actions. This is a short-lived authorization and is not stored anywhere other than in memory, once you stop the GAM process the authorization is lost and Google expires it on it's end after one hour. Once you've completed the above GAM setup, you are ready to give your new Google project access to your G Suite admin user and G Suite instance. There are two pices to cover here:
- In order to use G Suite / Cloud Identity admin APIs, you must authorize your new API project to act as an admin user. As soon as you run a GAM command that calls Google admin APIs GAM will prompt you to select which API scopes you want to use, your admin email address and then direct you to a URL like https://gam-shortn.appspot.com/nnnnnn. The gam-shortn.appspot.com is a simple URL shortner tool that makes it easy for you to copy paste the URL into your browser. As soon as you enter the full URL you are immediately redirected to Google servers. Here you can authorize your GAM project to make admin API calls as your admin user.
- GAM can also make API calls that interact with your G Suite users data such as Gmail, Calendar and Drive. It can do this for all users in your G Suite domain. To do this GAM walks you through the process of granting the service account you created above domain-wide delegation. This allows GAM to authenticate as the service account you created but act on the Gmail, Drive and Calendar data of users in your G Suite domaini.
At the end of all this setup, you are left with three files which you should keep secure:
- client_secrets.json - this file stored a client id and secret that identifies your Google project so that your admin user can authorize your project to make admin API calls and so that you have your own API quota. You can share this file with anyone you wish to be able to use your Google project and it's quota. It does not contain sensitive information about your Google account or G Suite domain but generally should remain secure so others can't use your project.
- oauth2.txt - this file stores the OAuth credentials GAM uses when making admin API calls as your admin user. Anyone with access to this file can make API calls as your Google admin user so this file should be kept secure.
- oauth2service.json - this file stores the private key of the service account you created above. The private key acts similar to a password to authenticate to Google. Thus anyone with this file can make API calls as your G Suite users accessing, modifying and deleting your users G Suite, Gmail, Drive and Calender data. For this reason this file should be kept very secure.
If you have further questions about how GAM is setup, what you are granting GAM access to and how GAM manages your data, please reach out on the GAM mailing list.