3.2. Connecting to a Server¶
There are several ways to connect your client to a running xGT server:
The default port number is 4367. The xGT server listens on that port with a default hostname of “localhost”. Throughout this page, we assume the server platform has a DNS name of “my.example.com”.
3.2.1. Use SSH Tunneling¶
This strategy requires the user to have an SSH login account on the server platform running the xGT server process. To use this strategy, one must first establish an SSH connection, with tunneling, from their client laptop/desktop to the server platform:
$ ssh -L 4367:localhost:4367 my.example.com
-L option says to map local port 4367 to the socket
localhost:4367 on the server platform.
Now, all that a Python script needs to do is the same as if it were connecting to an xGT server running on its local platform:
import xgt server = xgt.Connection(host='localhost')
3.2.2. Connect Via SSL-encrypted Network Connection¶
In order to run a secure xGT server, it is necessary to configure the server in this way:
"system.usessl" : True, "system.ssl_root_dir" : "/path/to/certs/root"
/path/to/certs/root should point to the root directory where this directory subtree exists:
. ├── certs │ ├── ca-chain.cert.pem │ └── server.cert.pem └── private └── server.key.pem
To connect to an xGT server using SSL, the client needs to pass the following flags to
ssl flag needs to be set to true.
ssl_root_dir flag should be set to the root directory containing the SSL certificates and private keys.
ssl_server_cn flag should be set to the common name for the server listed on the server side SSL certificate.
The xGT client expects the following directory structure for SSL certificates and private keys:
. ├── certs │ ├── ca-chain.cert.pem │ └── client.cert.pem └── private └── client.key.pem
Here is a sample Python script showing connecting to a server via an SSL-encrypted network:
import xgt server = xgt.Connection(ssl = True, ssl_root_dir = "/path/to/client/certs/root/", ssl_server_cn = "my.xGT.cn")
3.2.3. Connecting to an Open Port¶
This method is insecure without enabling SSL support. It is not recommended.
To use this connection strategy, the server must be configured with the DNS name of the server system as hostname. For example:
"system.hostname" : "my.example.com"
To connect to this server from anywhere on the internet, a Python script can do:
import xgt server = xgt.Connection(host = 'my.example.com')
3.2.4. User Authentication¶
xGT supports using authentication to limit access to the server. The three available authentication types are no authentication, username / password authentication, and Kerberos authentication. The authentication type will be setup by the system administrator.
A user autheticates by passing an authentication class when constructing a
Connection object using the keyword argument
The xGT client supports three authentication classes:
NoAuth: Indicates that no authentication is needed. Default.
BasicAuth: Basic username / password authentication information.
KerberosAuth: Kerberos ticket-based single-sign on authentication.
126.96.36.199. No Authentication¶
To create a connection using the Python client when the server is setup to not require authentication, the user doesn’t need to pass anything to the
auth keyword argument as no authentication is the default:
conn = xgt.Connection()
188.8.131.52. User Password Authentication¶
To create a connection when the server is using username / password authentication, the user must pass a
BasicAuth object to the
auth keyword argument, providing a username and password:
conn = xgt.Connection(auth = xgt.BasicAuth("user01", "password01"))
When using a script or notebook, the Python getpass module can be used to securely authenticate a user’s password, prompting for a password input when run:
import getpass conn = xgt.Connection(auth = xgt.BasicAuth("user01", getpass.getpass()))
If authenticating into xGT with the client’s currently logged in UNIX user or LDAP user, the module may also be used to retrieve the username:
import getpass conn = xgt.Connection(auth = xgt.BasicAuth(getpass.getuser(), getpass.getpass()))
184.108.40.206. Kerberos Authentication¶
To connect to an xGT server using Kerberos-based single-sign-on capabilities, the user must have already authenticated to the third-party Kerberos Key Distribution Center (KDC) using a utility such as kinit.
To establish a connection, the user must use the
KerberosAuth authentication class:
conn = xgt.Connection(host = "graph_server", auth = xgt.KerberosAuth())
Usually, no arguments need to be given to the
KerberosAuth constructor as the user identity is derived from the already obtained Kerberos tickets.
host argument must be supplied to the
Depending on how the system running the xGT server has been set up, it might be necessary to specify another parameter called the Kerberos service principal.
The default value of the Kerberos service principal is computed from the name of the host running the service by the xGT client by using the prefix “xgtd/”.
The string “TROVARES.COM”, in this example, is the name of the Kerberos realm, which usually maps to the network domain name.
The keyword argument
principal on the
KerberosAuth constructor allows the specification of that parameter when the default is not acceptable.
conn = xgt.Connection(host = "localhost", auth = xgt.KerberosAuth("xgtd/graph_server@TROVARES.COM"))
Consult your system administrator for details on how to connect to the xGT server using Kerberos.