The TeamSpeak 3 user management and permission system

=====================================================


Copyright (c) TeamSpeak Systems GmbH




-----------------------------------------------------------
1. TeamSpeak 3 server user management
-----------------------------------------------------------

The mechanism controlling user permissions on a TeamSpeak 3 server is fundamentally different than in TeamSpeak 2.
In TeamSpeak 2 individual users were added to the servers database and permissions bound to a user login name and password.
In TeamSpeak 3 user login names and passwords no longer exist. Instead users connect to a virtual server providing just
a nickname, which is only used for how to display the user to others but in no way related to access control.
To indentify a user on a TeamSpeak 3 virtual server, a public key encryption mechanism is used: When the Client is started
for the first time, it automatically creates a key pair consisting of a public and a private key. The first time a new user
connects to a virtual server, his client will automatically send his public key to the server.

The virtual server creates a unique identifier from this public key and stores this identifier in its database. So
instead of identification with login and password, a TeamSpeak 3 server identifies users by their unique ID.
Should the user delete his private key and create a new one when connecting, he will be treated as a new individual by the server.

Since there is no input needed to �register� on a TeamSpeak 3 server there is no such thing as a manual registration in TeamSpeak 3.
Basically once you connect you are automatically
registered on the server you connected to. When you join again the server will recognize you.


-----------------------------------------------------------
2. TeamSpeak 3 permission overview
-----------------------------------------------------------

All settings that you can apply to a client on the server side are stored in reference to the clients unique ID.
This way, when the client reconnects to the server maybe using a new IP, a new nickname the server can still recoginize it by
the unique ID, and apply these settings. One of the more important settings you can apply to clients is of course to grant or
revoke certain permissions to them.

Clients joining for the first time will automatically become a member of the default Server Permissions Group that is configured
via the server settings � also clients that join a channel they have not visited before will automatically be inserted into the
Default Channel Permission Group (also configured via the server settings). Usually you will be a member of some kind of
administrator group that allows you to configure the server in the way you like it. The default group layout contains a �Server Admin�
group for this purpose.

When a new virtual server is created, the servers global template groups are copied to the virtual servers server default and admin group,
so modifying the templates is a good way to setup a security and access policy for multiple virtual servers without the need to modify
each virtual servers permissions individually, although this can still be done to tweak individual virtual servers if required.


-----------------------------------------------------------
3.The chicken and the egg, or how to use privilege keys
-----------------------------------------------------------

One obvious problem that presents itself is the following: How does the first client receive elevated permissions when there is no
other client with elevated permissions yet that could grant these permissions? The solution for this problem is through permission keys,
that will now be explained:

A permission key is similar to a client with administrator privileges that adds you to a certain permission group, but without the necessity
of a such a client with administrator privileges to actually exist. It is a long (random looking) string that can be used as a ticket into
a specific server group.

As an example I am a server hoster and a client has just purchased a server. I send this client a privilege key that, once it is used
on the clients server, will grant the client that used it administrative powers. Or, in a different use case I might be a server administrator
and I want three of my friends to become members of the clan managment permission group. Since these friends are not currently connected to
my server and I don�t have
them stored in my buddy list I can�t add them
directly into these groups, since I don�t know how to tell the server who they are. So, I generate three privilege keys that each promote
the client that uses it into the server managment group. Then I send these privilege keys to my friends, and they can go ahead and promote
themselves when they are online again.


---------------------------------------------------------------------------------
4. Step by step: Becoming Administrator on your own server using a privilege key
---------------------------------------------------------------------------------

Since you will usually need at least one privilege key to grant administrative privileges after
creating a new virtual server this task is automatically taken care of uppon creation.

Important!
The output would look like the following example:

ServerAdmin privilege key created, please use it to gain
serveradmin rights for your virtualserver. Please also
check the doc/privilegekey_guide.txt for details.

token=gOuRFCa5iM1iC+6GPFaeqiZXJoJrV04+tV0meuE9

Now the server owner would connect using the TeamSpeak 3 client with his still restricted permissions. The client offers a dialog to copy&paste
above privilege key. If the privilege key is correct and has not yet been used, the user will be elevated and gain administrator permissions
by joining the Server Admin permission group.

A privilege key can only be used once, attempting to use it a second time will result in an error. The privilege key is only valid for the
virtual server which it was created for � other virtual servers running within the same server process are not affected.

The usual procedure to create a new virtual server is:
� Create the virtual server
� Copy the privilege key from the server log
� Start the client and connect to the new virtual server,
automatically creating a new unique user ID
� Paste the privilege key into the clients privilege
key dialog


-----------------------------------------------------------
5. Gaining global ServerQuery administrator permissions
-----------------------------------------------------------

In addition to the privilege key mechanism, which grants administrator permissions for individual users on virtual servers, server owners
can gain administrative powers using a global ServerQuery login. In contrary to the user management system using unique IDs, ServerQuery
connections have to provide a login name and password.

When a server process starts for the first time, a password for a global ServerQuery super-admin account is created and printed to the
server console output.

Important!
The output might look like this:

Server Query Admin Acccount created
loginname= �serveradmin�, password= �ifSsSm8w�

Using the provided login name and password, the server administrator can connect to the ServerQuery interface and login using the �login� command.
The ServerQuery admin account password should be protected carefully, as this grants complete control over all virtual servers running within
the server process.