Authentication when using Google Cloud APIs from FileMaker
Hello.
My name is Teruhiro Komaki from frudens Inc.
We have published a solution to use each Google API from FileMaker on GitHub, but we have not written an explanatory article.
Since we often receive questions, we would like to publish several articles explaining the process.
Update (2022–04–19)
We have published an article on using Google Service Account to call APIs such as Google Forms.
Target audience
Those who want to integrate FileMaker and Google Cloud APIs
Goal
You can get an overview of what authentication methods you should use to achieve what you want to do.
Introduction
In this blog, we will give a supplementary explanation while quoting the official document.
If you find any mistakes in the content, please let us know.
Official documentation
The following documents describe the authentication when using Google Cloud APIs, so please check it first.
About「Authentication strategies」
When using API from FileMaker, there are the following three types.
Log in to GCP (Google Cloud Platform) and click on “Create Credentials” and you will see the same options as described above.
About「API key
An API key is a simple encrypted string that identifies an application without any principal. They are useful for accessing public data anonymously, and are used to associate API requests with your project for quota and billing.
As explained in the official documentation above, an “API key” is used when you want to use an API anonymously, such as Goole Maps, rather than an API associated with a Google account, such as Gmail or Google Calendar.
For example, the following APIs can be executed using API keys.
- Google Maps Platform
Using API Keys | Maps JavaScript API | Google Developers - Cloud Text-to-Speech
Speech to Text Transcription with the Cloud Speech API | Google Cloud Skills Boost - Cloud Vision API
Authenticating to the Cloud Vision API | Vision API Product Search | Google Cloud - Sheets API
Authorize Requests | Sheets API | Google Developers - Cloud Translation — Basic
Compare Basic and Advanced | Cloud Translation | Google Cloud
In addition to the above, various APIs can be used with “API keys.
If the API you want to use is available with an “API key,” simply create an “API key,” and you can use the API relatively easily.
Google Calendar used to be accessible with an “API key”, but the following URL indicates that it is not currently accessible with an “API key”.
Authorizing Requests to the Google Calendar API | Google Developers
Reference「API key」
Why and when to use API keys | Cloud Endpoints with OpenAPI | Google Cloud
About 「OAuth 2.0 client」
When an application needs to access Google Cloud APIs on behalf of an end user, the application initiates an OAuth consent flow. After the user completes the flow, your application receives an access token that enables your application to call Google Cloud APIs on behalf of the user.
The official diagram will be easier to understand.
General description of the consent flow
- Developer creates application.
- The developer creates the URL for the consent screen.
- The user opens the consent screen URL in a browser.
- The user agrees to the consent screen.
- The user is redirected to the URL specified by the developer.
(An authorization code is set in the URL.) - The redirected website can access the authorization code set in the URL.
- This destination varies depending on the environment.
For supplemental information, here are two specific examples.
Example 1: OAuth 2.0 Playground
Access the following Playground URL
Select Gmail API and click “Authorize APIs”.
Sign in with any Google account.
An agreement screen will appear.
If you agree, you will be redirected to the pre-designated URL.
If you check the URL, you will see that an authorization code is set in the URL, such as “code=HOGE”.
You can use this authorization code to obtain a “refresh_token” and an “access_token”.
Click on “Exchange authorization code for tokens.
The “refresh_token” and “access_token” have been obtained.
(The difference between “refresh_token” and “access_token” and “expire” will be explained in another article.)
By setting the “access_token” obtained here in the header, you can use the Gmail API as a user with an agreed Google account.
Click “List possible operations” and then Click “GetProfile Users”.
The Request URL is set to
https://gmail.googleapis.com/gmail/v1/users/{userId}/profileChange “{userId}” to “me” and set
https://gmail.googleapis.com/gmail/v1/users/me/profileClick “Send the request.
The API response is now displayed on the right side of the screen.
Example 2: Todoist’s Google Calendar integration function
Todoist, a task management tool, has a function to connect to Google Calendar as follows.
Click on “Connect Calendar.
As with Playground, you will be taken to the consent screen.
Once you log in and agree, you will be able to use the Google Calendar API from your Todoist program.
How to check if you do not know whether you should use an “API key” or an “OAuth 2.0 client
Basically, use the “OAuth 2.0 client” for APIs that require access to user information.
Also, if you read the documentation for each API, you should know which authentication method to use, but you may not know at first.
For example, if you want to check if the Gmail API mentioned earlier can be used with an “API key,” you can do so by operating as follows
Go to the following API Reference page, uncheck “Google OAuth 2.0” under “Try this method,” and click “EXECUTE.
The error message states “API keys are not supported by this API.
{
"error": {
"code": 401,
"message": "API keys are not supported by this API. Expected OAuth2 access token or other authentication credentials that assert a principal. See https://cloud.google.com/docs/authentication",
"errors": [
{
"message": "Login Required.",
"domain": "global",
"reason": "required",
"location": "Authorization",
"locationType": "header"
}
],
"status": "UNAUTHENTICATED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CREDENTIALS_MISSING",
"domain": "googleapis.com",
"metadata": {
"method": "caribou.api.proto.MailboxService.GetProfile",
"service": "gmail.googleapis.com"
}
}
]
}
}Reference 「OAuth 2.0 client」
- RFC 6749 — The OAuth 2.0 Authorization Framework
Please refer to the URL above for more detailed information on OAuth 2.0. - Using OAuth 2.0 to Access Google APIs | Google Identity | Google Developers
Why we recommend a Google Workspace account instead of a free Google Account
There will be two types of accounts
- Free Google Account (hoge@gmail.com)
- Google Workspace account (hoge@yourdomain.com)
We do not recommend using the free version of Google accounts for business use.
Details will be provided in a separate article, but creating an “A public application” for a free version of Google Accounts will require Google confirmation work depending on the scope.
Also, the specification has changed considerably before the current flow was put in place, and it is conceivable that the specification may change in the future.
Therefore, we recommend using a Google Workspace account and creating an “An internal application” if you want to use it consistently in your work.
Please refer to the following documents for OAuth 2.0 “for public use” and “for internal use”, verification process, etc.
About 「Service accounts」
What are service accounts?
A service account is a special kind of account used by an application or compute workload, such as a Compute Engine virtual machine (VM) instance, rather than a person. Applications use service accounts to make authorized API calls, authorized as either the service account itself, or as Google Workspace or Cloud Identity users through domain-wide delegation.
For example, a service account can be attached to a Compute Engine VM, so that applications running on that VM can authenticate as the service account. In addition, the service account can be granted IAM roles that let it access resources. The service account is used as the identity of the application, and the service account’s roles control which resources the application can access.
A service account is identified by its email address, which is unique to the account.
Differences between a service account and a user account
Service accounts differ from user accounts in a few key ways:
- Service accounts do not have passwords, and cannot log in via browsers or cookies.
- Service accounts are associated with public/private RSA key pairs that are used for authentication to Google, and for signing data.
- You can let other users or service accounts impersonate a service account.
- Service accounts do not belong to your Google Workspace domain, unlike user accounts. If you share Google Workspace assets, like docs or events, with your entire Google Workspace domain, they are not shared with service accounts. Similarly, Google Workspace assets created by a service account are not created in your Google Workspace domain. As a result, your Google Workspace and Cloud Identity admins can’t own or manage these assets.
Best practices for using and managing service accounts
Service accounts represent non-human users. They’re intended for scenarios where a workload, such as a custom application, needs to access resources or perform actions without end-user involvement.
Choosing when to use service accounts
Service accounts can be used for many different purposes, but they aren’t always the best choice. The following section provides guidance about when to use service accounts, and when to avoid them.
Use service accounts for unattended scenarios
Not every application interacts with human users — instead, an application might be running in the background unattended. Unattended applications include batch jobs, worker processes that dispatch messages read from a queue, or a resource-monitoring agent.
As explained in the official documentation above, this is used in cases where applications such as FileMaker run in the background.
After creating a service account with GCP and subsequently creating a key, you can download a JSON file containing the authentication information as shown below.
If you check the contents of the JSON, you will see that an email address such as “test-ab3euo@stable-hoge-123456.iam.gserviceaccount.com” is assigned.
Therefore, if you want to use Google Drive or Google Calendar APIs from your service account, add “test-ab3euo@stable-hoge-123456.iam.gserviceaccount.com” to the sharing settings as shown in the figure below. to be accessible from the service account.
Delegating domain-wide authority to the service account
If you have a Google Workspace account, an administrator of the organization can authorize an application to access user data on behalf of users in the Google Workspace domain. For example, an application that uses the Google Calendar API to add events to the calendars of all users in a Google Workspace domain would use a service account to access the Google Calendar API on behalf of users. Authorizing a service account to access data on behalf of users in a domain is sometimes referred to as “delegating domain-wide authority” to a service account.
As explained in the official documentation above, by setting “Allow applications to access user data on behalf of users in the GoogleWorkspace domain”, you can access any user’s Google Calendar, Gmail, etc. from the service account.
Which authentication should be used
When using Google’s API from FileMaker, we can think of it as follows.
Next time
In this article, I explained about authentication when using Google’s API from FileMaker.
Next, we will publish an explanation article when using each API of Google from FileMaker with curl command (Insert From URL) using “OAuth 2.0 client” and “Service account key”.
If you have a request, please feel free to contact us on Twitter etc.
