2.6. Third-Party Authentication and Web Authentication

Third-party authentication enables users to log in to SGD if they have been authenticated by an external mechanism.

If you are using the SGD webtop, the only form of third-party authentication you can use is web authentication. If you develop your own webtop applications using SGD web services, you can use any third-party authentication mechanism.

Third-party authentication is disabled by default.

This section includes the following topics:

2.6.1. How Third-Party Authentication Works

The user types in a user name and password directly to the external mechanism, typically using a web browser's authentication dialog.

Third-party authentication is based on trust. SGD trusts that the third-party mechanism has authenticated the user correctly and so they are authenticated to SGD.

Next SGD performs a search to establish the user identity and user profile. The following search methods can be used:

  • Search Local Repository

  • Search LDAP Repository

  • Use Default Third-Party Identity

If more than one search method is enabled, the methods are tried in the order they are listed above. The first matching user identity found is used. The search methods are described in the following sections.

If the searches do not produce a match, SGD cannot establish an identity for the user and the user cannot log in. If you are using the SGD webtop, the standard login page displays so that the user can log in using system authentication.

2.6.1.1. Search Local Repository

The Search Local Repository method searches the local repository for a user profile with a Name attribute that matches the user's third-party user name. If there is no match, the search is repeated on the Login Name attribute, and finally on the Email Address attribute. If no user profile is found, the next search method is tried.

2.6.1.1.1. User Identity and User Profile

If a user profile is found, that object is used for the user identity and user profile. In the SGD datastore, the user identity is in the Local namespace. In the Administration Console, the text "(Local)" is displayed next to the user identity. On the command line, the user identity is located in .../_ens.

2.6.1.2. Search LDAP Repository

The Search LDAP Repository method searches an LDAP directory for an LDAP object with an attribute that matches the user name typed by the user. By default, SGD searches the following attributes:

  • cn

  • uid

  • mail

If an LDAP object is found, the password typed by the user is checked against the LDAP object. If the authentication fails, the next authentication mechanism is tried.

If an LDAP object is not found, the next search method is tried.

2.6.1.2.1. User Identity and User Profile

The user identity is the DN of the user's LDAP object. In the SGD datastore, the user identity is in the LDAP namespace. In the Administration Console, the text "(LDAP)" is displayed next to the user identity. On the command line, the user identity is located in .../_service/sco/tta/ldapcache.

Next SGD searches for the user profile. When searching for the user profile, you can specify Use Default LDAP Profile or Use Closest Matching LDAP Profile. Use Default LDAP Profile is the default.

If Use Default LDAP Profile is selected, the profile object o=System Objects/cn=LDAP Profile is used for the user profile.

If Use Closest Matching LDAP Profile is selected, SGD establishes the user profile by searching the local repository, allowing for differences between the LDAP and SGD naming systems. SGD searches for the following until a match is found:

  • A user profile with the same name as the user's LDAP object.

    For example, if the LDAP object is cn=Emma Rald,cn=Sales,dc=example,dc=com, SGD searches the local repository for dc=com/dc=example/cn=Sales/cn=Emma Rald.

  • A user profile in the same organizational unit as the user's LDAP object but with the name cn=LDAP Profile.

    For example, dc=com/dc=example/cn=Sales/cn=LDAP Profile.

  • A user profile in any parent organizational unit with the name cn=LDAP Profile.

    For example, dc=com/dc=example/cn=LDAP Profile.

If there is no match, the profile object o=System Objects/cn=LDAP Profile is used for the user profile.

2.6.1.3. Use Default Third-Party Identity

The Use Default Third-Party Identity method does not perform a search.

2.6.1.3.1. User Identity and User Profile

The user identity is the third-party user name. In the SGD datastore, the user identity is in the Third-party namespace. In the Administration Console, the text "(3rd party)" is displayed next to the user identity. On the command line, the user identity is located in .../_service/sco/tta/thirdparty.

The profile object System Objects/Third Party Profile is always used for the user profile.

2.6.2. Setting Up Third-Party Authentication

