Authentication Authentication

Xpra's authentication modules can be useful for:

For more information on the different types of connections, see network. For more generic security information, please see security considerations

SSL mode can also be used for authentication using certificates (see #1252)

When using SSH to connect to a server, encryption and authentication can be skipped: by default the unix domain sockets used by ssh do not use authentication.


Server Syntax

Starting with version 4.0, the preferred way of specifying authentication is within the socket option itself.
ie for starting a seamless server with a TCP socket protected by a password stored in a file:

xpra start --start=xterm -d auth
     --bind-tcp=0.0.0.0:10000,auth=file:filename=password.txt

So that multiple sockets can use different authentication modules, and those modules can more easily be chained:

xpra start --start=xterm -d auth \
     --bind-tcp=0.0.0.0:10000,auth=hosts,auth=file:filename=password.txt \
     --bind-tcp=0.0.0.0:10001,auth=sys

Server Authentication Modules

Xpra supports many authentication modules. Some of these modules require extra dependencies.

| Module | Result | Purpose | |--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| | allow | always allows the user to login, the username used is the one supplied by the client | dangerous / only for testing | | none | always allows the user to login, the username used is the one the server is running as | dangerous / only for testing | | fail | always fails authentication, no password required | useful for testing | | reject | always fails authentication, pretends to ask for a password | useful for testing | | env | matches against an environment variable (XPRA_PASSWORD by default) | alternative to file module | | password | matches against a password given as a module option, ie: auth=password:value=mysecret | alternative to file module | | multifile | matches usernames and passwords against an authentication file | proxy: see password-file below | | file | compares the password against the contents of a password file, see password-file below | simple password authentication | | pam | linux PAM authentication | Linux system authentication | | win32 | win32security authentication | MS Windows system authentication | | sys | system authentication | virtual module which will choose win32 or pam authentication automatically | | sqlite | sqlite database authentication | #1488 | | capability | matches values in the capabilities supplied by the client | #3575 | | peercred | SO_PEERCRED authentication | #1524 | | tcp hosts | TCP Wrapper | #1730 | | exec | Delegates to an external command | #1690 | | kerberos-password | Uses kerberos to authenticate a username + password | #1691 | | kerberos-token | Uses a kerberos ticket to authenticate a client | #1691 | | gss_auth | Uses a GSS ticket to authenticate a client | #1691 | | keycloak | Uses a keycloak token to authenticate a client | #3334 | | ldap | Uses ldap via python-ldap | #1791 | | ldap3 | Uses ldap via python-ldap3 | #1791 | | u2f | Universal 2nd Factor | #1789 |

Beware when mixing environment variables and password files as the latter may contain a trailing newline character whereas the former often do not.

The syntax with older versions used a dedicated switch for each socket type:

For more information on the different socket types, see network examples


Client Syntax

By default, challenge-handlers=all which means that the python client will try all authentication handlers available until one succeeds.
If the server is configured with multiple authentications modules for the same socket, the client will do the same.

Basic examples

Authenticating as username foo with password bar using the URI:

xpra attach tcp://foo:bar@host:port/

For a more secure option, storing the password value in a file, with debugging enabled:

echo -n "foo" > ./password.txt
xpra attach tcp://host:port/ --challenge-handlers=file:filename=./password.txt --debug auth

| Module | Behaviour and options | |-----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| | env | name specifies the environment variable containing the passworddefaults to XPRA_PASSWORD | | file | filename specifies the file containing the passowrd | | gss | use gss-services to specify the name of the security context | | kerberos | kerberos-services specifies the valid kerberos services to connect tothe wildcard * may be used | | prompt | GUI clients should see a dialog, console users a text prompt | | u2f | APP_ID specifies the u2f authentication application ID | | uri | Uses values parsed from the connection string, ie: tcp://foo:bar@host |


Password File

Usernames

The username can be specified:

xpra attach tcp://username:password@host:port/

When an authentication module is used to secure a single session, many modules will completely ignore the username part and it can be omitted from the connection string.

for connecting to the TCP socket and specifying the password only:

xpra attach tcp://:password@host:port/

Since the username is ignored, it can also be replaced with any string of your liking, ie 'foobar':

xpra attach tcp://foobar:password@host:port/

Only the following modules will make use of both the username and password to authenticate against their respective backend: kerberos-password, ldap, ldap3, sys (pam and win32), sqlite, multifile and u2f. In this case, using an invalid username will cause the authentication to fail.

The username is usually more relevant when authenticating against a proxy server (see authentication details there).


Development Documentation

The steps below assume that the client and server have been configured to use authentication:

For more information on packets, see network.