HOWTO Use OpenSSO With SGD

This article describes how to use OpenSSO to enable single sign-on and enforce access policies for SGD users.

In this article, Sun OpenSSO Enterprise 8.0 is integrated with SGD 4.50 at the web server authentication level. This involves installing a plug-in, called a web agent, on the SGD web server. The web agent communicates with the OpenSSO Enterprise server, enabling authentication and authorization of SGD users to be carried out by OpenSSO.

For advanced users, a section describing how to to configure a basic SGD Gateway deployment for OpenSSO is included.

Configuring SGD to use OpenSSO involves the following steps:

Before You Begin

This article assumes that you have completed the following tasks:

  • Deployed and configured OpenSSO on a supported application server. In this article, Sun OpenSSO Enterprise 8.0 was deployed on a Sun GlassFish 2.1 Application Server. For documentation on installing and deploying OpenSSO, see the Sun OpenSSO Enterprise documentation.
  • Configured an SGD 4.50 server to use secure connections. For details of how to do this, see the SGD 4.50 Administration Guide.

The following server names are used in this article:

  • sgd-server.example.com – The SGD server
  • opensso-server.example.com – The OpenSSO Enterprise server
  • gateway-server.example.com – The SGD Gateway

Enable Third-Party Authentication for SGD

To use OpenSSO authentication for SGD logins, you must configure SGD to use third-party authentication. This involves the following steps:

  1. Configure Tomcat to Trust OpenSSO Authentication
  2. Enable Third-Party Authentication for SGD
  3. (Optional) Allow Administrators to Log In Using Third-Party Authentication

Configure Tomcat to Trust OpenSSO Authentication

  1. Edit the server.xml file.
    On the SGD host, edit the /opt/tarantella/webserver/tomcat/{version}/conf/server.xml file. Add a tomcatAuthentication="false" attribute to the <Connector> element in this file, as follows: 
    <!-- Define an AJP 1.3 Connector on port 8009 -->

<Connector port="8009" protocol="AJP/1.3"

 redirectPort="8443" tomcatAuthentication="false" />
  2. Restart the SGD web server.

    # tarantella restart webserver

Enable Third-Party Authentication for SGD

  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.
  4. On the Review Selections step, check the authentication configuration and click Finish.

See Enabling Third-party Authentication for SGD 4.50 for for more details about configuring SGD to use third-party authentication.

(Optional) Allow Administrators to Log In Using Third-Party Authentication

By default, for security reasons, SGD Administrators are not allowed to log in using third-party authentication. The SGD login page is always shown for these users, even if they have been authenticated by the SGD web server. To allow SGD Administrators to log in using third-party authentication, run the following command:

# tarantella config edit --tarantella-config-login-thirdparty-allowadmins 1

This means that SGD Administrators are not prompted for a second username and password combination when they log in to SGD.

Install the Web Agent

Installing the web agent involves the following steps:

  1. Obtain the Web Agent
  2. Create an Agent Profile
  3. Install the Web Agent on the SGD Web Server

Obtain the Web Agent

  1. Download the latest version of the web agent software.
    SGD 4.50 uses an Apache version 2.2 web server. Web agents for this version of the Apache web server are available for download from the OpenSSO web site.
    Note
    Ensure that you download version 3.0 or later of the Apache web agent.
  2. Extract the web agent software into a temporary directory on the SGD host.

    $ cp apache_v22_Linux_agent_3.zip /tempdir
    $ cd /tempdir
    $ unzip apache_v22_Linux_agent_3.zip

    A folder called web_agents/ is created.

Create an Agent Profile

The web agent uses an agent profile to communicate with the OpenSSO Enterprise server. You use the OpenSSO Enterprise Administration Console to create an agent profile, as follows:

  1. Log in to the OpenSSO Enterprise Administration Console as the OpenSSO administrator.
    The default OpenSSO administrator user is amadmin.
  2. Display the Web Agents page.
    Choose Access Control -> realm-name -> Agents -> Web.
  3. Create a new agent profile.
    1. In the Agent table, click the New button.
      The New Agent page is displayed.
    2. In the Name field, type the name for the new agent profile.
      For example, SGDagent.
    3. Type and confirm the password for the agent profile.
    4. In the Configuration field, select the Centralized option.
      This means that configuration settings are stored in the OpenSSO Enterprise server central configuration data repository.
    5. In the Server URL field, type the URL for the OpenSSO Enterprise server.
    6. In the Agent URL, type the URL for the SGD web server.
    7. Click Create to create the new agent profile.
      The Agent table is redisplayed, showing the name of the new web agent.
      The following screen capture shows some example settings for an agent profile.

  4. Configure the agent.
    Click on the agent name and configure the following settings for the agent:
    1. Not Enforced URLs. Display the Application tab and add the following URL to the Not Enforced URLs list: 
      https://sgd-server.example.com:443/axis*

      This setting enables access to the SGD web services.

    2. UserID. Display the Open SSO Services tab and ensure that the User ID Parameter setting is set to the default value of UserToken.
      This setting ensures that OpenSSO passes the REMOTE_USER variable for authenticated users. By default, SGD is configured to use the REMOTE_USER variable for third-party authentication.
    3. (Optional) Profile Attribute Fetch Mode. Display the Application tab and select the HTTP_HEADER option for the Profile Attribute Fetch Mode setting.
      This setting means that LDAP user profile attributes, such as cn or mail can be included in the headers of HTTP requests by the agent. The attributes to include are specified in the Profile Attribute Map table.
    4. (Optional) Agent log level. Display the Global tab for the agent profile and set the Agent Debug Level to All. The agent logs are written to the /tempdir/web_agents/apache22_agent/Agent_001/logs/debug/amAgent text file on the SGD host.
      This setting is useful when diagnosing problems with the operation and configuration of the agent.