Setting up third–party authentication involves the following configuration steps:

  1. (Optional) Prepare to use LDAP directories.

    Third–party authentication can be configured to search an LDAP directory to establish users' identities.

    Check that you are using a supported LDAP directory, see Section 2.4.3.1, “Supported LDAP Directories”.

    Additional configuration might be required to use SGD with your LDAP directory, see Section 2.4.3, “Preparing for LDAP Authentication”.

    For organizations with complex LDAP deployments, use service objects to manage and tune your LDAP configuration. See Section 2.8.4, “Using Service Objects”.

  2. Enable third–party authentication.

    See Section 2.6.3, “How to Enable Third-Party Authentication”.

    By default, SGD Administrators cannot log in to SGD when third–party authentication is enabled, see Section 2.6.8, “SGD Administrators and Third-Party Authentication”.

  3. Enable a third–party authentication mechanism.

    The most common authentication mechanism used with third–party authentication is web authentication. See Section 2.6.5, “Enabling Web Authentication”.

2.6.3. How to Enable Third-Party Authentication

  1. In the SGD Administration Console, display the Secure Global Desktop Authentication Configuration Wizard.

    Go to the Global Settings → Secure Global Desktop Authentication tab and click the Change Secure Global Desktop Authentication button.

  2. On the Third-Party/System Authentication step, select the Third-Party Authentication check box.

  3. On the Third-Party Authentication - User Identity and Profile step, select the check box for one or more search methods for finding the user identity.

    For details on how the search methods work, see Section 2.6.1, “How Third-Party Authentication Works”.

    If the Search LDAP Repository check box is selected, select an option for finding the LDAP user profile.

  4. (Optional) On the LDAP Repository Details step, configure the LDAP directory details.

    The LDAP Repository Details step only displays if an LDAP search method is selected in Step 3.

    1. For Repository Type, select the LDAP option.

      Select this option even if you are using a Microsoft Active Directory server for LDAP authentication. The Active Directory option enables Active Directory authentication, see Section 2.2, “Active Directory Authentication”.

    2. In the URLs field, type the URL of one or more LDAP directory servers.

      For example, ldap://melbourne.example.com.

      If you type more than one URL, separate each URL with a semicolon (;).

      SGD uses the URLs in the order they are listed. If the first LDAP directory server in the list is unavailable, the next one is tried.

      To use secure connections to LDAP directory servers, use an ldaps:// URL.

      The URLS must all be of the same type, either ldap:// or ldaps://. You cannot use a mixture of ldap:// and ldaps:// URLs.

      If the LDAP directory uses a non-standard port, specify the port number as part of the URL, for example ldap://melbourne.example.com:5678. Otherwise the port number can be omitted.

      You can specify a DN to use as the search base, for example ldap://melbourne.example.com/dc=example,dc=com. This specifies the part of the LDAP directory used to search for the user identity.

    3. Type the details of an LDAP user in the User Name and Password fields.

      The user name must be the DN of the user, for example cn=sgd-user,cn=Users,dc=example,dc=com. This is the administrator bind DN, see Section 2.4.3.3, “LDAP Bind DN and Password Change” for more details.

      As you can only enter one user name and password, this user must be able to search all LDAP directory servers listed in the URL field.

      If the directory server supports anonymous binds, you can omit the user name and password. You must be able to perform LDAP queries for user data to use anonymous binds.

  5. On the Review Selections step, check the authentication configuration and click Finish.

    If you enabled the LDAP search method, SGD creates a service object called generated. Service objects are used to manage directory services configuration, see Section 2.8.4, “Using Service Objects” for more details.

2.6.4. Web Authentication

Web authentication, or HTTP authentication, is the most common use of third-party authentication. With web authentication, the web server performs the authentication, and SGD determines the user identity and user profile.

The advantage of web authentication is that you can use any web server authentication plug-in as long as it sets the REMOTE_USER environment variable. If the authentication plug-in you use sets a different variable, you can configure SGD to support it, see Section 2.6.6, “Using Authentication Plugins With Web Authentication”.

You can use web authentication and system authentication together. It is best to enable at least one system authentication mechanism as a fallback. If SGD cannot find a user profile for a user, the standard SGD login page displays so that the user can authenticate using a system authentication mechanism.

2.6.4.1. How Web Authentication Works

Web authentication works as follows:

  • A web server administrator protects a section of a web site. For SGD, this is usually the https://server.example.com/sgd URL, where server.example.com is the name of an SGD server.

  • When a web browser first tries to access a URL within the protected section, the web server responds by requesting authentication.

  • The web browser displays an authentication dialog to the user. SGD users do not see the SGD login screen.

  • The user types a user name and password, which the browser sends to the web server.

  • The web server authenticates the user's credentials and grants access to the requested URL. SGD users go directly to their webtop.

The web browser caches the user's credentials because the credentials must be sent with every request to the protected URL. The browser sends the credentials automatically. The credentials are cached as follows:

  • Temporarily. The credentials are cached until the user closes the browser.

  • Permanently. The user selects the check box on the browser's authentication dialog.

