LTech Single Sign On for Google Apps Documentation

The Single Sign-On Installer is a Windows MSI that handles deployment of the .NET Google Apps Single Sign-On application.

The installer handles the following deployment requirements:

  • Deployment of executable files
  • Creation of IIS Web Site or Virtual Directories
  • Basic setup of the .NET Single Sign-On web.config file

Requirements

  • Windows Server 2000, 2003, 2008.
  • IIS 6.0, WWW services, Microsoft .NET 3.5 Runtime.
  • Microsoft Active Directory or other directory services login with Account Operator rights.
  • Google Apps service user account, must have Administrator rights.
  • Recommended: Valid Secure Socket Layer (SSL) certificate issued by a trusted third party provider to provide secured HTTPS access to the Single Sign-On portal.

Installation Steps

The Single Sign-On Installer is a standard MSI package with the addition of three steps that will provide a standard configuration of the Single Sign-On application. Additional configuration parameters are available but are configured post installation.


I. Google Apps Domain Settings

The first setup page of prompts you to configuration the Google Apps domain.

  • Google Apps Domain - Enter the Google Apps domain that the Single Sign-On application will be authenticating.
  • Administrator Login - Provide a user account with Administrator rights for the Google Apps domain. This user will authenticate against Google Apps when changing passwords. The installer will append the Google Apps domain value to the login entered if it is not supplied.
  • Administrator Password - The password for the administrator login entered.

II. LDAP Connection

The second page provides configuration settings pertaining to the LDAP server.

  • LDAP Server - Enter a fully qualified domain name or IP address of the LDAP server to authenticate against.
  • Account Operator Login - Provide a valid user account for the LDAP server. The user must have Account Operator rights within your LDAP environment (Or equivalent rights to change account passwords).
  • Account Operator Password - Enter the password for the user login.

III. LDAP Information

The third page provides configuration settings for user authentication using LDAP.

  • LDAP Base DN - Enter the top level container that allows all user objects to sign in using their Active Directory credentials.
  • Mail Attribute - Enter the attribute that will contain the email address for user objects.

IV. Select Installation Address

During this step, the installer will deploy web service files to the selected location.

  • Site - Select existing IIS website where webservice will be installed. This is the path where files will be copied during installation.
  • Virtual Directory - Provide a virtual directory name to install into the selected Site.
  • Application Pool - Select existing IIS Application Pool to use for the selected Virtual Directory.

V. Perform Installation

Click "Next" to perform the installation. This may take a few minutes.


VI. Configuring the Google Apps Domain

At this point you should have a successful installation of the Single Sign-On Application. However for the Single Sign-On to be fully integrated with Google Apps the domain must be configured to point to the newly installed instance of the Single Sign-On Application.

To enable Single Sign-On on your domain:

  • Log in to your Google Apps domain control panel (https://www.google.com/a/yourdomain.tld).
  • Under the "Advanced tools" section select the link "Set up Single Sign-On (Single Sign-On)". This will direct you to the Single Sign-on set up page.
  • At the set up page you will be presented with the following form:

In the URL fields, enter the publicly available URL or IP that you will use to access the Single Sign-On application appended with the following paths:

  • Sign-in page URL - /Prompt.aspx
  • Sign-out page URL - /SignedOut.aspx
  • Change password URL - /ChangePassword.aspx

Example: https://sso.yourdomain.tld/virtualdirectory/Prompt.aspx

  • After supplying Sign in, Sign out, and Change Password URL's Save your changes, and proceed to upload your Verification Certificate on the same page.

  • To install the verification certificate click "Upload certificate" or "Replace certificate" and browse to the installation location of the Single Sign-On Application.

  • Under the root folder of the Single Sign-On Application, navigate to the "Keys" folder. This folder contains the keys used by the Single Sign-On Application. Select the file 'Single Sign-On.cer' file and click 'Upload' to upload the verification certificate to Google Apps.

  • After all URLs are entered and the verification certificate is uploaded click 'Enable Single Sign-on' to enable the Single Sign-On application and save the configuration one final time.

Post Installation Configuration

The installer provides a basic configuration of the .NET Single Sign-On Application. There are additional fields that are not necessary for configuration, but may provide additional features that are useful for your environment.

To modify these settings edit the web.config file located under the root of the location where the application was installed.

The following settings can be modified:

  • Security.PasswordMinLength - This option will enable password length validation on the Change Password page. The default value for this settings is -1 indicating that length validation does not occur, but if any value greater than zero is supplied the Change Password page will validate against this value.
  • Google.Apps.SingleSignOn.ChangePasswordRedirect - This option will enable a redirect to occur upon succesful password change. The default value is empty, indicating that no redirect will occur on successful change.
  • Google.Apps.SingleSignOn.SignOutRedirect - This option will enable a redirect to occur upon sign out. The default value is empty, indicating that no redirect will occur on sign out.

Single Sign-On Testing and Usage

After completing all steps, you can proceed to test and use your Single Sign-On application.

  • Log out of any active sessions for your Google Apps domain, if any.
  • Navigate to your Google Apps Mail URL (Example: https://mail.google.com/a/yourdomain.tld). You should be redirected to your Single Sign-On login page
  • Supply your valid LDAP username and password and click Submit.
  • If login is successful, you should be redirected to your Google Apps Mail page.

Error Messages - Troubleshooting

Sign On failures:

  • Invalid Mailbox: This account is found in your LDAP store, and authenticated successfully. The user account is not provisioned within your Google Apps domain.
  • Invalid Operation: This error can be encountered when your SSO host server's time is not properly synchronized. Please ensure your webserver's system time is synchronized with an external source, and accurate for the time zone it is situated within.
  • Login failed: The password provided does not allow for a successful logon to your directory server. Causes include invalid password, locked/suspended account, expired password, and unknown account.

Password Change failures:

  • Password Change Failed: This can happen for multiple reasons, and most likely related to your local password policies. Reasons for this message include:
    • Insufficient password length.
    • Insufficient complexity (Some LDAP/Active Directory environments require user passwords to adhere to complexity and history rules).
    • Directory Server / Account policy (Some accounts are disallowed from changing their passwords).
    • New password and password confirmation must match.

User Interface Customization

The Google Apps Single Sign-On solution allows for near full customization of the appearance user interface. The default installation provides the following resources:

  • Master Paging - A default template is provided to give the user interface a consistent theme.
  • Style sheets - A default style sheet is provided. Styles made be added or removed to this sheet, and additional style sheets can be added or referenced if required.
  • Customizing Confirm and Error Messages - Messages are defined within page HTML and may be edited to provide customized instructions for your environment, or for localization purposes.

HTML may be customized as necessary as long as required page elements are not removed. These required page elements include any server tags that implement the runat="server" attribute or are prefixed by 'asp.' Page elements that contain HTML may also have the inner HTML changed.

The Prototype JavaScript library included is not recommended to be modified. Any additional JavaScript should be added either by adding additional files, or by referencing JavaScript from another location.

The following screen shot is provided as an example of what type of elements are required page elements and can not be removed.

The screen shot provided represents the default Master page provided. Highlighted elements are required Master page elements and cannot have their ID attributes change and likewise they may also not be removed from the page. However you can add additional CSS styles to page elements where appropriate.