Authentication Authentication

Xpra’s authentication modules can be useful for: * securing socket connections * making the unix domain socket accessible to other users safely * using the proxy server

For more information on the different types of connections, see network

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.


Authentication Modules

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

Here is the full list:

list of modules

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
peercred SO_PEERCRED authentication
tcp hosts TCP Wrapper #1730
exec Delegates to an external command #1690
kerberos-password Uses kerberos to authenticate a username + password #1691
kerberos-ticket Uses a kerberos ticket to authenticate a client #1691
gss_auth Uses a GSS ticket to authenticate a client #1691
ldap Uses ldap via python-ldap #1791
ldap3 Uses ldap via python-ldap3 #1791
u2f Universal 2nd Factor #1789

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 
     --bind-tcp=0.0.0.0:10001,auth=sys

more examples

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

syntax for older versions

The syntax with older versions used a dedicated switch for each socket type: * --auth=MODULE for unix domain sockets and named pipes * --tcp-auth=MODULE for TCP sockets * --vsock-auth=MODULE for vsock (#983) etc

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

Password File

Usernames

The username can be specified: * in the connection files you can save from the launcher * in the client connection string

tcp example

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.

example: specifying the password only

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

Authentication Process

The steps below assume that the client and server have been configured to use authentication: * if the server is not configured for authentication, the client connection should be accepted and a warning will be printed * if the client is not configured for authentication, a password dialog may show up, and the connection will fail with an authentication error if the correct value is not supplied * if multiple authentication modules are specified, the client may bring up multiple authentication dialogs * how the client handles the challenges sent by the server can be configured using the challenge-handlers option, by default the client will try the following handlers in the specified order: uri (whatever password may have been specified in the connection string), file (if the password-file option was used), env (if the environment variable is present), kerberos, gss, u2f and finally prompt

module and platform specific notes

For more information on packets, see network.

Salt handling is important