Using RESTfm to build OAuth callback urls

by | Mar 4, 2020 | Uncategorised | 0 comments

If you think that RESTfm isn’t needed any more because FileMaker Server now has a JSON Data API, then I’d like to give you an example of where RESTfm shines in a way that the Data API will never allow.

And it lets us solve a previously intractable FileMaker problem with doing authentication via an OAuth 2 workflow.

FileMaker Connecting to Xero’s new OAuth 2 workflow

Previously, connecting to Xero required doing OAuth 1.0 via a private/public key pair. Even if you don’t understand what that means the short answer is that there is no native way for FileMaker to talk to the Xero API without the use of a plugin. In our case we added a function to the BaseElements plugin that did this for us, and that anyone else could use for free too.

But Xero has changed their workflow now, such that all connections go through an OAuth 2 workflow. The process starts with the developer registering their app on the Xero website. After that, every time you want FileMaker to connect you do :

  1. Open a web page with the public connection details of the developers app.
  2. Get the user to login to Xero.
  3. Let the user “Authorise” your app and select which parts of Xero you can connect to.
  4. Get a redirect url call back into FileMaker that contains the authorisation codes from Xero.
  5. Verify the auth codes with Xero and get access tokens.
  6. Use the access tokens to access the API.

So all that is perfectly doable in FileMaker native, with one exception : in step 5, there’s no way to have a url call FileMaker in a way that will properly pass the parameters.

FileMaker URLs and parameters

FileMaker has it’s own url scheme, it looks like this :

fmp://{{account:password@}address/}filename{?script=scriptname{&param=scriptparameter}{&$variablename{[repetitionnumber]}=value}}

Note that there are some fixed parameters ( script and param ) and then everything else is done via $variables. But FileMaker doesn’t let you add extra parameters. Anything other than script or param is ignored. So there’s no way to have FileMaker accept the callback url.

RESTfm to the rescue – accepting the redirect

The thing is, RESTfm can accept urls. And it can output custom formatted text. So we can use RESTfm to accept the incoming url, respond to it in whatever way we want, and then redirect the data we need back into the local copy of FileMaker via a calculated fmp url.

The trick is that RESTfm lets you accept the original url even though it’s a GET, and turn it into a POST so that you create a record, and authenticate and run a script ( if required ) and return a HTML page redirecting to FileMaker Pro locally. The redirect URL that we give to Xero is something like this :

https://server.domain/RESTfm/OAuthRedirect/layout/Redirect.html?RFMkey=key&RFMmethod=POST

server.domain is the location of our FileMaker server, running RESTfm.

OAuthRedirect is the name of the FileMaker file that contains a table to post into.

We are authenticating with a key ( the key isn’t hidden, anyone needs to be able to post to the url as it’s coming from a browser window, but we authenticate back to Xero later to validate codes ), and overriding the GET by adding RFMmethod=POST. We could also add RFMscript=Name if needed to run a script on the incoming data and do any processing required.

The Xero codes that we need just get are added to the data being sent to the url, and in this case are just fields in the FileMaker database. Xero writes to the code, state, scope, session state and error fields. We have a calculated “url” field that looks up whether this code has been used before and if not generates the right url. As you can see below, the url field now contains our working fmp url.

So that’s all good and well, we now have the data in FileMaker on an external FileMaker server, but not necessarily where we need it, as we might have started this process from a local file, or a file on a local network etc. But this first step happens in a local users browser, as the whole authentication process starts there. So how do we get it into our local copy of FileMaker Pro?

RESTfm to the rescue again – custom formats

So the other feature we’re going to use in RESTfm is the ability to have custom output formats via XSLT. Not just JSON like the Data API. We can do XML, csv, HTML, ics, plain text, FileMaker XML, basically whatever you want.

( Don’t worry if you don’t know XSLT, we know it inside out, and write XSLT for our clients all the time. )

In this case were going to do custom HTML. Even though HTML is a built in native format for RESTfm, we can build our own version of the HTML output and override the built in one. In this case we generate HTML that is basically :

<html><head>

<meta 

http-equiv="Refresh" 
content="0; url=fmp18://$/XeroIntegration?script=redirect&$code=abc&$state=7BE0A1E4-0A4E-4915-B27F-3BCE1E6822DC"

/>

</head></html>

I’ve broken it out a bit, but the basic idea is that this little bit of code does a redirect automatically using the fmp url we calculated. And it passes along the data we need ( code and state ) as $code and $state variables, so we can get them in the FileMaker. In this case $ means a file open locally in FileMaker Pro, and XeroIntegration is the name of that local file, and redirect is the script name to call.

There’s a bit more to the XSLT code than that, as it also has some text to say “If it doesn’t open, click this link” and some error handling if it’s called without the right data.

And the best bit is that the local file location and name can be set dynamically, before the auth process starts. So it could redirect anywhere.

But in a nutshell, this is a FileMaker file with 2 tables, and a total of 9 fields, plus a 38 line XSLT file on the server. And we’ve got a full end to end OAuth 2 redirection working. It’s working for Xero, but could work for any process that requires OAuth 2 workflows. And nothing to install on the client, no plugins, no extra code on their FileMaker server, and it works within a browser so is entirely capable within a secure local network. That’s the sort of code you like to deploy.

It’s always amazing to me what RESTfm can do. The customisation and flexibility you get keeps coming up in situations where we can either build something that otherwise just couldn’t be done, or we can do things much simpler and easier than any other method.

RESTfm has a long future ahead, and it’s certainly not being superseded by the Data API any time soon.

If you need OAuth 2.0 workflows in FileMaker Pro, contact us for more details about integrating this into your own solutions.