Mikesh 3.0 Syntax

Introduction

Mikesh is a middleware that allows for easy integration of Active Directory (AD) and Microsoft Entra ID with a FileMaker Server.
This software runs an HTTP or HTTPS server which listens to POST requests and receives parameters in JSON format. It can be installed on macOS, Windows and Ubuntu 22.04+ LTS.

Docker compatibility

The linux binaries are fully compatible with Docker.

API Endpoints

The Server exposes the following services through API endpoints:

• Get Version
• Register Product
• Check Registration Status
• Get MSAD Users
• Get Entra ID Users

Configuration file

The Server has a config.toml file, which can specify the ip address, port, timeout, maximum number of cached session ids, ssl certificate and key, maximum size of logs in MB and logging level.

ip = "127.0.0.1"
port = 24034
timeout = 60
maxTokens = 30

[tls]
sslCertificatePath = "path/to/ssl.cert"
sslPrivateKeyPath = "path/to/ssl.key"

[security]
apiKey = "xxxx"

[log]
maxSizeMB = 1000
level = "info"

When apiKey is specified, the server only accepts requests which have the following authorization header:

Authorization: Bearer <your apiKey>

Note that apiKey should only contain ASCII characters. When apiKey is not present, no authorization is required. When sslCertificatePath and sslPrivateKeyPath are not specified, the server does not use any encryption (HTTP). Note that this is generally insecure on public networks. Log levels are “debug”, “info”, “warning” and “error”.

A sample config.toml file is included in the distribution archive and is copied to the installation directory during installation. You can configure the application in two ways:

• Before installation:
  Modify the config.toml file in the installer package. The customized configuration will be applied during installation. Due to Gatekeeper, this method is not available on macOS.

• After installation:
  Edit the config.toml file located in the installation directory. After making changes, you must restart the service for them to take effect. To this end, run:

Session IDs

Each MS AD or Entra ID query returns a session id, which can be used in a future request to get incremental changes. To prevent memory overflow, sessions will expire after a number of queries specified by "maxTokens" in config.toml.

Get Version

• Endpoint: /version
• Method: GET

Description

Get the current version of Mikesh. This is a lightweight endpoint, so it can be used for verifying that the service is running.

Parameters

None.

Response

JSON with error code, error message and version.

Example

Client calls endpoint with no argument. The server returns:

  {
    "error_code": 200,
    "error_message": "No error",
    "version": "3.0.0.0"
  }

Register Product

• Endpoint: /register
• Method: POST

Description

The user has 1 hour by default for demo. After this period, user may provide an email to activate a trial version for another 14 days. A license key is needed to register full version.

Parameters

Accepts a JSON with the following format:

{
  "license": "SNorEmail"
}

Response

Returns a JSON with error code and description.

Example

Client calls endpoint with

{
  "license": "john@example.com"
}

as argument. The server returns

{
    "error_code": 200,
    "error_message": "No error"
}

The product was registered by email and has entered the Trial state.

Check Registration Status

• Endpoint: /register
• Method: GET

Description

Check the current registration status.

Parameters

None.

Response

Returns a JSON with error code, error message, current status, and the maximum number of users (max_users) and groups (max_groups) allowed by the current license. Both limits are returned as strings: either a number string like "1000" or "unlimited". Demo and Trial statuses are limited to 20 users and 5 groups.

Example

Client calls endpoint with no argument. The server returns

{
    "error_code": 200,
    "error_message": "No error",
    "status": "Trial",
    "max_users": "20",
    "max_groups": "5"
}

Get MSAD Users

• Endpoint: /getMSADUsers
• Method: POST

Description

Query user data from Microsoft Active Directory. The returned attributes can be mapped to custom output fields. Results can be returned in two ways:

1. As files written to disk in specified location
2. Directly in the response JSON using base64 encoding (to ensure safe transmission of data with quotes and whitespaces)

The output consists of two files or two JSON fields respectively: table of users currently present in Microsoft AD and a list of UUIDs for users that were removed since the last successful query. The users table will list UUID, status (new or updated) and values defined with “attributes” in a TSV (tab-separated values) format.

The connector maintains an internal state of the last successful synchronization. During the next query, only users that were created or modified since the last synchronization are returned with status new or updated. Deleted users are reported separately using their UUID.

Parameters

Parameters are inserted as a JSON with fields:

Note