Install the Web Agent on the SGD Web Server

  1. Create a password file.
    On the SGD host, create a text file with a one line entry that contains the password for the agent profile, specified in Create an Agent Profile. The agent profile password is a shared secret used by the OpenSSO server and the web agent. For example:

    $ cd /tempdir
    $ echo "letmein" > password.txt

  2. Stop the SGD web server.

    # tarantella stop webserver

  3. On the SGD host, run the web agent installation program.

    # cd /tempdir/web_agents/apache22_agent/bin
    # ./agentadmin --install

    Follow the on-screen prompts to install the web agent.
    You need to duplicate some of the details you typed when you created the agent profile, such as the agent name and the URLs for the OpenSSO server and the SGD web server.

  4. Start the SGD web server.

    # tarantella start webserver

Configure an Access Policy

To integrate OpenSSO with the SGD log in process, you must configure an access policy that protects the SGD login page. This means that SGD users must be authenticated by the OpenSSO Enterprise server before being allowed to access the SGD login page. The URL of the login page is https://sgd-server.example.com/sgd.

  1. Log in to the OpenSSO Enterprise Administration Console as the OpenSSO administrator.
    The default OpenSSO administrator user is amadmin.
  2. Display the Web Agents page.
    Choose Access Control -> realm-name -> Policies
  3. Create a new access policy.
    1. Click the New Policy button and create a new policy called SGD_access, for example.
    2. Click the Rules button and add the following URL Policy Agent rules for the policy: 
      Rule1: https://sgd-server.example.com:443/sgd*
Rule2: https://sgd-server.example.com:443/sgd*?*
    3. Click the Subjects button and allocate the policy to All authenticated users.
    4. Click OK to save the access policy.
      The following screen capture shows an example access policy.

Log In to SGD Using OpenSSO Authentication

Check that SGD users can log in using OpenSSO, as follows:

  1. Restart your browser.
  2. Log in to SGD.
    Go to the SGD login page at the following URL: https://sgd-server.example.com/sgd.
    Because this URL is protected, the OpenSSO login screen is shown, enabling users to be authenticated by OpenSSO.

  3. Enter your OpenSSO credentials and click OK.
    If authentication against the OpenSSO server is successful, you are logged in to SGD and the SGD webtop is displayed. The SGD login page is not shown.

(Optional) Customize the OpenSSO Deployment

To customise the OpenSSO deployment, you can do one or more of the following configuration tasks:

Enable Unauthenticated Access to the SGD Administration Console

You might want to enable unauthenticated access to the SGD Administration Console, so that SGD Administrators can configure SGD without having to be authenticated by OpenSSO. The SGD Administration Console is at https://sgd-server.example.com/sgdadmin.
To enable unauthenticated access to the SGD Administration Console, add the following URL to the Not Enforced URLs list for the web agent.

https://sgd-server.example.com:443/sgdadmin*

Enable Unauthenticated Access to the SGD Welcome Page

You might want to enable unauthenticated access to the SGD Welcome Page. This means that users can view the SGD documentation and download software, such as the SGD Client and SGD Gateway, without having to be authenticated by OpenSSO. The SGD Welcome Page is at https://sgd-server.example.com.
To enable unauthenticated access to the SGD Welcome Page, add the following URLs to the Not Enforced URLs list for the web agent.

https://sgd-server.example.com:443/
https://sgd-server.example.com:443/*.css
https://sgd-server.example.com:443/*.html
https://sgd-server.example.com:443/*.gif
https://sgd-server.example.com:443/*.ico
https://sgd-server.example.com:443/*.pdf
https://sgd-server.example.com:443/tarantella*

Enable Automatic Log Outs From OpenSSO

By default, when a user logs out of SGD, their OpenSSO user session is not ended automically. You can configure SGD to log users out of OpenSSO automatically as follows.

  1. Edit the SGD logout page.
    The SGD logout page is at /opt/tarantella/webserver/tomcat/{version}/webapps/sgd/webtops/standard/webtop/logged-out.jsp on the SGD host.
    Go to line 128 of the logged-out.jsp file and add the response.sendRedirect statement as shown in the following code fragment. 
    {
%>
          <td><img src="<%= getWebtopGif("loggedout_login.gif") %>" name="login" width="560" height="21" border="0"></td>

<%
    }
