Authentication is the gateway to every FileMaker solution. For years, the options were straightforward: FileMaker accounts (username and password stored in the file), or external authentication via Active Directory or Open Directory using the legacy Kerberos/LDAP mechanism. Both worked. Both were manageable. Neither required deep understanding of modern identity protocols.

Then the enterprise identity landscape shifted. Organizations moved to cloud identity providers like Okta, Azure Active Directory (now Microsoft Entra ID), Google Workspace, and Auth0. Single Sign-On became an organizational mandate. Multi-factor authentication became a security baseline. The traditional FileMaker authentication options suddenly looked like a gap in the security posture of any solution that needed to integrate with a modern enterprise identity stack.

Claris responded by introducing OAuth 2.0 and OpenID Connect (OIDC) support for FileMaker, available in FileMaker Server and Claris Cloud. In theory, this closes the gap: FileMaker solutions can now participate in the same identity ecosystem as the rest of the organization's applications, with SSO, MFA enforcement through the IdP, and centralized user lifecycle management.

In practice, getting OAuth/OIDC authentication working with a real enterprise identity provider is one of the most technically demanding configuration tasks in the FileMaker platform. It lives at the intersection of FileMaker Server administration, the identity provider's configuration, network infrastructure, and the OAuth/OIDC protocol specifications. When it breaks, the error messages rarely tell you which layer is the problem. And the configuration surface is large: a single misconfigured parameter in any of three or four systems can prevent authentication from working, silently or with a cryptic error.

This post covers how FileMaker's OAuth/OIDC authentication actually works, the configuration requirements on both the FileMaker Server side and the identity provider side, the specific failure modes that make this integration difficult to troubleshoot, and a systematic diagnostic approach for when something goes wrong.

The Identity Protocol Stack: OAuth 2.0 and OIDC

Before configuring anything, it's worth understanding what OAuth 2.0 and OIDC actually are and how they relate to each other. I've found that developers who haven't worked with these protocols often conflate them, and that confusion leads to misconfiguration.

OAuth 2.0 is an authorization framework. Its core purpose is to allow one application to access resources on behalf of a user from another application without sharing the user's credentials. The canonical example is "Allow App A to read your Google Drive files." The user logs into Google, grants App A access, and App A receives a token it can use to access Google Drive.

OAuth 2.0 defines a set of grant types (flows) for different use cases:

  • Authorization Code - the standard web application flow; the user is redirected to the IdP, authenticates, and returns with an authorization code that gets exchanged for tokens
  • Authorization Code with PKCE - the authorization code flow with Proof Key for Code Exchange, designed for public clients (mobile apps, SPAs) that can't securely store a client secret
  • Client Credentials - machine-to-machine authentication; no user involved
  • Implicit - deprecated; don't use it

FileMaker uses the Authorization Code flow for user authentication. The user's browser is redirected to the identity provider, the user authenticates (potentially with MFA), and the IdP redirects back to FileMaker Server with an authorization code that FileMaker exchanges for tokens.

Here's the critical distinction: OAuth 2.0 by itself does not define how to authenticate users. It defines how applications get authorized access to resources. Using OAuth 2.0 for user authentication is technically possible but requires conventions that OAuth 2.0 itself doesn't specify. This is where OIDC comes in.

OpenID Connect (OIDC) is an authentication layer built on top of OAuth 2.0. It adds a standardized identity token (the ID token) and a standardized set of claims (user attributes) to the OAuth 2.0 framework. OIDC defines exactly what a "login with [Provider]" flow looks like, what information is returned about the authenticated user, and how the application can verify the user's identity.

When a user authenticates through OIDC:

  1. The application redirects the user to the IdP with an authorization request that includes the openid scope
  2. The user authenticates at the IdP
  3. The IdP redirects back to the application with an authorization code
  4. The application exchanges the code for tokens, including an ID token (a JWT containing user identity claims) and an access token
  5. The application validates the ID token and extracts user identity from its claims (typically email, sub, name, etc.)

OIDC is what FileMaker actually uses for user authentication when configured with an OAuth/OIDC identity provider. The "OAuth" in FileMaker's configuration UI refers to the underlying OAuth 2.0 authorization framework; the actual identity assertion comes from the OIDC ID token.

There are several key concepts you'll need to understand before diving into configuration:

