2.2 SGD Gateway Configuration Tasks

This section includes instructions for configuring the connections used by the SGD Gateway.

The following configuration tasks are described:

2.2.1 Client Device to SGD Gateway Connections

Configuring connections between the client device and an SGD Gateway involves the following configuration tasks:

  1. (Optional) Configure the ports and connections used by the SGD Gateway.

    You configure these settings when you install the SGD Gateway.

    To change these settings, see Section 2.2.1.1, “How to Configure the Ports and Connections for the SGD Gateway”.

  2. (Optional) On the SGD Gateway, install an SSL certificate for client connections.

    See Section 2.2.1.2, “How to Install an SSL Certificate for Client Connections Into the Client Keystore”.

  3. (Optional) Configure the SGD Gateway for connections from tablet devices.

    This task is only required if the Gateway is using an untrusted certificate.

    See Section 2.2.1.3, “How to Configure the SGD Gateway for Connections From Tablet Devices Using Untrusted Certificates”.

2.2.1.1 How to Configure the Ports and Connections for the SGD Gateway

You only need to use this procedure if you want to change the settings you made during installation of the SGD Gateway.

  1. Log in as superuser (root) on the SGD Gateway host.

  2. Run the gateway config create command.

    # /opt/SUNWsgdg/bin/gateway config create
    

    Answer the on-screen questions, to configure the following:

    • SGD Gateway port settings. The interface and port used by the SGD Gateway for incoming connections.

    • Network entry point. The IP address, or DNS name, and port that client devices use to connect to the SGD Gateway. This is not always the same as the address of the SGD Gateway. Depending on the configuration of your network, this can be the address of a load balancer or other external device.

    • Secure connections. Whether to secure the connections between the SGD Gateway and the SGD servers in the array. To use secure connections, the SGD servers in the array must be running in secure mode.

  3. Save the port and network entry point settings.

    The SGD Gateway is configured using the settings you entered.

2.2.1.2 How to Install an SSL Certificate for Client Connections Into the Client Keystore

The SSL certificate that the SGD Gateway uses for client connections is called the SGD Gateway SSL certificate. The SSL certificate is stored in the client keystore, /opt/SUNWsgdg/proxy/etc/keystore.client.

By default, the SGD Gateway uses a self-signed SGD Gateway SSL certificate for client connections, but you can replace the self-signed SSL certificate with a certificate signed by a Certificate Authority (CA).

The following procedure assumes you have an SSL certificate signed by a CA.

The private key you install must be in Privacy Enhanced Mail (PEM) format.

  1. Log in as superuser (root) on the SGD Gateway host.

  2. Copy the SSL certificate and the corresponding private key to the SGD Gateway host.

  3. Import the SSL certificate and private key into the client keystore.

    Use the gateway sslkey import command, as follows:

    # /opt/SUNWsgdg/bin/gateway sslkey import \
    --keyfile temp.key \
    --keyalg RSA \
    --certfile example.com.pem
    

    Here, the certificate file example.com.pem and the corresponding RSA-encoded private key, temp.key, are imported into the client keystore.

    The existing self-signed SSL certificate in the client keystore is overwritten.

    For details on how to import an SSL certificate chain, see Section B.27, “gateway sslkey import”.

  4. (Optional) Restart the SGD Gateway.

    Caution

    Only use this step if you are not performing initial configuration of the SGD Gateway. Restarting the SGD Gateway at this stage during initial configuration displays an error message, because initial configuration of the SGD Gateway has not been completed.

    Restart the SGD Gateway if you are replacing the SSL certificate on an SGD Gateway that is already configured and running.

    Note

    Restarting the SGD Gateway disconnects all user sessions and application sessions that are running through the SGD Gateway.

    On the SGD Gateway host, run the following command:

    # /opt/SUNWsgdg/bin/gateway restart
    

2.2.1.3 How to Configure the SGD Gateway for Connections From Tablet Devices Using Untrusted Certificates

Note

