All the FileMaker OAuth guides and white papers that we have written and co-written with Steven Blackwell have all dealt with using the OpenID Connect authentication flow (OIDC).
FileMaker Server has supported OIDC since version 16, and it is still using that for its built-in providers (Google, Amazon, Azure AD, and AD FS). In our OAuth work up to this point, we have expanded that pool of proven Identity Providers but always through the OIDC mechanism.
FileMaker Server 19.4 introduced a new feature that allows you to specify that the authentication flow should not be OIDC but rather the full OAuth2 flow.
What’s the difference?
| OIDC Flow | OAuth2 Flow | |
|---|---|---|
| On the FileMaker Pro or WebDirect login dialog, the user clicks on identity provider button | On the FileMaker Pro or WebDirect login dialog, the user clicks on identity provider button | |
| FMS takes the user to IdP's login page | FMS takes the user to IdP's login page | |
| Using the IdP's Authorization Endpoint | ||
| IdP does authentication and redirects to FMS with result (yay or nay) and a code | IdP does authentication and redirect to FMS with result (yay or nay) and a code | |
| FMS calls IdP to exchange code for a set of tokens | FMS calls IdP to exchange code for a set of tokens | |
| Using the IdP's Token Endpoint | ||
| IdP returns a set of tokens, including an id_token | IdP returns a set of tokens, including an access token | |
| FMS parses the id_token for the user's unique identifier (typically the email address) and the list of groups (when using groups-based authentication) | ||
| Using the access token, FMS calls IdP again to retrieve additional information about the user | ||
| Using the IdP's Profile Endpoint | ||
| IdP returns JSON with the requested user info | ||
| FMS parses the JSON for the user's unique identifier (typically the email address) and the list of groups (when using groups-based authentication) | ||
Why would you use one or the other?
You normally have very little choice in the matter; it is the Identity Provider that will require you to use either OpenID Connect or the longer OAuth2 flow. Most providers support OpenID Connect, but some do not or have a twist in their requirements that will make it necessary for you to use their OAuth2 flow.
How you configure your FileMaker Server depends on the flow that is needed.
An Example: Oracle Cloud Identity Service
If you are not familiar with the OpenID Connect flow and how FileMaker Server looks for the relevant information, we recommend reading this white paper first.
Oracle ICS supports OpenID Connect, but try as we may, we could not make the OIDC flow return the user’s email attribute nor the user’s groups in the id_token despite both scopes being listed as supported in the Oracle OpenID configuration
Oracle ICS seems to insist on making a call to the userinfo endpoint to retrieve that data.
If you configure your FileMaker Server as below, to use the supported scopes of openid, email, and groups, and with the instructions for FileMaker Server to look in the id_token for the email element and the groups element, authentication will fail.
The id_token returned by Oracle does not contain either the email or the groups element. This is unexpected because most other Identity Providers do when you include those scopes.
When configured for OIDC, FileMaker Server does not make a call to the profile (userinfo) endpoint. To make the authentication work properly then, you need to switch FileMaker Server to the full OAuth2 flow:
With that set, FileMaker Server will make that extra call to the identity provider and retrieve the requested data, including the email address and the list of the groups. The JSON returned by Oracle is in the format shown below: there is a groups element, and each group is represented by a small JSON object with the group’s id, name, and a reference.
The next challenge then becomes: how do you tell FileMaker Server to parse out the names of the groups from this array of JSON objects under the groups element?
In the simpler OIDC flow, groups are added to the id_token as a simple array of strings:
And in this scenario, you tell FileMaker Server to look for the list of group names by simply specifying the element’s name. FileMaker Server knows how to interpret the array as a list of group names:
But in the case of Oracle, the groups are not a simple array of group names; each group is a JSON object. The syntax you use in the FileMaker Server admin console is somewhat unintuitive and uses the greater-than symbol (>) to specify what key within the JSON to extract:
With all of this set correctly, we can test. In the Oracle identity provider, there is a group named FM_test.
And in the FileMaker solution, there is a matching group account.
Then when you log into the FileMaker file by using the Oracle button:
FileMaker will recognize the user and assign it the proper privileges associated with its group account:
How do you find out what to use and how to configure FileMaker Server?
When you try to authenticate using FileMaker Pro, Go, or WebDirect, there is not a lot of useful debugging information available to you. And often, when you set out to configure an Identity Provider, you will not know exactly what the provider sends back and what the various elements are called in the provider’s responses, but you need that info to configure FileMaker Server properly.
Therefore you will want the ability to inspect the id_token that the identity provider sends and see the output of the profile call to know how to tell FileMaker Server how to recognize the groups. There is a detailed walkthrough of the debugging steps in this white paper. In essence, you will use one of these two websites below to mimic the action that initiates the first step, the call from FileMaker Server to the identity provider’s authorize endpoint:
Enter your IdP’s authorized endpoint and your IdP’s client id and specify the scopes you want to have returned.
Remember to configure your IdP with the Redirect URI on the second line as an allowed redirect url. The example below is where to add it for Oracle. Without it, Oracle will refuse to authenticate the user.
After the authentication on the provider’s website, the debugger website will show the token that you will need for the second leg of the trip: calling the identity provider’s token endpoint to exchange that code for a set of tokens.
To make that second call, you will need a tool that can make an HTTP POST request. Postman and Insomnia are great free tools for this.
The instructions on the web page that show you the code explain how to make the call. The result of that call is a set of tokens.
The id_token is the one you need for a simple OIDC call, and you can decode it using online tools like JSON Web Tokens – jwt.io
If you are debugging the full OAuth2 flow, then use the access_token in Postman or Insomnia to make a call to the profile endpoint of the provider and inspect the response sent by the identity provider:
The format of the response will then dictate how you configure FileMaker Server to point to the group names.
In Conclusion
The new ability to use the full OAuth2 flow certainly opens the door to use more Identity Providers to authenticate users into your FileMaker solutions.
The tricky part is always in figuring out what the identity provider returns or not so that you can make the right choices in configuring FileMaker Server.
Soliant has built up a wealth of expertise in the realm of FileMaker authentication, so feel free to call our team when you are looking for information or assistance.
