The FileMaker Data API and OAuth
You can connect to the FileMaker Data API using OAuth 2.0. The steps involved are described in the FileMaker Data API Guide.
Trying to make this work with a PHP client application, I found out that there are some caveats. In this blog article, we will walk through all steps involved to connect a web application to the FileMaker Data API using OAuth.
I developed a PHP connector for the FileMaker Data API which is freely available on Github. With this connector, any PHP application only needs to instantiate a class object and do a few things to connect to the FileMaker Data API.
This blog article assumes you have some basic knowledge of the HTTP protocol, i.e. you know what an HTTP method or an HTTP header is. No other knowledge is required. Although referring to PHP at some points, the outline is quite generic and can be used to in any other programming languages capable of making HTTP calls.
OAuth: Why bother?
Now, why bother with OAuth at all? If this really is the new kid on the block, what benefits does it have? There are a few advantages of using OAuth over other authentication and authorization methods, the main one of which is that a client application does not need to store credentials to log in into a FileMaker database. Before FileMaker Server 16 for example, if you wanted to get data from a FileMaker database with the CWP, you needed to store an accountname and password in some place, like a file or an external database. This is obviously a serious security risk. OAuth 2.0 eliminates this need, and literally gives the key to the end user, so she or he can decide wether your application is authorized to access some FileMaker data, and let an external authentication provider like Amazon, Google or Microsoft security handle authentication. End users can have their credentials safely in one place, and log in through OAuth in a multitude of apps.
In order to fully understand what is going on, you need to be familiar with some OAuth 2.0 concept.
OAuth defines four roles:
- Resource Owner: This is the end user that want to.
- Resource Server: The server hosting the protected resources. Resources can be personal data on a Facebook server, and in our context are data that live in a FileMaker database on a FileMaker Server
- Client: An application making protected resource requests on behalf of the Resource Owner and with its authorization. If you are developing a PHP application for example hat need to connect to a FileMaker Server with the end user authenticating with its Google account, then your application is called the Client.
- Authentication/Authorization server: The server that manages authentication and authorization of the Resource Owner
The original specification (IETF RFC 6749), which actually is a pretty good read, describes the following basic protocol workflow:
The abstract OAuth 2.0 flow illustrated in Figure 1 describes the
interaction between the four roles and includes the following steps:
(A) The client requests authorization from the resource owner. The
authorization request can be made directly to the resource owner
(as shown), or preferably indirectly via the authorization
server as an intermediary.
(B) The client receives an authorization grant, which is a
credential representing the resource owner’s authorization,
expressed using one of four grant types defined in this
specification or using an extension grant type. The
authorization grant type depends on the method used by the
client to request authorization and the types supported by the
(C) The client requests an access token by authenticating with the
authorization server and presenting the authorization grant.
(D) The authorization server authenticates the client and validates
the authorization grant, and if valid, issues an access token.
The FileMaker Data API OAuth implementation
In order to make this all work, you need to have a few things set up:
- An installation of FileMaker Server 16 (or higher :-)).
- One or more configured OAuth Providers in the FileMaker Server Admin Console. For example, you have to enter the Client ID and Secret obtained from the Google API Developer Console in the FileMaker Server Admin Console. This article is assuming you know how to configure OAuth Providers within FileMaker Server. If you are not comfortable with it, please refer to the FileMaker Help for more info on how to set this up.
- One ore more OAuth accounts set up in the Security (Manage -> Security…) of the database file(s) you are going to connect to. We are going to use an external account (i.e. a Google account) to log in, and this account needs to be registered in the database.
- If you are using the PHP FMDataAPIOAuthConnector, you will need an installation of PHP 5.6 or higher and have the curl extension enabled. If you are using the PHP installation of FileMaker Server, you are good to go.
To implement the OAuth implementation in a client application, you need to know how to hande outbound and inbound HTTP calls (i.e. using ajax or cURL) , because there is a lot of redirection in the OAuth workflow.
Now enough preliminary checks, let’s gear up and go on our journey!
The OAuth model as implemented by the FileMaker Dat API is a complex set of calls between the actors in the OAuth model. The steps are all described in the documentation, but without too much explanation. Here is a graphical overview of all calls involved:
Now, let’s go to all of these calls in detail.
Step 1: Get a RequestId and send a Return URL
First of all, you make a call to FileMaker Server:
- [host]: this is the hostname of your filemaker server, e.g. ‘your server.yourdomain.org’
- [tracking-ID]: an optional tracking id.
- [OAuthprovider]: the name of the OAuth provider, e.g. ‘Google’
You can get a list of the names of the OAuth providers configured for your FileMaker Server installation by calling this URL: https://[host]/fmws/oauthproviderinfo. It returns JSON with all details on the configured OAuth providers.
The hostname in the ‘address’ URL query value and the X-FMS-Return-URL header MUST match, if not an HTTP error 400 (Bad Request) is yielded.
Step 2: Receive RequestId and OAuth Authentication URL
From your request in Step 1, you receive following HTTP response:
- Response Header: The RequestId in the ‘X-FMS-Request-ID’ header
- Response Body: OAuth provider call URL to authenticate
A caveat here is that the scope parameter in the authentication URL is, strangely enough, contains spaces. You should replace this by the ‘+’ character in order to make the following call.
Step 3: Call The OAuth Provider’s authentication URL
This is simple. Now we call authentication URL obtained in the previous step.
Step 4: User Authentication
Now hang back and relax for a while. The authentication and authorization is handled by the OAuth Provider now (Google, Microsoft, Amazon).
This is where the typical screens like the one from Google below are seen by the end user:
Step 5: OAuth Provider redirects to FileMaker Server
If the end user (the Resource Owner in OAuth speak) successfully authenticates, The oAuth Authentication Server redirects back to FileMaker Server. This is important to know, it is FileMaker Server and not your client application that receives the first hand notification that the end user has logged in successfully. This is slightly different from the basic OAuth workflow, where the Client receives the Access Token from the Authentication Server (the OAuth Provider) and then Passes is to the Resource Server (which would be FileMaker Sever).
The redirection link to FileMaker Server is passed to the oAuth provider in the calling URL in step 4, see text bold:
Step 6: FileMaker Server calls you client application
After FileMaker Server receives the notification from the OAuth Provider in the previous step, it in turn calls your Client Application by using the return URL you initially provided in Step 1, in the ‘X-FMS-Return-URL’ header. It send your client application an Identifier. This is a authorization code representing an authorization approval for the client.
The return URL can be anything you want, even a PHP script on an external webserver (although it makes little sense to do that, unless you enjoy a bunch of good HTTP calls per se).
FileMaker Server sends an Identifier as part of a HTTP GET request in the return URL call. For example, if you specified ‘https://yourserver.yourdomain.org/myspecialscript.php’ as return URL, your script will be called by FileMaker Server here as ‘https://yourserver.yourdomain.org/myspecialscript.php?identifier=ABC123’
Step 7: OAuth Login with FileMaker Server
Now your Client application has the 2 pieces of information necessary to make the actual login call to FileMaker Server itself: a RequestId and an Identifier.
Now you do the actual login call to FileMaker Server. Here is how you do it, straight from the documentation:
Step 8: FileMaker Server sends an Acces Token
Finally, if everything went well, FileMaker Server sends an Access Token to your client application. You can now actually do something useful (i.e. retrieve a list of records) and pass the Access Token in all following calls to the FileMaker Data API.
The implemented model is quite complex. Additionally, FileMaker Server plays different roles in the workflow, which might be somewhat confusing.
FileMaker Server plays a role as part of the Client Application:
- It receives an authorization grant from an OAuth provider (Google, Microsoft or Amazon currently)
- After redirect from the oAuth provider, FileMaker Server redirects in turn to the “other” Client application, i.e. a custom web application connecting to the FMS Data API.
FileMaker Server plays a role as an Authentication Server:
- It receives an authorisation grant (represented in the Request Id and Identifier) and returns an access token.
FileMaker Server is also the Resource Server.
About the FMDataAPIOAuth Connector
The FMDataAPIOAuthConnector is intended for PHP web applications to facilitate the OAuth authentication process when connecting to FileMaker using the FileMaker Data API. It shields developers from the complexity of the FileMaker Data API OAuth implementation. Specifically,through a simple instance of a class object, it retrieves RequestId and Identifier necessary for an OAuth Login call.
After retrieval of these 2 pieces of information, your PHP application has all that is necessary to do the actual login request and obtain an Access Token from FileMaker Server. Please refer to the FileMaker Data API reference documentation on how to to perform that call.
It is important to note that the Connector is not a wrapper around the REST API from FileMaker Server, but only a handler to facilitate the OAuth login. Your application will still need to make HTTP calls to the FileMaker Data API in order to log in and retrieve data from FileMaker Server.
The general outline of using the connector is this:
- Your application shows a login page where your application users (or, in OAuth language ‘Resource Owners’) can click a login button linked to an OAuth Provider (Google, Amazon or Microsoft Azure). You specify a callback URL for your application for the connector to call after users successfully log in.
- The Connector calls the callback script and your application can retrieve the RequestId and Identifier necessary to log in into a FileMaker database.
This significanty simplifies the process to log in to FileMaker and connect to the data API.