Mikesh takes into account indirect group memberships. For instance, a member of “FileMaker Team”, which is a subgroup of “Developers”, will also count as a member of “Developers”.

Response

The output depends on response_method specified.

1. When exporting to a file, the output is a JSON object containing error code and error message. The server will generate current_users.txt and removed_users.txt files in the specified location.
2. In case of base64 output method, server will instead place the base64-encoded data into response JSON under “current_users” and “removed_users” fields.

Current users and deleted users are reported separately to simplify parsing in FileMaker. Moreover, in MS AD, attributes cannot be queried for deleted objects.

Example 1

Client calls the endpoint with parameter

{
    "domain": "example.com",
    "username": "johndoe",
    "password": "password1234",
    "session_id": "1775654044752729100",
    "groups" : [
        "Group1",
        "Group2"
    ],
    "attributes": {
      "created" : "whenCreated",
      "modified" : "whenChanged",
      "first_name" : "givenName",
      "email_address" : "mail"
    },
    "response_method": "file",
    "response_path": "/opt/FileMaker/FileMaker Server/Data/Documents/"
}

The server returns

{
    "error_code": 200,
    "error_message": "No error",
    "session_id": "1775655880649388300"
}

and exports a file current_users.txt which contains (as tab-separated values):

and removed_users.txt which contains:

12345678-1234-1234-1234-1234567890AD
12345678-1234-1234-1234-1234567890AF

to /opt/FileMaker/FileMaker Server/Data/Documents/. Here, current_users.txt and removed_users.txt list all changes since the request that returned a session id "1775654044752729100".

Example 2

Assuming that the session id is valid, the following set of parameters:

{
    "url": "ldap://10.0.1.192:389",
    "domain": "example.com",
    "username": "john doe",
    "password": "password1234",
    "session_id": "1775655880649388300",
    "groups" : [
        "Group1",
        "Group2"
    ],
    "attributes": {
        "created" : "whenCreated",
        "modified" : "whenChanged",
        "first_name" : "givenName",
        "last_name" : "sn",
        "email_address" : "mail"
    },
    "response_method": "base64"
}

will return an output such as

{
    "error_code": 200,
    "error_message": "No error",
    "session_id": "1775655880649388300",
    "current_users": "dXVpZAlzdGF0dXMJY3JlYXRlZAltb2RpZmllZA...",
    "removed_users": "zNGREVCCW5ldwkyMS4wNy4yMDIwIDA5OjQ4OjUx..."
}

Get Entra ID Users

• Endpoint: /getEntraIDUsers
• Method: POST

Description

Query user data from Microsoft Entra ID. The endpoint retrieves user accounts using Microsoft Graph API. The returned attributes can be mapped to custom output fields. Results can be returned in two ways:

1. As files written to disk in specified location
2. Directly in the response JSON using base64 encoding

The output consists of two files or two JSON fields respectively: table of users currently present in Entra ID and a list of UUIDs for users that were removed since the last successful query. The users table will list UUID, status and values defined with “attributes” in a TSV format.

Parameters

Parameters are inserted in JSON format.

Response

The output depends on response_method specified.

1. When exporting to a file, the output is a JSON object containing error code and error message. The server will generate current_users.txt and removed_users.txt files in specified location.
2. In case of base64 output method, server will instead place the base64-encoded data into response JSON under “current_users” and “removed_users” fields.

Example

The client calls:

{
    "tenant_id": "example.onmicrosoft.com",
    "client_id": "john doe",
    "client_secret": "password1234",
  "session_id": "1775654044752729100",
    "groups" : [
        "Group1",
        "Group2"
    ],
    "attributes": {
        "uuid" : "id",
        "created" : "createdDateTime",
        "modified" : "modifiedDateTime",
        "first_name" : "givenName",
        "last_name" : "surname",
        "display_name" : "displayName",
        "telephone_number" : "telephoneNumber",
        "email_address" : "mail"
    },
    "response_method": "base64"
}

Will return output such as:

{
    "error_code": 200,
    "error_message": "No error",
    "session_id": "1775654483604030900",
    "current_users": "dXVpZAlzdGF0dXMJY3JlYXRlZAltb2RpZmllZA...",
    "removed_users": "zNGREVCCW5ldwkyMS4wNy4yMDIwIDA5OjQ4OjUx..."
}

You can use native FileMaker function Base64Decode ( text ) to decode the result.

Error Codes