Authentication

FreeTAKServer implements multiple authentication mechanisms depending on the API service being accessed. This page covers authentication requirements and implementation details for all API types.

Authentication Methods

FreeTAKServer uses different authentication methods for different services:

Service	Authentication Method	Port
REST API	Bearer Token (Flask-HTTPAuth)	19023
HTTPS TAK API	Mutual TLS (Client Certificates)	8443
HTTP TAK API	Optional/None	8080
SSL CoT Service	Client Certificates	8089
TCP CoT Service	None	8087

REST API Authentication

The REST API service uses Bearer Token authentication implemented with Flask-HTTPAuth.

Implementation

The authentication is implemented in FreeTAKServer/services/rest_api_service/controllers/authentication.py:

from flask_httpauth import HTTPTokenAuth
from flask import request
import datetime as dt

auth = HTTPTokenAuth(scheme='Bearer')

@auth.verify_token
def verify_token(token):
    from .persistency import dbController
    if token:
        # Check API user table
        output = dbController.query_APIUser(query=f'token = "{token}"')
        if output:
            return output[0].Username
        else:
            # Check system user table
            output = dbController.query_systemUser(query=f'token = "{token}"')
            if output:
                output = output[0]
                # Log API call for system users
                dbController.create_APICall(
                    user_id=output.uid, 
                    timestamp=dt.datetime.now(), 
                    content=request.data,
                    endpoint=request.base_url
                )
                return output.name
    return None

Token Verification Process

Extract Token: The @auth.login_required decorator extracts the Bearer token from the Authorization header
Query APIUser Table: First checks if the token exists in the APIUser table
Query SystemUser Table: If not found in APIUser, checks the SystemUser table
Log Request: For system users, logs the API call with timestamp, content, and endpoint
Return Identity: Returns the username if valid, None if invalid

Using Bearer Token Authentication

Making Authenticated Requests

Include the Bearer token in the Authorization header:

curl -X GET \
  http://localhost:19023/ManageSystemUser/getAll \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE'

Using Python requests:

import requests

url = "http://localhost:19023/ManageSystemUser/getAll"
headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE"
}

response = requests.get(url, headers=headers)
print(response.json())

Using JavaScript fetch:

