[X2Go-Commits] page added: wiki:advanced:x2gobroker:howitworks

wiki-admin at x2go.org wiki-admin at x2go.org
Wed Mar 27 18:18:45 CET 2013


A page in your DokuWiki was added or changed. Here are the details:

Date        : 2013/03/27 17:18
Browser     : Mozilla/5.0 (X11; Linux x86_64; rv:18.0) Gecko/20100101 Firefox/18.0 Iceweasel/18.0.1
IP-Address  : 213.178.75.58,10.0.32.50
Hostname    : nocatv2.tng.de,10.0.32.50
Old Revision: ---
New Revision: http://wiki.x2go.org/doku.php/wiki:advanced:x2gobroker:howitworks
Edit Summary: created
User        : sunweaver

====== How does X2Go Session Broker Work ======

===== Authentication =====

The X2Go client can use different methods of authentication.

With an HTTP(S) broker it could be //username and password//. With an SSH broker a //SSH key authentication// can also be used.

===== Extra Security: Pre-shared Authentication ID =====

With both types of broker (HTTP, SSH) you can use an additional parameter "authid" for verifying the trust state of an authenticating user. The authentication ID is a user defined string (like a pre-shared key) which is stored in file on the
client-side. 
\n
The file path to the authentication ID has to be specified as the X2Go Client command line option ''<nowiki>--auth-id</nowiki>''.

===== Don't Check User Data =====

In some setups it can make sense to give access to the X2Go Session Broker without authentication. An example can be a broker on your internal LAN where the broker only serves as a load balancer for two or more X2Go Servers (multi-node setup).

When implementing your own session broker, you can configure the broker not to check the username (and password) at all. This is only possible with HTTP based brokers.

With SSH based X2Go Session Broker implementations, you can also ignore the username, but it is not possible to access the broker without some sort of login method. 

===== Granting Access to the Broker =====

Whatever mechanism is used for authentication, the first line printed to STDOUT (or returned via CGI script) has to be: ''Access granted''.

This is to let X2Go Client know, that
authentication has been successful.


===== List of predefined X2Go session profiles =====

After successful authentication against the X2Go Session Broker, X2Go Client will request a list of predefined X2Go session profiles. This session profile list looks pretty much the same as the sessions file of X2Go Client. Check ''[[wiki:development:sessions-file|~/.x2goclient/sessions]] '' (under GNU/Linux) for reference.

==== Generic function: listSessions ====

A generic function, that sends X2Go session profiles to X2Go Client can look like this:

<code perl>
sub listSessions
{
  print "START_USER_SESSIONS\n
\n
[  <session 1>  ]\n
option1=value1\n
....
optionN=valueN\n

[  <session 2>  ]\n
option1=value1\n
....
optionN=valueN\n
\n
END_USER_SESSIONS\n";
}
</code>

==== Sesssion Profile Format ====

The option keys and values are the same as in X2Go Client's configuration file (''~/.x2goclient/sessions'').

The only difference occurs in the parameters ''host=<hostname>'' and
''key=<keyfile>''. 

Furthermore, there are two parameters that are not supported in the ''sessions'' file, but are only functional when X2Go Client is in broker mode: ''status=<status>'' and ''usebrokerpass={true,false}''.

=== The session profile option: host ===

The ''host='' parameter is not necessarily a hostname of an X2Go Server. The actual address of the server will be provided after the session profile has been selected by the user. Delaying the provision of the X2Go Server name makes sense in a cases where X2Go Session Broker is used as a [[wiki:advanced:x2gobroker:loadbalancing|load balancer]].

In load balancing setups, the best server will be
chosen after selection of a session profile. Once the best server has been detected, it is sent to X2Go Client and X2Go Client use the best server's hostname for authentication and session startup. When resuming an X2Go session, the broker will know the server that runs the suspended session and return that one, so that the user
can continue his/her earlier session.

=== The session profile option: key ===

The ''key='' parameter is simply ignored when returned via an X2Go Session Broker.

A valid SSH key (X2Go Client authenticates against X2Go Servers using SSH) can be provided to X2Go Client directly after the selection of a session profile. 