Client ID and Client Secret: When you register FileMaker Server as an application with an identity provider, the IdP issues a Client ID (a public identifier for your application) and a Client Secret (a private key that proves the application's identity when exchanging codes for tokens). Both are required for the Authorization Code flow.

Redirect URI: The URL that the IdP redirects the user back to after authentication. This must be registered with the IdP exactly as FileMaker Server will send it. A single-character mismatch (trailing slash, HTTP vs. HTTPS, wrong port) causes the authentication to fail with a "redirect_uri_mismatch" error.

Scopes: Permissions the application requests from the IdP. At minimum, the openid scope is required for OIDC. The email and profile scopes are commonly required for FileMaker to receive the user attributes it needs to identify the user.

ID Token: A JSON Web Token (JWT) returned by the IdP that contains claims about the authenticated user. FileMaker uses claims from the ID token to identify the user and map them to a FileMaker account.

Discovery Document (OIDC Well-Known Configuration): Most OIDC providers publish a discovery document at a well-known URL (/.well-known/openid-configuration) that describes all the provider's endpoints, supported scopes, and signing keys. FileMaker can use this document for automatic endpoint discovery. If the discovery document is inaccessible or returns unexpected content, FileMaker can't complete OIDC configuration.

How FileMaker's OAuth/OIDC Authentication Works

Understanding the specific sequence of events in a FileMaker OIDC authentication is essential for diagnosing where failures occur. Let me walk you through it step by step.

Step 1: User opens FileMaker Pro or navigates to a WebDirect URL. The FileMaker client or browser presents the authentication options. If the server is configured with an OAuth/OIDC provider, a button or link for that provider appears alongside (or instead of) the standard username/password login.

Step 2: User clicks the OAuth/OIDC login option. FileMaker constructs an Authorization Request URL and redirects the user's browser to the identity provider. This URL includes the Client ID registered with the IdP, the requested scopes (openid, email, profile), the redirect URI pointing back to FileMaker Server, a state parameter (a random value to prevent CSRF attacks), a nonce (for OIDC, to prevent token replay), and the response_type=code parameter indicating the Authorization Code flow.

Step 3: User authenticates at the identity provider. The user enters their credentials at the IdP's login page. If MFA is enabled at the IdP level, the MFA challenge happens here. FileMaker has no involvement in this step. The IdP handles all authentication logic, including MFA, password policy enforcement, and account lockout.

Step 4: IdP redirects back to FileMaker Server. After successful authentication, the IdP redirects the user's browser to the Redirect URI registered with FileMaker Server, appending an authorization code and the state parameter: 

https://filemaker.company.com/oauth/callback?code=AUTH_CODE&state=RANDOM_STATE

Step 5: FileMaker Server exchanges the authorization code for tokens. FileMaker Server makes a server-to-server POST request to the IdP's token endpoint, sending the authorization code, the Client ID, the Client Secret, and the redirect URI (which must match exactly what was sent in step 2). The IdP validates these parameters and returns an ID token (JWT with user identity claims), an access token (for accessing IdP resources, not typically used by FileMaker), and optionally a refresh token.

Step 6: FileMaker validates the ID token. FileMaker Server validates the ID token by verifying the JWT signature against the IdP's public signing keys, checking that the token's iss (issuer) claim matches the configured IdP, checking that the aud (audience) claim includes the Client ID, verifying the token hasn't expired, and verifying the nonce matches what was sent in step 2.

Step 7: FileMaker extracts user identity and maps to a FileMaker account. FileMaker reads the user identity from the ID token's claims (typically the email claim) and looks for a corresponding FileMaker account or external authentication group. If a match is found, the user is authenticated and the session opens. If no match is found, authentication fails.

Step 8: Session opens. The user's FileMaker session opens with the privilege set associated with their account or external authentication group.

Configuration Requirements: FileMaker Server Side

FileMaker Server's OAuth/OIDC configuration is done through the Admin Console under Security > External Authentication. Here's what you'll need to configure.

Identity Provider Name: A display name for the IdP, shown to users on the login screen. This is cosmetic but should be clear: "Company SSO," "Okta," "Google Workspace," etc.

Client ID: The Client ID issued by the IdP when you registered FileMaker Server as an application. Copy this exactly. It's case-sensitive.

Client Secret: The Client Secret issued by the IdP. This is a sensitive credential. Store it securely. In some IdP configurations, the client secret rotates periodically. A rotated secret that isn't updated in FileMaker Server configuration will silently break authentication.

OIDC Discovery URL (or manual endpoints): The URL for the IdP's OIDC discovery document. FileMaker uses this to automatically discover the authorization endpoint, token endpoint, and JSON Web Key Set (JWKS) URL. For most major IdPs, this URL follows a standard pattern:

  • Azure AD / Entra ID: https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
  • Okta: https://{your-okta-domain}/.well-known/openid-configuration
  • Google Workspace: https://accounts.google.com/.well-known/openid-configuration
  • Auth0: https://{your-domain}.auth0.com/.well-known/openid-configuration
  • Ping Identity: https://{your-domain}/as/.well-known/openid-configuration
  • On-premise ADFS: https://{adfs-host}/adfs/.well-known/openid-configuration

If manual endpoint configuration is required (for providers that don't publish a discovery document, or in environments where the discovery URL is inaccessible), you'll need to configure separately: the authorization endpoint, token endpoint, JWKS URI (for signature verification), and the userinfo endpoint (optional).

Redirect URI: The URL that FileMaker Server registers with the IdP and uses for the callback. FileMaker Server generates this based on its configured hostname. The format is: 

https://[FileMaker-Server-Hostname]/oauth/callback

This must match exactly what you register with the IdP. Common mismatch sources: HTTP vs. HTTPS, trailing slash, custom port, hostname vs. IP address, case differences.

Scope: The scopes to request from the IdP. At minimum: openid email. Additional scopes (profile, groups) may be required depending on what attributes FileMaker needs to identify users and assign privilege sets.

Claim for account name: The ID token claim that FileMaker uses to identify the user and match to a FileMaker account. Typically email for most IdPs. For some configurations, sub (subject), upn (User Principal Name in Active Directory), or a custom claim may be appropriate.

Users authenticating via OAuth/OIDC also need corresponding FileMaker accounts. There are two models to consider.

Individual accounts: Each user has a FileMaker account whose name matches the value of the configured claim (typically their email address). Privilege sets are assigned at the account level. This model gives per-user control but requires manual account creation for each user.

External authentication groups: FileMaker can map IdP group membership to FileMaker privilege sets. Users in a specific IdP group are automatically assigned a corresponding privilege set without needing individual FileMaker accounts. This model requires that the IdP includes group claims in the ID token and that FileMaker is configured to read those claims.

For most enterprise deployments, I've found that external authentication groups are the preferred model. User lifecycle management (adding users, changing roles, disabling access) happens entirely in the IdP, not in FileMaker.

Configuration Requirements: Identity Provider Side

Every identity provider has its own configuration UI and terminology, but the required configuration elements are consistent across providers.

You must register FileMaker Server as an application (sometimes called a "client," "integration," or "app") with the IdP. This registration produces the Client ID and Client Secret and establishes the trusted configuration for your FileMaker Server instance. Registration typically requires:

  • Application type: Web application (not mobile, not SPA)
  • Grant type: Authorization Code
  • Redirect URI: The exact https://[FileMaker-Server-Hostname]/oauth/callback URL
  • Logout URI (optional): For single logout support
  • Application name: A human-readable name shown to users during consent

The IdP must be configured to release the claims FileMaker needs in the ID token. At minimum: openid scope (required for OIDC), the email claim (the most common account identifier), and the email_verified claim (some FileMaker configurations require this).

For group-based privilege set mapping, you'll also need the groups claim or equivalent (the name varies by IdP: "groups," "roles," "memberOf"). The IdP must be configured to include group membership in the ID token, which is often not the default and must be explicitly enabled. Group names or IDs in the claim must match what FileMaker expects.

A common failure point I've seen: the IdP is configured to release the email claim but not the email_verified claim, or the groups claim is configured but the group values in the token are internal IDs (GUIDs) rather than human-readable names that match what's configured in FileMaker.

The redirect URI must be registered exactly as FileMaker Server will send it. IdPs typically enforce strict matching with no wildcards and no trailing slash tolerance. Register: 

https://filemaker.company.com/oauth/callback

And only that. If your FileMaker Server is accessible at multiple hostnames (internal and external DNS names, IP address), register all of them. Each hostname that users might use to access FileMaker needs its own redirect URI registered.

A few notes on token configuration:

  • ID token expiration: The ID token's lifespan affects how long FileMaker's token validation window is. For FileMaker authentication purposes, a short expiration (5-15 minutes) is appropriate. The token is used once for authentication, not for ongoing access.
  • Signing algorithm: FileMaker supports RS256 (RSA + SHA-256) for ID token signing, which is the default for most major IdPs. Some IdPs support HS256 (HMAC + SHA-256) or other algorithms. Verify that your IdP is configured to sign tokens with RS256.
  • Audience claim: The ID token's aud claim should include the Client ID. Most IdPs configure this automatically. Some require explicit configuration.

The Failure Mode Taxonomy

OAuth/OIDC integration with FileMaker fails in ways that don't obviously reveal their cause. Here's a systematic taxonomy of failure modes, organized by where in the authentication flow they occur.

Configuration Discovery Failures

These failures occur before the authentication flow starts, when FileMaker Server attempts to read the IdP's discovery document. You'll see the OAuth/OIDC option not appearing on the login screen, or the Admin Console showing an error when saving the OIDC configuration.

Causes include an incorrect discovery URL (wrong tenant ID, wrong domain), FileMaker Server being unable to reach the discovery URL (network/firewall issue), the discovery URL requiring authentication (unusual but possible in on-premise configurations), the SSL certificate on the IdP not being trusted by FileMaker Server's Java trust store, or the discovery document returning content that FileMaker can't parse.

From the FileMaker Server machine, attempt to fetch the discovery document directly: 

curl -v https://[idp-domain]/.well-known/openid-configuration

If this fails from the server machine, the issue is network connectivity or SSL trust, not FileMaker configuration. If it succeeds, the issue is in how FileMaker is parsing the document or using the configuration.

Authorization Request Failures

These failures occur when FileMaker tries to redirect the user to the IdP. You'll see an error page from the IdP after clicking the OAuth login button, or the browser will stay on the FileMaker login page with an error. Common IdP error messages and what they mean:

  • invalid_client - Client ID is incorrect or the application registration doesn't exist
  • unauthorized_client - The application isn't authorized for the Authorization Code grant type
  • redirect_uri_mismatch - The redirect URI in the request doesn't match what's registered with the IdP
  • invalid_scope - A requested scope isn't configured for this application
  • access_denied - The user cancelled authentication or the IdP policy blocked it

The redirect_uri_mismatch is the most common. Debug it by capturing the exact URL FileMaker sends to the IdP (use browser developer tools, Network tab, look for the redirect to the IdP authorization endpoint), extracting the redirect_uri parameter from that URL (URL-decode it), and comparing it character-by-character with what's registered in the IdP. Common differences: http vs https, presence or absence of trailing slash, port number, uppercase/lowercase hostname.

Token Exchange Failures

These failures occur when FileMaker Server attempts to exchange the authorization code for tokens (step 5 in the flow). This is a server-to-server call. The user's browser isn't involved. You'll know you're in this territory when the IdP redirects back to FileMaker (the URL in the browser changes to the callback URL) but FileMaker then displays an authentication error.

The most common cause is a wrong Client Secret. The secret may have been copied incorrectly, may have expired and been rotated at the IdP, or may have been regenerated after an IdP configuration change. Other causes include the Client Secret containing characters that require URL encoding (+, =, /, &, or %), FileMaker Server being unable to reach the token endpoint (this is a server-to-server call, so the fact that the user's browser can reach the IdP doesn't help), the token endpoint requiring mTLS (which standard FileMaker configuration doesn't support), and clock skew (if the FileMaker Server machine's clock is significantly out of sync with the IdP's clock, token validation fails).

That last one, clock skew, is a surprisingly common cause of intermittent authentication failures.

You can replicate the token exchange request manually using curl from the FileMaker Server machine: 

curl -v -X POST https://[idp-token-endpoint] \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=[authorization_code]" \
  -d "redirect_uri=[exact_redirect_uri]" \
  -d "client_id=[client_id]" \
  -d "client_secret=[client_secret]"

This confirms whether the server can reach the token endpoint and whether the credentials are accepted, independent of FileMaker's request handling.

Token Validation Failures

These failures occur when FileMaker Server receives the tokens but can't validate them. The authentication process appears to complete (callback URL is reached, tokens are returned) but the user isn't logged into FileMaker.

Causes include the signing key not being fetchable (FileMaker validates the ID token signature by fetching the IdP's public keys from the JWKS URI), a signing algorithm mismatch (if the IdP signs tokens with an algorithm FileMaker doesn't support, like ES256 or PS256), an audience mismatch (the ID token's aud claim doesn't include the Client ID), an issuer mismatch (the ID token's iss claim doesn't match what FileMaker expects), token expiration (clock difference between the IdP and FileMaker Server), or a nonce mismatch.

To diagnose, decode the ID token manually. ID tokens are JWTs with base64url-encoded components. The payload can be decoded without the signing key: 

# Extract the payload (middle section of the JWT)
echo "[JWT_PAYLOAD_BASE64]" | base64 -d

Or use an online JWT decoder (jwt.io) in a non-production debugging context. Inspect the iss, aud, exp, email, and other claims. Compare them to FileMaker's expected values.

Account Mapping Failures

These failures occur when the token is valid but FileMaker can't map the authenticated user to a FileMaker account or privilege set. You'll see an "account not found" or "invalid privilege set" error even though authentication completed successfully.

Causes include no FileMaker account matching the claim value (the email claim in the ID token is alice@company.com but the FileMaker account is named alice without the domain, or COMPANY\alice in Windows domain format), external authentication group names not matching (the groups claim contains group GUIDs but FileMaker expects group display names), the configured claim not existing in the token, the email_verified claim being false or absent, or the FileMaker account being marked inactive.

Decode the ID token and verify that the claim FileMaker is configured to use for account matching is present and has the expected value. Then verify that a FileMaker account or external authentication group exists with a name that matches that value exactly. Case sensitivity matters: Alice@Company.com and alice@company.com may not match.

Network and Infrastructure Failures

These aren't specific to OAuth/OIDC configuration. They're infrastructure problems that manifest as authentication failures.

SSL Certificate Trust Issues: FileMaker Server's Java runtime maintains its own trust store for SSL certificates. If the IdP uses a certificate signed by a certificate authority (CA) not in the Java trust store (common with internal enterprise CAs, self-signed certificates, or recently issued certificates from newer CAs), the SSL connections from FileMaker Server to the IdP will fail with certificate verification errors. You'll see intermittent authentication failures, connection timeout errors in FileMaker Server logs. The resolution is to add the IdP's CA certificate to the Java trust store on the FileMaker Server machine using the Java keytool command.

Proxy Server Interception: Enterprise networks often route outbound HTTPS traffic through an SSL-inspecting proxy. The proxy terminates the SSL connection, inspects the content, and re-establishes an SSL connection using the proxy's own certificate. FileMaker Server's Java runtime will reject this substituted certificate unless the proxy's CA is in the Java trust store. This is an extremely common cause of OAuth/OIDC failures in enterprise environments and is often the hardest to diagnose because the failure looks identical to a genuine SSL error. Network teams may not disclose (or be aware) that the proxy performs SSL inspection. On the FileMaker Server machine, use curl with verbose SSL output to test connectivity to the IdP. If the certificate chain includes your proxy's certificate rather than the IdP's real certificate, you've found the problem.

Firewall Rules for Server-to-Server Traffic: The token exchange (step 5 in the flow) is a server-to-server HTTP request from FileMaker Server to the IdP. This traffic originates from the FileMaker Server machine, not from the user's browser. Firewall rules that allow user browsers to reach the IdP may not allow FileMaker Server's machine to do the same. I've seen this scenario more times than I can count: the IdP is hosted in a cloud service (Azure, Okta, Google) and the FileMaker Server is in an on-premise network behind a firewall. User browsers have internet access, but the FileMaker Server machine has restricted outbound internet access. Test outbound connectivity from the FileMaker Server machine specifically, not from a workstation on the same network segment.

Claris Cloud vs. On-Premise: Important Differences

FileMaker's OAuth/OIDC behavior differs between Claris Cloud (hosted by Claris) and on-premise FileMaker Server. These differences are significant for planning and troubleshooting.

Claris Cloud uses Claris ID (Claris's own identity system) as the primary authentication mechanism. Claris ID supports external identity providers through its own OIDC federation, but the configuration path is different from on-premise FileMaker Server. On Claris Cloud, authentication is managed through the Claris Team Manager, not through FileMaker Server's Admin Console. The redirect URI and client registration are managed through Claris's infrastructure, not directly by the customer. And some IdP configurations available on-premise aren't available on Claris Cloud, or require engagement with Claris support.

If you're planning OAuth/OIDC integration on Claris Cloud, verify the specific configuration options available in the current version of Team Manager before designing the integration. Claris Cloud's authentication capabilities have evolved and continue to evolve.

On-premise FileMaker Server gives you direct control over all OAuth/OIDC configuration parameters in the Admin Console. The full configuration flow described in this post applies to on-premise deployments. On-premise deployments are also where SSL certificate trust and network/firewall issues are most common, since you control the network infrastructure and bear responsibility for ensuring FileMaker Server can reach the IdP's endpoints.

Active Directory: OAuth/OIDC vs. Legacy LDAP/Kerberos

Many organizations that use Active Directory for user management are choosing between two integration approaches: the legacy LDAP/Kerberos external authentication and the modern OAuth/OIDC approach via Azure AD (Entra ID).

The legacy approach has been around for many years. FileMaker Server is joined to the Active Directory domain (or configured to talk to a domain controller), users log in with their Windows domain credentials, FileMaker validates credentials against AD via LDAP or Kerberos, and AD security groups can be mapped to FileMaker privilege sets. This approach works reliably for on-premise AD environments with FileMaker Server on the same network as the domain controllers.

But there are good reasons why OAuth/OIDC via Azure AD is often the better choice today:

  • Cloud and hybrid environments: Organizations with Azure AD (cloud or hybrid) may have users whose primary identity is in Azure AD rather than on-premise AD. Legacy LDAP integration doesn't reach Azure AD directly.
  • MFA enforcement: Azure AD's Conditional Access policies enforce MFA centrally. With OIDC, MFA happens at the Azure AD level and applies to FileMaker logins automatically. With legacy LDAP, FileMaker can't participate in Conditional Access policies.
  • SSO consistency: Users get a consistent SSO experience across all applications that use Azure AD, including FileMaker, rather than a separate credential prompt.
  • User lifecycle management: Disabling a user in Azure AD immediately blocks their FileMaker access when using OIDC (the next authentication attempt fails at the IdP). With legacy LDAP, synchronization timing may allow a window where a disabled AD account still has FileMaker access.

In practice, many organizations run both legacy AD authentication and OIDC simultaneously during a migration period. FileMaker Server supports multiple external authentication configurations, allowing existing users to continue using legacy AD credentials while new users are provisioned via OIDC. Plan the migration carefully, particularly the account naming convention, since legacy AD accounts are typically named with DOMAIN\username format while OIDC accounts are typically named with email addresses.

Debugging Workflow: A Systematic Approach

When OAuth/OIDC integration fails and the error message doesn't tell you why, work through this diagnostic sequence rather than randomly changing configuration parameters. I've refined this approach across many deployments, and it consistently points to the right layer.

Layer 1: Verify Network Connectivity from the Server Machine

From the FileMaker Server machine (not a workstation), test: 

# Test discovery document
curl -v https://[idp-discovery-url]

# Test token endpoint (from the discovery document)
curl -v https://[idp-token-endpoint]

# Test JWKS endpoint (from the discovery document)
curl -v https://[idp-jwks-uri]

If any of these fail with SSL errors, certificate trust is the issue. If they fail with connection timeouts, firewall rules are the issue. If they succeed, the network layer is not the problem.

Layer 2: Verify the IdP Application Registration

In the IdP's admin console, confirm: the application exists and is active, the redirect URI is registered exactly as expected, the Client ID and Client Secret are current (not rotated), the required scopes and claims are configured, and the Authorization Code grant type is enabled.

Layer 3: Capture and Inspect the Authorization Request

Using browser developer tools (Network tab), initiate the OAuth login and capture the redirect URL to the IdP. URL-decode the redirect_uri parameter and compare it to what's registered with the IdP. Verify all other parameters (client_id, scope, response_type) are as expected.

Layer 4: Attempt Manual Token Exchange

Using the authorization code from a failed authentication attempt (visible in the browser's URL bar after the IdP redirect), manually replicate the token exchange using curl from the FileMaker Server machine. A successful response confirms the Client ID, Client Secret, and token endpoint are correct. A failure response from the IdP reveals the specific error.

Layer 5: Decode the ID Token

If a token is returned, decode it (jwt.io or manually via base64 decode) and inspect all claims. Verify: iss matches the configured issuer, aud includes the Client ID, email (or the configured claim) is present and has the expected value, exp is in the future relative to the server's current time, and email_verified is true (if required).

Layer 6: Verify Account Mapping

Confirm that a FileMaker account or external authentication group exists with a name that exactly matches the claim value from the token. Check case sensitivity. Check for leading or trailing whitespace. Check for domain-format differences (email vs. username vs. domain\username).

Layer 7: Check FileMaker Server Logs

FileMaker Server logs OAuth/OIDC-related events in the event log. Enable verbose logging if available. Look for specific error messages that correlate with the authentication failure timestamp.

A Practical Configuration Checklist

Identity Provider Setup

  • Application registered with IdP as a web application with Authorization Code grant type
  • Redirect URI registered exactly: https://[filemaker-hostname]/oauth/callback
  • All redirect URIs registered for all hostnames users may use
  • Client ID and Client Secret recorded securely
  • Required scopes configured: openid, email, profile
  • Groups/roles claim configured if using group-based privilege set mapping
  • ID token configured to include required claims
  • Signing algorithm confirmed as RS256

FileMaker Server Setup

  • OIDC Discovery URL verified accessible from FileMaker Server machine
  • Client ID entered exactly as issued by IdP
  • Client Secret entered exactly as issued (watch for special characters)
  • Configured claim for account matching matches what the IdP releases
  • Redirect URI in FileMaker configuration matches registered URI exactly
  • FileMaker accounts or external authentication groups created with names matching expected claim values

Network and SSL

  • FileMaker Server machine can reach IdP authorization endpoint (outbound HTTPS)
  • FileMaker Server machine can reach IdP token endpoint (outbound HTTPS)
  • FileMaker Server machine can reach IdP JWKS endpoint (outbound HTTPS)
  • IdP's CA certificate trusted by FileMaker Server's Java runtime
  • SSL-inspecting proxy CA added to Java trust store if applicable
  • FileMaker Server system clock synchronized (NTP configured, skew under 2 minutes)
  • Firewall rules permit server-to-server traffic from FileMaker Server to IdP

Testing

  • Authentication tested with a known test account before production rollout
  • Account claim value verified in decoded ID token matches FileMaker account name
  • Group claim values verified if using group-based privilege mapping
  • MFA enforcement tested through IdP Conditional Access policies
  • Authentication failure path tested (wrong credentials, disabled account, unauthorized IdP user)
  • Session behavior verified (session duration, re-authentication requirements)
  • Rollback plan confirmed (FileMaker accounts available if OIDC fails)

Wrapping Up

OAuth/OIDC integration with FileMaker is one of the most technically demanding configuration tasks in the platform because it spans three distinct systems: FileMaker Server, the identity provider, and the network infrastructure between them. Each has its own configuration surface, its own error messages, and its own failure modes. When something goes wrong, the error rarely tells you which system is responsible.

The key to getting this right, and to diagnosing it when it breaks, is understanding the authentication flow at the protocol level. The Authorization Code flow has six steps, each of which can fail independently. A systematic diagnostic approach that isolates each step (network connectivity first, then IdP application registration, then authorization request parameters, then token exchange, then token validation, then account mapping) eliminates guesswork and points to the specific layer where the failure is occurring.

The most common failure modes in real deployments aren't exotic protocol edge cases. They're the redirect URI that has a trailing slash on one side and not the other. The client secret that was rotated at the IdP six months ago and never updated in FileMaker. The enterprise proxy that intercepts SSL traffic and presents its own certificate to FileMaker's Java runtime. The groups claim that contains GUIDs instead of display names. The FileMaker Server machine that can't reach the IdP's token endpoint because it sits behind a firewall that nobody thought to update when the identity provider was moved to a cloud service.

Each of these is diagnosable with the right tools and the right sequence of tests. The protocol knowledge and the systematic approach are what separate a two-hour configuration project from a two-week debugging ordeal.