Authenticating to the Data API
FileMaker, Inc has introduced a new form of authentication called the FileMaker ID. This is an integrated sign-on system intended to provide more consistent and manageable user authentication on FileMaker Cloud. The credentials are basically a valid email address and a password. The new FileMaker Cloud exclusively uses the FileMaker ID to authenticate users.
Given this, you would expect that you can just use that same email address and password for authentication with the Data API on FileMaker Cloud. However, this is not the case, at least not in a straightforward fashion. The documentation for the FileMaker Cloud Data API indicates you need to provide an authorization header with a FileMaker ID token:
In Postman, the login request would look like this:
Using FileMaker ID for External Authentication
We need something called a FileMaker ID token in order to use the Data API. The online help for FileMaker Cloud explains how to get one. Be prepared: it is a complex multi-step process.
In essence it comes down to making the authentication call directly to Amazon Cognito, which is the underlying mechanism that drives FileMaker ID. The help article includes example JavaScript code to make such an authentication call.
A Standalone Web Service
At Soliant Consulting, we wanted to simplify this process and provide you with the necessary code to make these calls. We decided to created a simple Node.js standalone web service that does all the heavy lifting for you. The web service is open source and available from our GitHub page. Because it is a standalone web service, you can integrate this authentication process into any of your automated workflows that require the use the FileMaker Cloud Data API.
When testing, you can use the Node.js web service without having to host it anywhere. Download the project from GitHub and open it in the free VS Code editor. In the Terminal window pane, navigate to the bin folder (“cd bin”) and type in “./www” to launch the web service. It will start listening on port 3000 by default.
Then you can use Postman to make a call: a POST call to the DNS name or IP address of the web service, the right port (which is 3000 in our VS Code example) and the /users endpoint. The body is a simple JSON construct with the FileMaker ID username and password that you want to use to log into the Data API.
Tokens
The response includes three tokens: an accessToken, an idToken, and a refreshToken.
According to the Amazon AWS documentation these tokens represent:
- The ID Token contains claims about the identity of the authenticated user such as name and email.
- The Access Token grants access to authorized resources.
- The Refresh Token contains the information necessary to obtain a new ID or access token.
You can disregard the access token as it serves no purpose for logging into the Data API.
Next, copy the idToken and paste it into Postman Authorization header (making sure to prefix it with “FMID “ (note the space and the fact that FMID is all uppercase). When you make the call to the Data API “sessions” endpoint to log into the Data API, you will receive a token that you can use for any subsequent calls to the Data API.
A couple of things to note:
1. With four different tokens involved here, things can get a little confusing. Let’s break down which tokens are involved where:
- On one hand, we have the FileMaker ID access token, ID token, and refresh token; on the other hand, we have the Data API login token. You need the FileMaker ID token (idToken) to log into the Data API, but you need the Data API token for any other call to the Data API.
- Your Data API token stays valid for 15 minutes after your most recent Data API call. If you do not make a call to the Data API within 15 minutes of your last call, the Data API token expires.
- At that point, you can re-use the idToken from the Soliant web service and call the Data API login again to get a new Data API token, but that will work only if that FileMaker ID idToken is less than an hour old. The FileMaker ID idToken expires one hour after it was generated.
- You can, of course, just use the web service again to get a new idToken. However, you could also use the refresh token you received in the original call. Refresh tokens are valid for 3 years.
- To use that refresh token, call the Soliant web service again, but use the /users/refresh endpoint. The JSON body to send it includes the username and the refresh token.
- The response returns a new idToken to use in a Data API login call that will give you a new Data API token.
2. All of this applies only when you are using FileMaker Cloud. It is not relevant if:
- you are hosting your files on FileMaker Cloud for AWS or with a 3rd party hosting provider.
- you have your FileMaker Server installed locally or as a cloud instance in your own AWS, Google Cloud, or Azure account.
Resources
- Download the Soliant web service from our GitHub page
- For information on how to use the Data API on non-FileMaker Cloud servers, read our other blog posts.
You can leave any suggestions and comments here on this blog post or on GitHub, and as always you can also find us on community.filemaker.com.
Hello, thanks for these details. I have downloaded Visual Studio Code and the project files from Github. I open the project in Visual Studio Code and start a new terminal window, and then type ‘cd bin’ and then ‘./www’ as instructed but terminal just comes back with ‘env: node: No such file or directory’. Any ideas what I might be doing wrong?
Screenshot of my Visual Studio Code session here: https://www.icloud.com/iclouddrive/0zelLxmPFB2tTT4twzB_klh-w#Screenshot_2020-01-29_at_03.38
Currently absolutely stumped on how to authorise with FM Cloud Data API, so any help much appreciated.
It looks like you do not have node.js installed on that machine. That sample web service runs on node.js so go grab it from nodejs.org first and then try to run it. If you don’t want to add things to your OS then perhaps use a small Linux VM instead.
Hello Wim,
Please find below what I am getting from the terminal window pane in VS Code…
From your VS Code screenshot, it seems like the only difference from what you can download from GitHub is that the node_modules repo is missing.
Tatai:FileMakerID_token seb$ cd bin
Tatai:bin seb$ ./www
internal/modules/cjs/loader.js:985
throw err;
^
Error: Cannot find module ‘http-errors’
Require stack:
– /Users/seb/Documents/GitHub/FM/FileMakerID_token/app.js
– /Users/seb/Documents/GitHub/FM/FileMakerID_token/bin/www
at Function.Module._resolveFilename (internal/modules/cjs/loader.js:982:15)
at Function.Module._load (internal/modules/cjs/loader.js:864:27)
at Module.require (internal/modules/cjs/loader.js:1044:19)
at require (internal/modules/cjs/helpers.js:77:18)
at Object. (/Users/seb/Documents/GitHub/FM/FileMakerID_token/app.js:1:19)
at Module._compile (internal/modules/cjs/loader.js:1158:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1178:10)
at Module.load (internal/modules/cjs/loader.js:1002:32)
at Function.Module._load (internal/modules/cjs/loader.js:901:14)
at Module.require (internal/modules/cjs/loader.js:1044:19) {
code: ‘MODULE_NOT_FOUND’,
requireStack: [
‘/Users/seb/Documents/GitHub/FM/FileMakerID_token/app.js’,
‘/Users/seb/Documents/GitHub/FM/FileMakerID_token/bin/www’
]
}
Tatai:bin seb$
HI Sébastien,
From inside VS Code, in Terminal, make sure that you are inside the project and then type in “npm install” which will collect all the necessary Node packages and install them.
Thank you Wim for sorting me out !
Things are working (sort of) now…
This is the JSON response I am getting with the code 200 !?!
{
“user”: “xxxxxxxxxx”,
“tokens”: “”,
“error”: “MFA required”
}
This seems like a new “feature” of FileMaker Cloud 2.18.1.1056 🙁
I’ve tested the web service with FM Cloud 2.18.1056 and it works fine. In my.filemaker.com, go to your profile and turn off the MFA setting. Or if you have room in your FM Cloud subscription for an additional licensed account, create an account and set it to not use MFA and treat it as a ‘service account’.
Works like a charm 😉
Thank you for your patience.
Hello Wim!
I have a trouble.
I get this answer:
{
“user”: “email@clarisid.com”,
“tokens”: “”,
“error”: {
“code”: “NotAuthorizedException”,
“name”: “NotAuthorizedException”,
“message”: “Unable to login because of security reasons.”
}
}
And after two or three attempts, I get an e-mail of Claris, requesting me an authorization of my Location.
I’m in mexico, so, I need to be connected from USA to get no errors?
Thanks for your guide!
Most likely that is because that Claris ID is set up for two-factor authentication. Log in to my.filemaker.com with that Claris ID, click on the email address on the top right in the black banner and choose ‘Profile’. Scroll down to the Security section and turn off the ‘two-step verification’.
Hello Wim!
It was for privileges of the accounts. I finally Get the FMID Token, so that I can work with DataAPI in FMCloud.
Thanks a lot!
I’m currently having a similar issue:
For using Filemaker API, I created a separate Claris ID, with no 2FA. Also set up privileges for that account on the database and enabled API extension on Filemaker Cloud.
As explained in documentation, using node.js Amazon Cognito Identity JS to give me the token for Claris ID, but the response I’m getting is:
[{“code”:”NotAuthorizedException”,”name”:”NotAuthorizedException”,”message”:”Unable to login because of security reasons.”}]
Also receiving emails for confirming login attempts from different location.
Can you advise on how you solved it?
Hi Cristina,
Are you using our utility or creating your own to interact with the Amazon Cognito APIs?
Hello Wim,
I’m trying to use Data Api for site-to-database communication (backend fetch calls). My site is hosted on ‘Wix’ (working with integrated developer platform ‘Velo’), and I installed npm package Amazon-Cognito-Identity for this, so I’m the javascript code that documented here: https://help.claris.com/en/customer-console-help/content/create-fmid-token.html?
Is there a way for me to install/use your utility using Wix Velo platform?
Thanks in advance,
Cristina
Hi Cristina,
I’m not familiar with Wix Velo and at first glance seems to be focused on front-end JS. They do have API abilities (https://www.wix.com/velo/forum/tips-tutorials-examples/example-myapi-and-myapiclient) so perhaps most of the code can be replicated as its own Velo API. I would shy away from this in front-end API; with a back-end API you can better shield your secrets.
Hi Wim,
It’s backend, no problem there. Also regarding Wix Velo I’m conformable enough using their api and making fetch http requests. The problem is on filemaker cloud authorization process. For exemple in fms it would be a simple basic auth. Filemaker Cloud demands cognito token and when I make that request it denies access because it doesn’t recognize ip location. I’m stuck.
You’ll need to contact Claris support to see if they can relax the geo / device / IP rules.
The alternative is to host the backend microservice in a place where you can do at least one manual Claris ID authentication from. For that reason we host ours in-house.
Hi Wim
Thank you very much for your response. I had no ideia that cloud would end being so limited, regarding API, and I just recently bought the subscription to give it a try. Previously I was using FMP. Next year I definitely change to FMS. Regards. Cristina
I have a question.
How can I deploy your WebService on a Windows Server? I have never installed a webService and I don’t know where to start.
What I need to do that?
Hi Juan,
The ‘how-to’ would take more space than we have here; I’ll write it up in separate blog post.
Best regards,
Wim
Hi Wim,
I have got the Node service running on 127.0.0.1:3000, but when I run the POST method, and supply the username and password in the body, this is the error I get, and I am not able to move forward.
Unexpected token = in JSON at position 17
400
SyntaxError: Unexpected token = in JSON at position 17
at JSON.parse ()
at parse (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/body-parser/lib/types/json.js:89:19)
at /Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/body-parser/lib/read.js:121:18
at invokeCallback (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/raw-body/index.js:224:16)
at done (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/raw-body/index.js:213:7)
at IncomingMessage.onEnd (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/raw-body/index.js:273:7)
at IncomingMessage.emit (events.js:327:22)
at endReadableNT (_stream_readable.js:1220:12)
at processTicksAndRejections (internal/process/task_queues.js:84:21)
Hi,
Unfortunately that doesn’t give us enough information to troubleshoot. This could be one of two issues:
1) when you installed the micro service, did you do an “npm install” to load all the referenced modules?
2) assuming that you did, it looks like the JSON that you are sending is malformed and not recognized as JSON. Pay particular attention to quotes and commas.
Feel free to create a post on community.claris.com and reference me by name, and post some screenshots of what you are sending.
I tried to follow the directions and I keep getting this error…
PS D:\Downloads\FileMakerID_token-master\FileMakerID_token-master\bin> .\www
Program ‘www’ failed to run: No application is associated with the specified file for this operationAt line:1 char:1
+ .\www
+ ~~~~~.
At line:1 char:1
+ .\www
+ ~~~~~
+ CategoryInfo : ResourceUnavailable: (:) [], ApplicationFailedException
+ FullyQualifiedErrorId : NativeCommandFailed
Please help
Hi Michael,
It sounds like you are trying to run this on a system that does not have Node installed yet. You can confirm that with this command from that folder: ‘npm start’
If you don’t have Node.js installed yet you can get it from here: https://nodejs.org/en/download/, or alternatively if you intend to work with different versions of Node, you can install the Node Version Manager (nvm) with these instructions for Windows: https://docs.microsoft.com/en-us/windows/nodejs/setup-on-windows
so it seems that the terminal is listening because every time I do a post. A new POST /users line pops up.
But what I am getting from POSTMAN is:
{
“errors”: [
{
“msg”: “Invalid value”,
“param”: “password”,
“location”: “body”
},
{
“msg”: “Invalid value”,
“param”: “username”,
“location”: “body”
}
]
}
Help!
Ok so I figured out that in POSTMAN it was listed as text and not JSON. Got my tokens!!!
Thank you for your help and will definitely reach out, maybe on community, if I have any other questions.
Even with the Bearer token if the claris cloud login is closed the data does not get fetched with the api. So is there any way to keep the data flowing through the api even after the claris cloud is logged out.
Can you provide a bit more detail on “if the claris cloud login is closed”?
The Data API is session-based, so if the session token expires, no calls will work anymore. Is that the scenario you are running into? If so – in your code – you can check the token’s validity and get a new one issued if it has expired so that the data flow is not interrupted.
problem is data doesn’t come even bearer token generation until we should login in Claris could then only we get data if we want data we should login in Claris but due to time out Claris login closed how to fix this issues can you please help me
I’m not sure I follow the “we should login in Claris” part. The whole routine is centered around *not* logging into my.claris.com at all but rather get a token from AWS Cognito and use that token to exchange for a Data API token.
The only thing to check: make sure that the Claris ID account that you use does not have two-factor authentication turned on.
Feel free to contact us directly or start a thread on community.claris.com, we would have to see screenshots of the full sequence to see what that Claris login looks like and where it fits into the entire flow.
Wim,
I agree with your comment “The whole routine is centered around *not* logging into my.claris.com at all but rather get a token from AWS Cognito and use that token to exchange for a Data API token.” However, I experience the same behaviour as Prem. If your process is executed in a “clean” environment (machine has not been logged into my.claris.com), the idToken is returned from AWS Cognito but the subsequent request for a bearer (data) token fails with error “401 Authorization Required”. However if you now log on to my.claris.com with valid Claris ID and resubmit the request for a data token it will succeed. It would be interesting if you can replicate this behaviour? I have a business partner who is trying to access our data with the API using AWSSDK.CognitoIdentity (https://www.nuget.org/packages/AWSSDK.CognitoIdentity/). They experience the same issue. I have raised this with Claris support using your blog post to provide “proof of concept” of the issue but they have not been able to help as they cannot support 3rd party software (i.e. yours).
Hi Christian,
I will try and replicate the issue. In the meantime and to get proper support from Claris, I would suggest trying the JavaScript example they have in their help docs. That way they cannot refuse support if it fails there as well.
Best regards,
Wim
I have just posted in this thread: https://community.claris.com/en/s/question/0D53w000057xo1BCAQ/need-help-with-bringing-data-using-the-claris-data-api-with-react-js
with screenshots of using the micro service to get the Cognito token, exchange it for a Claris token and then query the FileMaker cloud 2.19.1.211 Data API with that Claris token.
You are a life saver.
I cannot express how pissed I am with Claris for making something they should provide (as every other API provider I have worked with does) so obscure. 5 hours, 2 extra software packages on my Mac plus your invaluable help and I finally have 255 characters of gobbledygook.
It would be something if they were providing this technology for free but when we have paid over £1,000 i think their attitude is outrageous.
Hi Chris,
Glad that it helped you out. The extra hurdles to make this work on FM Cloud are definitely on Claris’ radar but do make sure to add your voice to the Product Ideas section, vote on any product idea that was already raised to make this better. There are a few that ask for better tokenized access. And potentially raise it as a Product Issue to make sure Claris Support is aware.
https://community.filemaker.com/s/ideas
https://community.filemaker.com/community/discussions/report-an-issue
Best regards,
Wim
Thanks for contributing this to the community! Minor documentation bug: the Claris help page referenced (https://fmhelp.filemaker.com/cloud2/edition/en/customer-console-help/#page/fcc-help%2Fcreate-fmid-token.html) looks like it moved to https://help.claris.com/en/customer-console-help/content/create-fmid-token.html
Hey Wim thanks so much for the work you put in on this. Quick question, how would I deploy the web service on an outside web server where I don’t have access to download and run it (bluehost)?
Hi Darren,
A couple of different options: spin up a tiny Linux instance at your preferred virtual server provider (AWS, Azure, Google Cloud, Linode…) and host it there. It doesn’t need to run on your FileMaker Server. Or you can deploy the code as an AWS Lambda function or other similar server-less deployment options.
Best regards,
Wim
Hi Wim,
First of all thank you so much for this guide.
I have been able to authenticate, add data and use this from my computer locally including our local servers using the instructions above , but when I move the code to AWS it keeps giving me the error
“Unable to log in because of security reasons.” and then I also get an email saying
“New Claris ID sign-in attempt
We blocked a sign-in attempt to your Claris ID account using the following unrecognised information:”
I have checked to make sure there is no 2FA on the account used to login.
I have tried this from different services in AWS (Lightsail, EC2, Lambda) and they all resulted in the same error.
Do you know why this would be happening ?
I believe that claris is using some sort of whitelisting-by-origin. You may be able to see something in the Access.log, Data API log or FMS event log. You can download those logs from the admin console.
If you have a desktop on your AWS instance you can try to log into my.claris.com with a browser and then try the API call.
FM Cloud is a bit of a black box though so your best bet for a definitive answer is to get in touch with Claris support.
Best regards,
Wim
Thanks Wim,
Will give this a try and also go through the logs.
Just a simple question
Would there be a PHP/JavaScript ready to host this?
I have a client that wants pages that post to send data straight to his API,
You can host this pretty much anywhere and then call the endpoint from your PHP or JavaScript. You can even take the code and turn it into a serverless function (Lambda on AWS for instance).
Hello Wim, this is a valuable reference, thank you so much. I have a minor error when running the webservice. Have a quick idea ? package.json include the node-fetch required.
global.fetch = require(‘node-fetch’)
—>> Error [ERR_REQUIRE_ESM]: require() of ES Module …/FileMakerID_token/node_modules/node-fetch/src/index.js from /…FileMakerID_token/routes/users.js not supported.
Instead change the require of index.js in /…/FileMakerID_token/routes/users.js to a dynamic import() which is available in all CommonJS modules.
In your project’s terminal window run this command:
npm install node-fetch@2
This will revert node-fetch to the previous (but still supported) version. I’ll push the change to the repo later today.
Hi Wim,
I have downloaded this node js service.
I want to host it or rather run it with API call instead of via PostMan.
Can you please help me with this.
If I run using npm start and call via PostMan, it works fine, but I want to call it as API service. I have hosted the files on web server. How do we call it?
Sorry this might be a very simple question.
Your help is appreciated!!
Hi Shweta,
It’s a node.js Express app so you can use any Process Manager you are familiar with. Some of them are listed here: http://expressjs.com/en/advanced/pm.html
We tend to use PM2. Also note that the web service as-is does not handle SSL so we typically use a reverse proxy on one of the available web servers (the one used by FMS will do) to let it take care of the SSL termination and then forward the traffic to the token microservice.
We don’t have a blog post on PM2 yet, but the reverse proxy part is described in this blog post: https://www.soliantconsulting.com/blog/filemaker-oauth-keycloak/
Thanks a lot Wim. I will check this.
Hi Wim,
If we have a web server with SSL and if we run this node.js express app there with Process manager, then Do we need to do this reverse proxy?
Thanks,
Shweta
Strictly speaking you don’t need to, you could open a port and forward it directly to your node app. But typically you will want to do reverse proxy through your existing web server, which makes SSL termination a lot easier and gives you the benefit of any security and logging configuration you already have there.
Okay… thanks a lot Wim..
Thanks a lot Wim, always some excellent solutions from you / Soliant!
I would like to follow your suggestion to go server less with this code using AWS Lambda. Do you, or does anyone here has got a how-to? I have uploaded the code to a Lambda function, but now it wants me to add a ‘trigger’, when to execute this code. I was hoping to be able to create a URL like https://awsserver.com/user/function:3000, but I’m far from that, although so it seems. Can somebody give me some directions?
Best, Corné.
Hi Corné, and thanks for the kind words.
Yes, our teams have the required expertise – Soliant is an AWS Advanced Tier Services partner.
The typical deployment would involve using AWS API Gateway, which will give you the URL you are after and can help protect your deployment. The API Gateway will then trigger the Lambda function when the incoming request looks ok. There are some variations on this that can be used depending on the volume of traffic you expect.
Best regards,
Wim
Hi Wim,
Thank your for your reply. It seems a pretty deep dive for me into the offered AWS services, a simple upload of your files from Github to Lambda plus a API Gateway to fetch the HTTP request doesn’t seem to work right away. I’ve been browsing YouTube video’s in order to get an idea how to make the transformation from the Node.JS app to Lambda / API gateway, but until now no sigar. I’ll keep on diving, but if there’s a more info at hand, I’d be very interested.
Hi guy’s, great article! but I get an issue when requesting the token:
https:///fmi/data/vLatest/databases//sessions
502 Bad Gateway
502 Bad Gateway
nginx
Hi Laurent,
Assuming that you had the host and the database properly filled into that URL, the error would mean that the web server on your FM Cloud instance isn’t working correctly. Reboot it or call Claris support.
I’ve just ran the code against our current FM Cloud (version 2.19.6.304) and it works as expected.
Wim,
Its 2023 and works like a charm. Detailed explanations man.
Thank you for your time and work.
I run the .\www command and it seems to take. However doing a port scan I don’t think anything is running on 3000 on my local host. When I do the post command I get the message below. I must be missing something in getting it up and running. I did load node.js as well based on some other comments, running it on Windows 11
POST http://localhost:3000/users
Error: connect ECONNREFUSED 127.0.0.1:3000
Request Headers
Content-Type: application/json
User-Agent: PostmanRuntime/7.39.0
Accept: */*
Postman-Token: cb09f469-28ad-4bfd-a03c-6a5381b7ca7f
Host: localhost:3000
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
From the FileMakerID_token folder, run “rpm start”, which will launch the www file for you but may give you better error information. The ECONNREFUSED tells you that either nothing is listening on port 3000 or that a firewall is blocking access.