fetch('http://localhost:19023/ManageSystemUser/getAll', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Protected Endpoints

All REST API endpoints except /Alive require authentication. Endpoints are decorated with @auth.login_required:

@app.route('/ManageSystemUser/getAll', methods=["GET"])
@auth.login_required
def getSystemUsersRest():
    # Endpoint logic here
    pass

The /Alive health check endpoint does not require authentication and can be used to verify server availability without credentials.

TAK API Authentication

HTTPS TAK API (Port 8443)

The HTTPS TAK API service uses mutual TLS authentication requiring client certificates.

Certificate Requirements

Server Certificate: Server must have a valid SSL certificate signed by the CA
Client Certificate: Each client must present a valid certificate signed by the same CA
CA Certificate: Both server and client must trust the Certificate Authority

The service is configured to require client certificates:

wsgi.server(
    sock=wrap_ssl(
        listen((IP, HTTPPORT)), 
        keyfile=config.unencryptedKey,
        certfile=config.pemDir,
        server_side=True, 
        ca_certs=config.CA, 
        cert_reqs=ssl.CERT_REQUIRED  # Require client certificate
    ), 
    site=app
)

Certificate Paths

Default certificate locations (configurable via MainConfig):

Server Key: /opt/fts/certs/server.key.unencrypted
Server Certificate: /opt/fts/certs/server.pem
CA Certificate: /opt/fts/certs/ca.pem
CA Key: /opt/fts/certs/ca.key

HTTP TAK API (Port 8080)

The HTTP TAK API service does not require authentication and is intended for development/testing only.

The HTTP TAK API on port 8080 should never be exposed in production environments. It does not enforce any authentication and all endpoints are publicly accessible.

System User Management

Creating Users with Tokens

System users can be created with authentication tokens through the REST API:

# Example: Create system user with token
url = "http://localhost:19023/ManageSystemUser/postSystemUser"
headers = {
    "Authorization": "Bearer ADMIN_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "systemUsers": [
        {
            "Name": "user1",
            "Group": "team1",
            "Token": "user1_secret_token",
            "Password": "user1_password",
            "DeviceType": "mobile",
            "Certs": "false"
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)

Creating Users with Certificates

When creating users with certificates enabled, FreeTAKServer automatically generates client certificates:

payload = {
    "systemUsers": [
        {
            "Name": "user1",
            "Group": "team1",
            "Token": "user1_secret_token",
            "Password": "user1_password",
            "DeviceType": "wintak",  # or "mobile"
            "Certs": "true"  # Enable certificate generation
        }
    ]
}

The server will:

Generate a client certificate using AtakOfTheCerts().bake(common_name=cert_name)
Create a certificate package (.p12 file)
Generate a platform-specific ZIP package (WinTAK or mobile ATAK)
Store the package as a data package for download
Optionally send a CoT message to the client with download information

Certificate generation uses the FreeTAKServer.core.util.certificate_generation module and creates packages compatible with ATAK, WinTAK, and iTAK clients.

User Types

FreeTAKServer supports two types of authenticated users:

API Users

Stored in the APIUser database table, these users are specifically for API access. Fields:

Username: User identifier
token: Bearer token for authentication

System Users

Stored in the SystemUser database table, these users represent TAK clients and can access both API and CoT services. Fields:

name: User/callsign
group: User group/team
token: Bearer token for API authentication
password: Password (may be used for alternative auth)
uid: Unique user identifier
certificate_package_name: Name of associated certificate package
device_type: Device type (“mobile”, “wintak”, etc.)

API Call Logging

When system users authenticate to the REST API, all API calls are logged:

dbController.create_APICall(
    user_id=output.uid,           # System user UID
    timestamp=dt.datetime.now(),  # Request timestamp
    content=request.data,          # Request body
    endpoint=request.base_url      # Endpoint URL
)

This provides an audit trail of all API operations performed by system users.

WebSocket Authentication

The REST API service provides WebSocket endpoints for real-time updates. WebSocket connections require separate authentication:

// Connect to WebSocket
const socket = io('http://localhost:19023');

// Authenticate
socket.emit('authenticate', JSON.stringify({
    "Authenticate": "YourWebsocketKey"  // From MainConfig.websocketkey
}));

// Listen for authentication response
socket.on('authentication', (data) => {
    const response = JSON.parse(data);
    if (response.successful === 'True') {
        console.log('WebSocket authenticated');
        // Now can use other events: users, logs, serviceInfo, etc.
    }
});

WebSocket authentication uses a separate key configured in MainConfig.websocketkey, not user Bearer tokens. The default value is “YourWebsocketKey” and should be changed in production.

Security Best Practices

Token Management

Generate Strong Tokens: Use cryptographically secure random tokens
```
import secrets
token = secrets.token_urlsafe(32)
```
Store Securely: Never commit tokens to version control

Rotate Regularly: Update tokens periodically using the update endpoint

curl -X PUT http://localhost:19023/ManageSystemUser/putSystemUser \
  -H 'Authorization: Bearer ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "systemUsers": [{
      "uid": "user-uid-here",
      "Token": "new-token-value"
    }]
  }'

Use HTTPS: Always use HTTPS in production to prevent token interception

Certificate Management

Protect CA Key: The CA private key should be stored securely with restricted permissions
Certificate Expiration: Monitor and renew certificates before expiration

Revocation: Use the Certificate Revocation List (CRL) to revoke compromised certificates

from FreeTAKServer.core.util.certificate_generation import revoke_certificate
revoke_certificate(username=username)

Client Certificate Distribution: Use secure channels to distribute client certificates