You only need to use this procedure if the following apply:

  • Your users are connecting to the SGD Gateway from a tablet device.

  • The SGD Gateway is using an untrusted SSL certificate, such as a self-signed certificate or an SSL certificate signed by a custom CA.

  1. Export the SGD Gateway SSL certificate.

    Repeat the following steps for each SGD Gateway.

    1. Log in as superuser (root) on the SGD Gateway host.

    2. Regenerate the SGD Gateway SSL certificate.

      1. Generate a self-signed certificate that is compatible with tablet client devices. Use the script provided for this task:

        # /opt/SUNWsgdg/bin/scripts/regenerate_sslcert.sh --ca

        The existing SGD Gateway SSL certificate in the client keystore is replaced.

      2. Restart the SGD Gateway.

        # /opt/SUNWsgdg/bin/gateway restart
    3. Export the SGD Gateway SSL certificate from the client keystore. For example:

      # /opt/SUNWsgdg/bin/gateway sslcert export --certfile gw1-example-com.pem

      When you export the certificate, it is best practice to rename the certificate file, so that you can identify the SGD Gateway it came from.

  2. Copy the SGD Gateway SSL certificates to the SGD array.

    1. Log in as superuser (root) on the primary SGD host.

    2. Copy the certificate files to the /opt/tarantella/var/tsp/certs/gateway directory on the primary SGD host.

    3. Check that the file permissions and ownership are correct. For example:

      # chmod 600 gw1-example-com.pem
      # chown root:ttaserv gw1-example-com.pem
  3. (Optional) Copy the CA certificate to the SGD array.

    This step is only required if the SGD Gateway SSL certificates are signed by a custom CA, or by an Intermediate CA.

    1. Log in as superuser (root) on the primary SGD host.

    2. Copy the CA certificate file to the /opt/tarantella/var/tsp/certs/gateway directory on the primary SGD host.

      For an Intermediate CA, copy the CA certificate chain.

    3. Check that the file permissions and ownership are correct. For example:

      # chmod 600 gw-ca.pem
      # chown root:ttaserv gw-ca.pem
  4. Update the security configuration used for the SGD Gateway.

    Use the script provided for this task:

    # /opt/tarantella/bin/scripts/mobile_profile_create.sh
    • A configuration profile at /opt/tarantella/var/docroot/certs/sgdg.mobileconfig is created and updated with details of the SSL certificate used by the SGD Gateway. A corresponding MD5 checksum file is also generated.

    • The Gateway SSL certificates are processed and corresponding .crt certificate files are generated in the /opt/tarantella/var/docroot/certs/gateway directory. The android_certs.html file which lists the certificates is updated.

  5. Copy the updated security configuration files to the other SGD servers in the array.

    Updated security configuration files are in the certs/ directory.

    Repeat the following step on every server in the array.

    1. Copy the /opt/tarantella/var/docroot/certs directory from the primary server to the SGD web server.

      Ensure that file permissions and ownerships are preserved. For example:

      # cp -pr certs/ /opt/tarantella/var/docroot/

See Secure Connections to Tablet Devices Using Untrusted Certificates in the Oracle Secure Global Desktop Administration Guide for more details about the required security configuration when using untrusted certificates.

2.2.2 SGD Gateway to SGD Server Connections

The connections between an SGD Gateway and the SGD servers in the array use certificates for mutual authorization. Configuring these connections involves the following configuration tasks:

  1. Install SGD server certificates on the SGD Gateway.

    See Section 2.2.2.1, “How to Install SGD Server Certificates”.

  2. Install the SGD Gateway certificate on the SGD array.

    See Section 2.2.2.2, “How to Install SGD Gateway Certificates on the SGD Array”.

  3. Configure SGD Client connections for the SGD Gateway.

    See Section 2.2.2.3, “How to Configure SGD Client Connections”.

2.2.2.1 How to Install SGD Server Certificates

To use this procedure, the SGD servers in the array must be running in secure mode.

In a standard installation, an SGD server is configured automatically to use secure connections. See “Secure Connections to SGD Servers” in Chapter 1 of the Oracle Secure Global Desktop Administration Guide if you need more information about how to enable security services on an SGD server.

