Authentication

Authentication is split into two modules:

• Member Provider - handles authentication and authorization of users, can be used to authenticate users against a database, LDAP, or any other system.
• Session Provider - handles session management, after the module authenticates the user, it creates a session and handles the session lifecycle.

Member Profile

A member profile is a structure that describes the user and what the user is allowed to do in the system.

Field	Description	Type
name	User's name as shown in the UI, must not be unique within the system (not used as an identifier).	string
is_admin	Whether the user can perform administrative tasks that include managing users, sessions, and settings.	boolean
can_login	Whether the user can log in to the system and use the HTTP API.	boolean
can_connect	Whether the user can connect to the room using the WebSocket API (needs can_login to be enabled).	boolean
can_watch	Whether the user can connect to the WebRTC stream and watch the room's audio and video (needs can_connect to be enabled).	boolean
can_host	Whether the user can grab control of the room and control the mouse and keyboard.	boolean
can_share_media	Whether the user can share their webcam and microphone with the room.	boolean
can_access_clipboard	Whether the user can read and write to the room's clipboard.	boolean
sends_inactive_cursor	Whether the user sends the cursor position even when the user is not hosting the room, this is used to show the cursor of the user to other users.	boolean
can_see_inactive_cursors	Whether the user can see the cursor of other users even when they are not hosting the room.	boolean
plugins	A map of plugin names and their configuration, plugins can use this to store user-specific settings, see the Plugins Configuration for more information.	object

YAML

Example member profile in YAML

name: User Name
is_admin: false
can_login: true
can_connect: true
can_watch: true
can_host: true
can_share_media: true
can_access_clipboard: true
sends_inactive_cursor: true
can_see_inactive_cursors: true
plugins:
  <key>: <value>

JSON

Example member profile in JSON

{
  "name": "User Name",
  "is_admin": false,
  "can_login": true, 
  "can_connect": true, 
  "can_watch": true, 
  "can_host": true, 
  "can_share_media": true, 
  "can_access_clipboard": true, 
  "sends_inactive_cursor": true, 
  "can_see_inactive_cursors": true,
  "plugins": {
    "<key>": "<value>"
  }
}

Member Providers

Member providers are responsible for deciding whether given credentials are valid or not. This validation can either be done against a local database or an external system.

Multi-User Provider

This is the default provider that works exactly like the authentication used to work in v2 of neko.

This provider allows you to define two types of users: regular users and admins. Which user is an admin is determined by the password they provide when logging in. If the password is correct, the user is an admin; otherwise, they are a regular user. Based on those profiles, the users are generated on demand when they log in and they are removed when they log out. Their username is prefixed with 5 random characters to avoid conflicts when multiple users share the same username.

Profiles for regular users and admins are optional, if not provided, the default profiles are used (see below in the example configuration).

config.yaml

member:
  provider: multiuser
  multiuser:
    # Password for admins, in plain text.
    admin_password: "adminPassword"
    # Profile fields as described above
    admin_profile:
      ...
    # Password for regular users, in plain text.
    user_password: "userPassword"
    # Profile fields as described above
    user_profile:
      ...

See example configuration

The default profiles for regular users and admins are as follows, highlighting the differences between them.

config.yaml

member:
  provider: multiuser
  multiuser:
    admin_password: "admin"
    admin_profile:
      name: "" # if empty, the login username is used
      is_admin: true
      can_login: true
      can_connect: true
      can_watch: true
      can_host: true
      can_share_media: true
      can_access_clipboard: true
      sends_inactive_cursor: true
      can_see_inactive_cursors: true
    user_password: "neko"
    user_profile:
      name: "" # if empty, the login username is used
      is_admin: false
      can_login: true
      can_connect: true
      can_watch: true
      can_host: true
      can_share_media: true
      can_access_clipboard: true
      sends_inactive_cursor: true
      can_see_inactive_cursors: false

tip

For easier configuration, you can specify only passwords using environment variables:

docker-compose.yaml

environment:
  NEKO_MEMBER_MULTIUSER_USER_PASSWORD: "neko"
  NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: "admin"

File Provider

This provider reads the user's credentials from a file. It is useful for small deployments where you don't want to set up a database or LDAP server and still want to have persistent users.

config.yaml

member:
  provider: file
  file:
    # Absolute path to the file containing the users and their passwords.
    path: /opt/neko/members.json
    # Whether the passwords are hashed using sha256 or not.
    hash: true

It allows you to store the user's credentials in a JSON file. The JSON structure maps user logins to their passwords and profiles.

members.json

{
  "<user_login>": {
    "password": "<user_password>",
    "profile": /* Member Profile, as described above */
  }
}

You can leave the file empty and add users later using the HTTP API.

See example members.json file

