Authentication

OpenTAKServer uses Flask-Security to provide authentication.

Administrator Account

When you start OpenTAKServer for the first time, an administrator account is automatically created. The username is administrator and the password is password. You should immediately change the password when you first log in.

Creating Accounts

By default, only administrators can create user accounts. However, users can register their own accounts if an administrator enables email support.

Note on Passwords

OpenTAKServer prevents @ and : characters in passwords. In certain situations that use basic authentication, such as viewing RTSP streams, having these characters can cause an invalid URL. A typical URL when using basic authentication looks like rtsp://username:password@server_address:8554/path. In these situations, the ':' character separates the username and password, and the @ character separates the username/password from the server address. Having a password with these characters will cause browsers and video players to incorrectly parse the URL.

Token Authentication

OpenTAKServer supports token authentication which can be helpful when interacting with OpenTAKServer via the API. Use the following steps to authenticate with a token:

Add these settings to ~/ots/config.yml if they're not already present. This will remove the CSRF requirements for token auth but still require CSRF for basic and session auth.

SECURITY_CSRF_PROTECT_MECHANISMS:
- session
- basic

If you changed config.yml you must restart OpenTAKServer sudo systemctl restart opentakserver

Next, make an HTTP POST request to /api/login with the include_auth_token query parameter and your credentials as JSON. Here is an example in Python. If your server uses signed certs such as from Let's Encrypt you can remove verify=False.

import requests
response = requests.post("https://<your_server_address>/api/login", params={'include_auth_token': ''}, json={'username': 'your_username', 'password': 'your_password'}, verify=False)

A successful login JSON response will be as follows

{
  "meta": {
    "code": 200
},
  "response": {
    "csrf_token": "xxxxx",
    "user": {
      "authentication_token": "yyyy"
    }
  }
}

The authentication_token must be sent on every subsequent request. It can be in a query parameter called auth_token or in an HTTP header called Authentication-Token

Session Authentication

Making API calls while using session authentication requires a CSRF token. Here is a python example using session authentication. If your server uses signed certs such as from Let's Encrypt you can remove verify=False.

import requests
s = requests.session()
address = "https://<your_server_address>"
r = s.get(f"{address}/api/login", json={}, verify=False)
csrf_token = r.json()['response']['csrf_token']
s.headers['X-XSRF-TOKEN'] = csrf_token
s.headers['Referer'] = address

r = s.post(f"https://{address}/api/login", json={'username': 'administrator', 'password': 'password'}, verify=False)

Whitelisting and Blacklisting Email Domains

If email support is enabled, any valid email address can be used to create an account. However, there are whitelists for email domains and top level domains. Likewise, there are also blacklists. For example, if you add example.com to the OTS_EMAIL_DOMAIN_WHITELIST option, only users with @example.com email addresses can register accounts. You can also add top level domains (TLDs) to the OTS_EMAIL_TLD_WHITELIST option. For example, adding gov and mil will allow only users with .gov or .mil email accounts to register accounts.

OTS_EMAIL_DOMAIN_BLACKLIST and OTS_EMAIL_TLD_BLACKLIST are similar except that any email address not in those lists will be able to register for an account.

Two-Factor Authentication

TOTP

Two-factor authentication can be enabled for any accounts using a TOTP from an authenticator app such as Google Authenticator (Android/iOS) or Microsoft Authenticator (Android/iOS). Click on Setup 2FA in the navigation bar and select the authenticator app option. It will generate a code and a QR code. Either scan the QR code with your authenticator app or copy and paste the code into the authenticator app. Your authenticator app will give you a PIN that you enter below the QR code.

Email

You can choose to use an email address as your 2FA if your administrator has enabled email support. A code will be sent to your email address which you will need to enter when you log in.

Screenshot

SSL Socket Authentication

Connecting to OpenTAKServer's SSL socket requires authentication. In ATAK's server setup, tap Use Authentication and enter your username and password. When ATAK connects, it will send an <auth> CoT with the username and password. If the username and password are incorrect, the account is disabled, or no <auth> CoT is sent, OpenTAKServer will close the connection. Two-Factor authentication is not required for the SSL socket.