Once the web server has authenticated the user, its sets the REMOTE_USER environment variable. This variable contains the user name of the authenticated user. SGD takes the value of the REMOTE_USER variable and uses it to search for the user identity and user profile. SGD supports four search methods for establishing the user identity and user profile, see Section 2.6.1, “How Third-Party Authentication Works”.

2.6.4.2. Security Considerations of Using Web Authentication

The following are the main security considerations of using web authentication with SGD:

  • Web browser cache. With web authentication, the web browser caches the user's credentials and, in effect, their authentication to SGD. To minimize the risk of cached credentials being used by someone else, ensure that users do the following:

    • Deselect the save password check box in the web browser authentication dialog. This ensures that user credentials are not saved permanently by the web browser.

    • Close the web browser after logging out. This clears the user's credentials from the temporary cache. Logging out of SGD does not clear the credentials.

  • Secure web server. Use a secure (HTTPS) web server to prevent user credentials from being sent in plain text.

  • Trusted user. SGD is able to trust the web server's authentication because the SGD webtop and the SGD server have a shared secret which is the user name and password of a trusted user. The credentials of this trusted user are created by default when you install SGD. You might want to change these credentials, see Section 2.6.9, “Trusted Users and Third-Party Authentication” for details of how to do this.

2.6.5. Enabling Web Authentication

To enable web authentication, you must configure both the web server and SGD.

You configure the web server for web authentication by protecting the /sgd URL on each SGD host. How you protect the /sgd URL depends on your web server, see your web server documentation for details. For the SGD web server, you can protect the /sgd URL in either the Apache or the Tomcat components. See Section 2.6.5.1, “How to Enable Web Authentication for the SGD Web Server” for an example of how to do this.

To configure SGD to support web authentication, you must enable third-party authentication, see Section 2.6.3, “How to Enable Third-Party Authentication”.

2.6.5.1. How to Enable Web Authentication for the SGD Web Server

For the SGD web server, you can protect the /sgd URL in either the Apache or the Tomcat components. This procedure protects the URL in Apache.

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

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

  2. Create a web server password file.

    Use the /opt/tarantella/webserver/apache/apache-version/bin/htpasswd program to create a web server password file and add entries.

    For example, to create the /etc/httpd/passwords password file and add an entry for the user jdoe, use the following command:

    # /opt/tarantella/webserver/apache/apache-version/bin/htpasswd -c \
    /etc/httpd/passwords jdoe
    New password: password
    Re-type new password: password
    Adding password for user jdoe

    For example to add an entry for the user privers to the /etc/httpd/passwords file, use the following command:

    # /opt/tarantella/webserver/apache/apache-version/bin/htpasswd \
    /etc/httpd/passwords privers
    New password: password
    Re-type new password: password
    Adding password for user privers
  3. Change the permissions on the web server password file.

    The password file must accessible by the ttaserv user.

    For example, if the web server password file is /etc/httpd/passwords, run the following commands:

    # chmod 440 /etc/httpd/passwords
    # chown ttaserv:ttaserv /etc/httpd/password
  4. Edit the Apache configuration file and protect the /sgd URL.

    The Apache configuration file is /opt/tarantella/webserver/apache/apache-version/conf/httpd.conf.

    1. Insert the following directives at the end of the configuration file:

      SetEnvIf Request_URI "\.(class|cab|jar|gif|der)$" sgd_noauth_ok
        <Location /sgd>
          Order Allow,Deny
          Allow from env=sgd_noauth_ok
          AuthUserFile file-path
          AuthName auth-domain
          Authtype Basic
          Require valid-user
          Satisfy any
        </Location>

      where file-path is the full path to the web server password file and auth-domain is the name of authorization realm that appears in the web browser's authentication dialog.

      The SetEnvIf directive protects the /sgd URL without affecting the operation of the Welcome Page of the SGD web server.

      For more information on how to configure the Location directive, check the Apache documentation.

      Note

      You must use a Location directive rather than a Directory directive because the SGD web server delegates the management of the /sgd URL to Tomcat. This is configured in the Apache configuration file and means you cannot use an .htaccess file to protect the /sgd URL.

    2. Save the changes.

  5. Edit the Tomcat configuration file.

    The Tomcat component of the SGD web server must be configured to trust the web server's authentication.

    The Tomcat configuration file is /opt/tarantella/webserver/tomcat/tomcat-version/conf/server.xml.

    1. Amend the configuration of the AJP 1.3 Connector.

      Add a tomcatAuthentication="false" attribute to the <Connector> element as follows:

        <!-- Define an AJP 1.3 Connector on port 8009 -->
        <Connector port="8009" protocol="AJP/1.3"
        redirectPort="8443" tomcatAuthentication="false" />
    2. Save the changes.

  6. Restart the SGD web server.

    You must restart the SGD web server for the configuration changes to take effect.

    # tarantella restart webserver