However, you can set this parameter with some value to inform the Client, that passwordless authentication should be
tried, for example: ''key=will-be-provided-later''.

=== The session profile option: usebrokerpass ===

The parameter ''usebrokerpass={true,false}'' is used to denote that requesting the user password for this session is not necessary, but that the X2Go Client should rather use the broker password instead. 

This can be useful if the X2Go Session Broker and the X2Go Server use the same authentication server (e.g. same LDAP db) and there is no need to ask the same password twice. 

It is not recommended to use such authentication with an HTTP Broker
without SSL encryption.

=== The session profile option: status ===

The parameter ''status={S,R}'' can be one of two values "S" or "R". It can be used to tell X2Go Client that an instance (or instances) of this session profile are already running or are suspended on the server. 

X2Go Client will display the status on the session profile card.

===== Selecting a Session Profile =====

After login to the X2Go Session Broker a list of provided session profiles is shown in X2Go Client. The user can now choose one session profile from this list. The ID of chosen session profile will be sent to the broker and the broker sends the connection data back to X2Go Client. 


==== Generic function: listSessions ====

This is a generic example for the "selectSession" function in a Perl based X2Go Session Broker:

<code perl>
sub selectSession
{
  my ($user, $sid)=@_;
  if($sid eq "123456789")
  {
      print "SERVER:x2goserver.org:22\n";
  }
}
</code>

This function sends a server address and an
SSH port for the X2Go server connection back to X2Go Client.

==== Starting vs. Resuming X2Go Sessions ====

If no other data is specified, a new X2Go session will be created.

The X2Go Session Broker can also send information back to client, that tells the client to resume a suspend session.

In this case the X2Go Session Broker should also send a session information to X2Go Client (one of those lines as returned by the X2Go Server command x2golistsessions):
<code perl>
sub selectSession
{
  my ($user, $sid)=@_;
  if($sid eq "123456789")
  {
      print "SERVER:phoca:22\n";
      print
"SESSION_INFO:12542|ncryer-53-1348753256_stDstartxfce4_dp24|53|debian|S|2012-09-27T06:40:57|7db77095d8a782f479d509d96f2e3261|188.195.168.12|30004|30005|2012-09-27T06:41:28|ncryer|285|30006|\n";
}
</code>

The X2Go Session Broker can get this data from the X2Go session database or by executing 
<code bash>
x2golistsessions
</code>

under the requesting user ID on the X2Go Server.

==== No Auto-Resuming
of Sessions ====

If X2Go Client is running in broker mode, it will not verify if there are existing sessions on X2Go Server. 

It is the responsibility of the X2Go Session Broker. The X2Go Broker should also suspend sessions before providing session data to client if a session is still/already running.

==== Providing Auto-Login via SSH Keys ====

The broker can also provide a SSH Key to client (the key in the below example has been obfuscated):

<code perl>
sub selectSession
{
  my ($user, $sid)=@_;
  if($sid eq "123456789")
  {
      print "SERVER:phoca:22\n";
      print "-----BEGIN DSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info:
AES-128-CBC,XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
yX7XLwCszCLM1FCYpdIGmM98vuHVcpNlVUBVgNcTxE1XCCnPZPjUXiNnUZPk1lme
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
o1q7Q1YmH43qI18lifjUhGZUTYWKQSsj2Am9bnjqaveV2aMEWymC8J9aJOYLpVZG
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
G1DwWnSRgyJaxRm4Ik0/kh78ioUfkVerXaCf2OKCMyiZBWcsNfvQwDa9MBrZ4rYW
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
VR60OGB7dHy+7ozqkjzuX+uB04GIqPJwG797i26Bo4v7uhbALjMa5qsObqXIPM1S
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXX==
-----END DSA PRIVATE KEY-----";
 }
}
</code>

Providing SSH Keys can be increase usability of X2Go in several cases.

It is highly recommended to transfer SSH keys only over encrypted channels (HTTPS or SSH broker). 

It is also recommended to transfer only temporary keys, which should be removed from ''authorized_keys'' directly after successful
authentication to X2Go server.




-- 
This mail was generated by DokuWiki at
http://wiki.x2go.org/




More information about the x2go-commits mailing list