Repeat the following procedure for each SGD server in the array.

  1. Log in as superuser (root) on the SGD host.

  2. Copy the CA certificate from the SGD server to the SGD Gateway keystore directory.

    The CA certificate for an SGD server is at /opt/tarantella/var/info/certs/PeerCAcert.pem on the SGD host.

    Note

    This is the same CA certificate that the SGD server uses for secure intra-array communication.

    The SGD Gateway keystore directory is /opt/SUNWsgdg/proxy/etc.

    When you copy the CA certificate, it is best practice to rename the certificate file so that you can identify what the file contains and the SGD server it came from.

  3. Copy the SSL certificate from the SGD server to the SGD Gateway keystore directory.

    The SSL certificate for an SGD server running in secure mode is at /opt/tarantella/var/tsp/cert.pem on the SGD host.

    The SGD Gateway keystore directory is /opt/SUNWsgdg/proxy/etc.

    When you copy the SSL certificate, it is best practice to rename the certificate file so that you can identify what the file contains and the SGD server it came from.

  4. Log in as superuser (root) on the SGD Gateway host.

  5. Import the certificates into the SGD Gateway keystore.

    # /opt/SUNWsgdg/bin/gateway server add --server sgd-server1 \
    --certfile /opt/SUNWsgdg/proxy/etc/PeerCAcert.pem --url https://sgd1.example.com \
    --ssl-certfile /opt/SUNWsgdg/proxy/etc/cert.pem
    

    The --server option defines the alias names used when storing the certificates in the keystore. In this example, the CA certificate is stored using an alias of sgd-server1, the SSL certificate is stored using an alias of sgd-server1-ssl.

    https://sgd1.example.com is the URL of the SGD web server.

  6. Restart the SGD Gateway.

    Note

    Restarting the SGD Gateway disconnects all user sessions and application sessions that are running through the SGD Gateway.

    On the SGD Gateway host, run the following command:

    # /opt/SUNWsgdg/bin/gateway restart
    

2.2.2.2 How to Install SGD Gateway Certificates on the SGD Array

Repeat the following procedure for each SGD Gateway.

  1. Export the SGD Gateway certificate.

    1. Log in as superuser (root) on the SGD Gateway host.

    2. Export the SGD Gateway certificate from the SGD Gateway keystore.

      Use the gateway cert export command, as follows:

      # /opt/SUNWsgdg/bin/gateway cert export --certfile gateway1.pem
      

      The certificate is exported to the file gateway1.pem.

      When you export the certificate, it is best practice to name the certificate file so that you can identify the SGD Gateway it came from.

    3. Copy the certificate to the /opt/tarantella/var/tsp directory on the primary SGD server in the array.

    4. Change the file permissions and ownership for the Gateway certificate.

      # chmod 600 /opt/tarantella/var/tsp/gateway1.pem
      # chown ttasys:ttaserv /opt/tarantella/var/tsp/gateway1.pem
      
  2. Register the SGD Gateway with the SGD array.

    1. On the primary SGD server, log in as superuser (root).

    2. Import the SGD Gateway certificate.

      # tarantella gateway add --name sgd-gateway1 \
      --certfile /opt/tarantella/var/tsp/gateway1.pem
      

      where sgd-gateway1 is a name used by SGD to identify the SGD Gateway, and gateway1.pem is the SGD Gateway certificate file name.

      The SGD Gateway certificate is added to the gateway keystore on the SGD server, at /opt/tarantella/var/info/gatewaycerts.

      To register multiple SGD Gateways at the same time, use the --file option of the tarantella gateway add command. See Section B.33, “The tarantella gateway Command” for more details.

      Configuration changes made using tarantella gateway add are replicated to the other SGD servers in the array.

2.2.2.3 How to Configure SGD Client Connections

  1. Configure the SGD Client connections that use the SGD Gateway.

    On the primary SGD server, set the --security-gateway global attribute to define which SGD Clients can use the SGD Gateway, based on their IP address or DNS name.

    To specify that all SGD Client connections are routed through TCP port 443 of a single SGD Gateway gateway1.example.com, use the following command:

    $ tarantella config edit --security-gateway \
    "*:sgdg:gateway1.example.com:443"
    

    To specify that all SGD Client connections are routed through TCP port 443 of an external load balancer lb.example.com, use the following command:

    $ tarantella config edit --security-gateway \
    "*:sgdg:lb.example.com:443"
    
    Note

    Changes to the --security-gateway attribute affect all SGD servers in the array. The changes only apply to new user sessions.

    See Section B.38, “The --security-gateway Attribute” for more details about how to use the --security-gateway attribute to define multiple SGD Client connection filters.

2.2.3 Client Device to Load Balancer Connections

Configuring connections between the client device and an external load balancer involves the following configuration tasks:

  1. Configure the load balancer to accept connections from client devices.

    See your load balancer documentation for details of how to do this.

  2. (Optional) Install the SSL certificate for the SGD Gateway on to the load balancer.

    See your load balancer documentation for details of how to do this.

2.2.4 Load Balancer to SGD Gateway Connections

Configuring connections between an external load balancer and the SGD Gateway involves the following configuration tasks:

  1. Configure the ports and connections used by the SGD Gateway.

    See Section 2.2.1.1, “How to Configure the Ports and Connections for the SGD Gateway”.

  2. (Optional) On the SGD Gateway, install an SSL certificate for incoming client connections.

    See Section 2.2.1.2, “How to Install an SSL Certificate for Client Connections Into the Client Keystore”.