2.6.6. Using Authentication Plugins With Web Authentication

SGD web authentication relies on the web server setting the REMOTE_USER environment variable to identify the user. If you use an authentication plug-in for web authentication, it is likely that the plug-in uses a different environment variable to identify the user.

It is best to install your authentication plug-in and verify that it is working, before configuring SGD.

In addition to the REMOTE_USER environment variable, SGD includes support for the SSL_CLIENT_S_DN_CN variable. This environment variable is set when using client certificates with web authentication. See Section 2.6.7, “Using Client Certificates With Web Authentication” for details of how to enable support for this variable.

If your plug-in uses a different environment variable, you must configure the webtop web application to support your environment variable. See Section 2.6.6.1, “How to Enable Support for Other Environment Variables for Web Authentication”.

2.6.6.1. How to Enable Support for Other Environment Variables for Web Authentication

Before you begin, consult the documentation for the web server authentication plug-in and make a note of the environment variable it sets to identify users.

HTTPS connections must be enabled on the SGD web server. You enable HTTPS connections by using the --https argument when you start the SGD server or the SGD web server.

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

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

  2. Configure the Apache component of the SGD web server to forward your variable to the Tomcat component.

    1. Edit the Apache configuration file.

      The file is /opt/tarantella/webserver/apache/apache-version/conf/httpd.conf.

    2. Add a JkEnvVar directive to forward your environment variable.

      Search for the existing JKEnvVar directives and add a directive for your own variable, as follows:

        #JkEnvVar SSL_CLIENT_S_DN_CN " "
        #JkEnvVar HTTP_SAFEWORD_USER " "
        JKEnvVar Your-Variable " "
    3. Make the variable available in the /sgd location.

      Add the following Location directive at the end of the file:

        <Location "/sgd">
        SSLOptions +StdEnvVars +ExportCertData
        </Location>
    4. Save the changes.

  3. Configure the webtop web application to use your environment variable.

    1. Change to the SGD web application resources directory.

        cd /opt/tarantella/webserver/tomcat/tomcat-version
        cd webapps/sgd/resources/jsp
    2. Edit the webtopsession.jsp file and add support for your variable.

      Search for either the HTTP_SAFEWORD_USER or the SSL_CLIENT_S_DN_CN variable and use the code for these variables as examples of how to implement your own variable.

    3. Save the changes.

  4. Restart the SGD web server.

2.6.7. Using Client Certificates With Web Authentication

You can strengthen the security of web authentication by authenticating users if they have valid Public Key Infrastructure (PKI) certificate installed on the client device.