// Redirect to OpenSSO login page
response.sendRedirect(response.encodeRedirectURL("https://opensso-server.example.com:8181/opensso/UI/Logout?goto=https://sgd-server.example.com/sgd"));

%>
       </tr>
        <tr>
          <td colspan="3"><img src="<%= getWebtopGif("loggedout_bottom.gif") %>" width="560" height="47"></td>
          </tr>
      </table>
    </td>
  </tr>
</table>
</body>
</html>
  2. Restart the SGD web server.

    # tarantella restart webserver

    When users next log out of SGD, their OpenSSO user session is ended automatically and the OpenSSO login screen is displayed. The SGD logout screen is not shown.

(Optional) Using OpenSSO With the SGD Gateway

This section describes how to integrate OpenSSO into an SGD Gateway deployment. A basic deployment consisting of an SGD Gateway gateway-server.example.com, used with a single SGD server sgd-server.example.com and an OpenSSO server opensso-server.example.com is considered.

This section assumes that you have completed the following tasks:

To configure an SGD Gateway deployment for OpenSSO, do the following:

  1. Install a Web Agent on the SGD Gateway
  2. Reconfigure the Web Agent on the SGD server
  3. Log In to SGD Through the SGD Gateway

Install a Web Agent on the SGD Gateway

The SGD Gateway includes an Apache web server. This means that the steps for installing a web agent are very similar to those for an SGD server, as described in Install the Web Agent.

  1. Obtain the web agent software.
    This is described in Obtain the Web Agent.
  2. Create a new agent profile.
    The procedure is identical to that described in Step 3 of Create an Agent Profile, except that for the Agent URL setting you must specify the URL of the SGD Gateway server.
    The following screen capture shows some example settings for the agent profile used by the SGD Gateway.

  3. Configure the agent.
    Click on the agent name and configure the following settings for the agent:
    1. SSO Only Mode. Display the Global tab and enable the SSO Only Mode setting.
      This setting means that access policies are not applied.
    2. Not Enforced URLs. Do not add any URLs to the Not Enforced URLs list. Ensure that the list is empty.
    3. UserID. Display the Open SSO Services tab and ensure that the UserID setting is set to the default value of UserToken.
      This setting ensures that OpenSSO passes the REMOTE_USER variable for authenticated users.
  4. Create a password file.
    On the SGD Gateway, create a text file with a one line entry that contains the password for the agent profile. For example:

    $ cd /tempdir
    $ echo "gatewaypass" > password.txt

  5. Stop the SGD Gateway.

    # /opt/SUNWsgdg/bin/gateway stop

  6. On the SGD Gateway host, run the web agent installation program.

    # cd /tempdir/web_agents/apache22_agent/bin
    # ./agentadmin --install

    Follow the on-screen prompts to install the web agent.

  7. Start the SGD Gateway.

    # /opt/SUNWsgdg/bin/gateway start

Reconfigure the Web Agent on the SGD Server

Because the SGD server is being used in an SGD Gateway deployment, you must make the following configuration changes for the web agent on the SGD server.

  1. Log in to the OpenSSO Enterprise Administration Console as the OpenSSO administrator.
    The default OpenSSO administrator user is amadmin.
  2. Display the Web Agents page.
    In the OpenSSO Enterprise Administration Console, choose Access Control -> realm-name -> Agents -> Web.
  3. Configure the web agent.
    Click on the agent name and configure the following settings:
    1. SSO Only Mode. On the Global tab, select SSO Only Mode.
      This setting means that access policies are not applied.
    2. Fully Qualified Domain Name (FQDN) Mapping. On the Application tab, set up the FQDN Virtual Host Map as follows:

      [sgd-server.example.com]=gateway-server.example.com

      This setting ensures that the SGD server URL is not shown during login.

  4. Restart the SGD web server.

    # tarantella restart webserver

Log In to SGD Through the SGD Gateway

  1. Restart your browser.
  2. Log in to SGD through the SGD Gateway.
    1. Go to https://gateway-server.example.com/sgd.
      The OpenSSO login screen is shown.
    2. Enter your OpenSSO credentials and click OK.
      If authentication against the OpenSSO server is successful, you are logged in to the SGD server sgd-server.example.com and the SGD webtop is displayed. The SGD login page is not shown.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Sun Microsystems community and they might not be employed or in any way formally affiliated with Sun Microsystems. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Sun nor any other party necessarily agrees with them.

Copyright 1994-2009 Sun Microsystems, Inc.
Powered by Atlassian Confluence Sun Guidelines on Public Discourse Privacy Policy Terms of Use Trademarks Site Map Employment Investor Relations Contact