Configuration Security

Change Default Keys: Update SecretKey and websocketkey in MainConfig

Environment Variables: Use environment variables for sensitive configuration:

export FTS_SECRET_KEY="your-secret-key"
export FTS_NODE_ID="your-node-id"

Restrict API Access: Use firewall rules to limit REST API access to authorized networks
Disable HTTP TAK API: In production, disable or firewall the HTTP TAK API service (port 8080)

Troubleshooting Authentication

401 Unauthorized Errors

Symptom: REST API returns 401 Unauthorized Possible Causes:

Missing or invalid Bearer token
Token not in database
Incorrect header format (should be Authorization: Bearer TOKEN)

Solution:

# Verify token format
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:19023/ManageSystemUser/getAll

# Check if token exists in database
# Query SystemUser or APIUser tables

Certificate Authentication Failures

Symptom: HTTPS TAK API refuses connection or returns SSL errors Possible Causes:

Client certificate not signed by trusted CA
Certificate expired
Certificate revoked
Incorrect certificate format

Solution:

# Verify certificate with OpenSSL
openssl verify -CAfile /opt/fts/certs/ca.pem client.pem

# Check certificate expiration
openssl x509 -in client.pem -noout -dates

# Test connection
curl --cert client.pem --key client.key --cacert ca.pem \
  https://localhost:8443/Marti/api/version

WebSocket Authentication Fails

Symptom: WebSocket events return no data or connection rejected Solution:

Verify websocketkey in MainConfig matches authentication key
Ensure authentication event is sent before other events
Check that session.authenticated is set to True

Next Steps

REST API Reference - Explore available REST API endpoints
Security Configuration - Learn about managing users and certificates
Configuration - Configure authentication settings

Overview

REST API

TAK API

CoT Services

Authentication Methods

REST API Authentication

Implementation

Token Verification Process

Using Bearer Token Authentication

Making Authenticated Requests

Protected Endpoints

TAK API Authentication

HTTPS TAK API (Port 8443)

Certificate Requirements

Certificate Paths

HTTP TAK API (Port 8080)

System User Management

Creating Users with Tokens

Creating Users with Certificates

User Types

API Users

System Users

API Call Logging

WebSocket Authentication

Security Best Practices

Token Management

Certificate Management

Configuration Security

Troubleshooting Authentication

401 Unauthorized Errors

Certificate Authentication Failures

WebSocket Authentication Fails

Next Steps

Build docs developers (and LLMs) love

Overview

REST API

TAK API

CoT Services

​Authentication Methods

​REST API Authentication

​Implementation

​Token Verification Process

​Using Bearer Token Authentication

​Making Authenticated Requests

​Protected Endpoints

​TAK API Authentication

​HTTPS TAK API (Port 8443)

​Certificate Requirements

​Certificate Paths

​HTTP TAK API (Port 8080)

​System User Management

​Creating Users with Tokens

​Creating Users with Certificates

​User Types

​API Users

​System Users

​API Call Logging

​WebSocket Authentication

​Security Best Practices

​Token Management

​Certificate Management

​Configuration Security

​Troubleshooting Authentication

​401 Unauthorized Errors

​Certificate Authentication Failures

​WebSocket Authentication Fails

​Next Steps

Build docs developers (and LLMs) love

Authentication Methods

REST API Authentication

Implementation

Token Verification Process

Using Bearer Token Authentication

Making Authenticated Requests

Protected Endpoints

TAK API Authentication

HTTPS TAK API (Port 8443)

Certificate Requirements

Certificate Paths

HTTP TAK API (Port 8080)

System User Management

Creating Users with Tokens

Creating Users with Certificates

User Types

API Users

System Users

API Call Logging

WebSocket Authentication

Security Best Practices

Token Management

Certificate Management

Configuration Security

Troubleshooting Authentication

401 Unauthorized Errors

Certificate Authentication Failures

WebSocket Authentication Fails

Next Steps