To use PKI certificates, you must configure the web server so that to access the /sgd URL you need a client certificate. The SGD web server includes the Apache mod_ssl (http://www.modssl.org) module which you can use to set up PKI client certificates.

SGD web authentication relies on the web server setting the REMOTE_USER variable to identify the user. However, when users are authenticated using client certificates generally another environment variable is used to identify the user. For Apache web servers, including the SGD web server, the SSL_CLIENT_S_DN_CN variable is used. See Section 2.6.7.1, “How to Enable Support for the SSL_CLIENT_S_DN_CN Variable” for details of how to add support for this variable. If your web server sets a different variable, see Section 2.6.6.1, “How to Enable Support for Other Environment Variables for Web Authentication”.

2.6.7.1. How to Enable Support for the SSL_CLIENT_S_DN_CN Variable

HTTPS connections must be enabled on the SGD web server. You enable HTTPS connections by using the --https argument when you start the SGD server or the SGD web server.

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

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

  2. Configure the Apache component of the SGD web server to forward the SSL_CLIENT_S_DN_CN variable to the Tomcat component.

    1. Edit the Apache configuration file.

      The file is /opt/tarantella/webserver/apache/apache-version/conf/httpd.conf.

    2. Enable the JkEnvVar directive to forward the SSL_CLIENT_S_DN_CN variable.

      Search for the existing JKEnvVar directives and add a directive for the SSL_CLIENT_S_DN_CN variable as follows:

      JkEnvVar SSL_CLIENT_S_DN_CN " "
      #JkEnvVar HTTP_SAFEWORD_USER " "
    3. Make the SSL_CLIENT_S_DN_CN variable available in the /sgd location.

      Add the following the Location directive at the end of the file:

      <Location "/sgd">
       SSLOptions +StdEnvVars +ExportCertData
      </Location>
    4. Save the changes.

  3. Restart the SGD web server.

2.6.8. SGD Administrators and Third-Party Authentication

By default, third-party authentication does not permit SGD Administrators to log in to SGD. This is a security measure. To change this behavior, use the following command:

$ tarantella config edit \
--tarantella-config-login-thirdparty-allowadmins 1

2.6.9. Trusted Users and Third-Party Authentication

Third-party authentication gives users access to SGD without having to authenticate to an SGD server. SGD is able to trust the third-party authentication mechanism because client applications, such as the webtop, and the SGD server have a shared secret which is the user name and password of a trusted user.

In a standard installation, there is just one trusted user. However, you might want to create additional trusted users in the following circumstances:

  • You relocate the webtop to a different JavaServer Pages (JSP) technology container on a different host.

  • You develop your own client applications, using the SGD com.tarantella.tta.webservices.client.views package, either on the same host as SGD or on a different host.

  • You have concerns about the security of the default trusted user.

You create and maintain the "database" of trusted users on each SGD server in the array. The database is not shared between SGD servers. See Section 2.6.9.2, “How to Create a New Trusted User” for details of how to add a trusted user. Note the following:

  • The tarantella webserver add_trusted_user command is the only supported way to store trusted users on the SGD server.

  • To change the password of an existing trusted user, you must first delete the user with the tarantella webserver delete_trusted_user command and then create the user again.

  • Every time you make a change to a trusted user, you must restart the SGD web server.

  • Usually client applications only use the credentials of a single trusted user to access SGD services.

2.6.9.1. Information for Application Developers

If you are using SGD web services to develop your own applications, the ITarantellaExternalAuth web service is used for third-party authentication. This web service is protected with Basic authentication so that you can only access it using the credentials of a trusted user. This is configured as follows:

  • The https://SGD-server/axis/services/document/externalauth URL is protected in the configuration file for the Axis web application /opt/tarantella/webserver/tomcat/tomcat-version/webapps/axis/WEB-INF/web.xml

  • The Tomcat component of the SGD web server is configured to support Basic authentication using Tomcat's MemoryRealm and Secure Hash Algorithm (SHA) digested passwords. This is in the Tomcat configuration file /opt/tarantella/webserver/tomcat/tomcat-version/conf/server.xml.

  • The list of trusted users is stored in the Tomcat users configuration file /opt/tarantella/webserver/tomcat/tomcat-version/conf/tomcat-users.xml

If you have developed your own client applications using the com.tarantella.tta.webservices.client.views package, you can store the trusted user credentials for the application in the same way as the webtop, see Section 2.6.9.2, “How to Create a New Trusted User”. Otherwise, you need to develop your own methods for storing the credentials.

2.6.9.2. How to Create a New Trusted User

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

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

  2. Stop the SGD web server.

  3. Add the new trusted user to the database of trusted users on the SGD server.

    1. Think of a user name and password for the trusted user.

    2. Create the trusted user.

      Use the following command:

      # tarantella webserver add_trusted_user username
      

      When prompted, type the password.

    3. Check the user is created.

      Use the following command:

      # tarantella webserver list_trusted_users
    4. Check that the trusted user works.

      Go to the https://SGD-server/axis/services/document/externalauth URL. When prompted, log in as the trusted user.

  4. Add the new trusted user to the web services resources file for the webtop application.

    If you have relocated the webtop to a different host, perform this step on the remote host.

    1. Encode the user name and password of the trusted user.

      Use the following command:

      # /opt/tarantella/bin/jre/bin/java -classpath \
      /opt/tarantella/webserver/tomcat/tomcat-version/webapps/sgd/
      WEB-INF/lib/sgd-webservices.jar\
      com.tarantella.tta.webservices.client.views.SgdPasswd \
      --encode username:password
      
    2. Copy the encoded user name and password from the output.

    3. Change to the shared resources directory.

      # cd /opt/tarantella/webserver/tomcat/tomcat-version
      # cd shared/classes/com/tarantella/tta/webservices/client/views
      
    4. Edit the Resources.properties file.

    5. Replace the text after sgdaccess= with the encoded user name and password.

    6. Save the changes.

  5. Start the SGD web server.