We have two users, admin and user with their passwords and profiles. admin is a regular user, while user is an admin.

Please note that the passwords are stored in plain text. To store them securely, set the hash field to true in the configuration. After that, the passwords are expected to be hashed using the bcrypt algorithm.

members.json

{
  "admin": {
    "password": "admin",
    "profile": {
      "name": "Administrator",
      "is_admin": true,
      "can_login": true,
      "can_connect": true,
      "can_watch": true,
      "can_host": true,
      "can_share_media": true,
      "can_access_clipboard": true,
      "sends_inactive_cursor": true,
      "can_see_inactive_cursors": true,
      "plugins": {}
    }
  },
  "user": {
    "password": "neko",
    "profile": {
      "name": "User",
      "is_admin": false,
      "can_login": true,
      "can_connect": true,
      "can_watch": true,
      "can_host": true,
      "can_share_media": true,
      "can_access_clipboard": true,
      "sends_inactive_cursor": true,
      "can_see_inactive_cursors": false,
      "plugins": {}
    }
  }
}

If you want to hash the passwords, you can use the following command to generate a sha256 hash:

echo -n "password" | sha256sum

Object Provider

This provider is the same as the file provider, but it saves the users only in memory. That means that the users are lost when the server is restarted. However, the default users can be set in the configuration file. The difference from the multi-user provider is that the users are not generated on demand and we define exactly which users with their passwords and profiles are allowed to log in. They cannot be logged in twice with the same username.

config.yaml

member:
  provider: object
  object:
  # List of users with their passwords and profiles
  - username: "admin"
    # Password in plain text
    password: "admin"
    # Profile fields as described above
    profile:
      ...

See example configuration

We have two users, admin and user with their passwords and profiles. admin is an admin, while user is a regular user.

config.yaml

member:
  provider: object
  object:
    users:
    - username: "admin"
      password: "admin"
      profile:
        name: "Administrator"
        is_admin: true
        can_login: true
        can_connect: true
        can_watch: true
        can_host: true
        can_share_media: true
        can_access_clipboard: true
        sends_inactive_cursor: true
        can_see_inactive_cursors: true
    - username: "user"
      password: "neko"
      profile:
        name: "User"
        is_admin: false
        can_login: true
        can_connect: true
        can_watch: true
        can_host: true
        can_share_media: true
        can_access_clipboard: true
        sends_inactive_cursor: true
        can_see_inactive_cursors: false

No-Auth Provider

This provider allows any user to log in without any authentication. It is useful for testing and development purposes.

config.yaml

member:
  provider: noauth

danger

Do not use this provider in production environments unless you know exactly what you are doing. It allows anyone to log in and control neko as an admin.

Session Provider

Currently, there are only two providers available for sessions: memory and file.

Simply by specifying the session.file to a file path, the session provider will store the sessions in a file. Otherwise, the sessions are stored in memory and are lost when the server is restarted.

config.yaml

session:
  file: /opt/neko/sessions.json

info

In the future, we plan to add more session providers, such as Redis, PostgreSQL, etc. So the Configuration Options may change.

API User

The API User is a special user that is used to authenticate the HTTP API requests. It cannot connect to the room, but it can perform administrative tasks. The API User does not have a password but only a token that is used to authenticate the requests. If the token is not set, the API User is disabled.

config.yaml

session:
  api_token: "apiToken"

tip

This user is useful in some situations when the rooms are generated by the server and the token is guaranteed to be random every time a short-lived room is run. It is not a good idea to define this token for long-lived rooms, as it can be stolen and used to perform administrative tasks.

You can generate a random token using the following command:

openssl rand -hex 32

Cookies

The authentication between the client and the server can be done using cookies or the Authorization header. The cookies are used by default, but you can disable them by setting the enabled to false.

warning

If you disable the cookies, the token will be sent to the client in the login response and saved in local storage. This is less secure than using cookies, as the token can be stolen using XSS attacks. Therefore, it is recommended to use cookies.

config.yaml

session:
  cookie:
    enabled: true
    name: "NEKO_SESSION"
    expiration: "24h"
    secure: true
    http_only: true
    domain: ""
    path: ""

• enabled - Whether the cookies are enabled or not.
• name - Name of the cookie used to store the session.
• expiration - Expiration time of the cookie, use go duration format (e.g., 24h, 1h30m, 60m).
• secure and http_only - Ensures that the cookie is only sent over HTTPS and cannot be accessed by JavaScript, see MDN Web Docs for more information.
• domain and path - Define where the cookie is valid, see MDN Web Docs for more information.

info

The secure and http_only are set to true by default, which means that the cookie is only sent over HTTPS. If you are using HTTP, you should really consider using HTTPS. Only for testing and development purposes should you consider setting it to false.