Solutions

Setting up and configuring Windows Single Sign On (SSO) authentication on the ProxySG

Solutions ID:    KB3458
Version:    6.0
Status:    Published
Published date:    09/01/2009
Updated:    10/30/2013
 

Problem Description

Setting up and configuring Windows Single Sign On (SSO) authentication
How do I setup and configure Windows SSO?

Resolution

In a Windows SSO realm, the client is never challenged for authentication.  Instead, the BCAAA agent collects information about the current logged on user from the domain controller and/or by querying the client workstation.  Then the IP address of an incoming client request is mapped to a user identity in the domain.  If authorization information is also needed, then another realm (LDAP or local) must be created.

NOTE:  The Windows SSO realm works reliably only in environments where one IP address maps to one user.  If an IP address cannot be mapped to a single user, authentication fails.  Those with NAT systems, which uses one set of IP addresses for intranet traffic and a different set for Internet traffic, should use a different realm for authentication.

PREREQUISITES:

  1. Workstations must be in a Windows domain environment
  2. Users must only logon to a single IP address.  Each user must have a unique IP address.  If users logon to many different workstations, or if the users logon to a Windows terminal server, then please use a different type of authentication, such as IWA or LDAP.
  3. The BCAAA agent must be installed onto a domain controller or member server.
  4. By default the BCAAA service is installed to run as LocalSystem.  For a Windows SSO realm to have correct permissions to query domain controllers and clients, the user who BCAAA runs under must be an authenticated user of the domain.
  5. If your policy will use Active Directory groups in order to make policy decisions, you will need to setup an LDAP authentication realm.  Please see KB3350 titled "Setting up and configuring LDAP authentication and authorization on the ProxySG".

STEPS:

First the BCAAA agent will be installed onto a Windows server.  The SSO.INI file will be modified.  Next, the ProxySG will be configured so the Windows SSO realm is created and configured.  Lastly, policy will be installed using the Visual Policy Manager to take advantage of the Windows SSO realm.


STEP I:
  Installing the BCAAA agent onto a Windows server.

  1. Check the BCAAA agent and make sure it is the correct version of BCAAA for the version of SGOS you are running.  Please see https://bto.bluecoat.com/download/ (or search the Knowledgebase for "download bcaaa") to verify the correct BCAAA version for your version of SGOS.  Remember that if you update SGOS on your ProxySG, you also need to update BCAAA prior to updating SGOS.
  2. Create a user ID as Domain user.  This newly created user ID will be assigned to BCAAA service. (LocalSystem account can be used if only DC query is used)
  3. Login to a Windows server with a this BCAAA user account, the server only needs to be a member of the domain.
  4. Install BCAAA to this Windows server.  Set the BCAAA user as the designated domain user.  If BCAAA has been already installed, in the “Log On” tab, select “This account”.  Browse the domain, select the user designated for BCAAA, enter the password, and click APPLY to save it.
  5. Ensure the BCAAA user has full access rights to the installed file location, which is: ..\Program Files\Blue Coat Systems\BCAAA,
  6. When installing BCAAA, it will ask for a port number.  Port 16101 is the default port.  Make sure firewalls, intrusion detection devices (IDS), and other similar security devices allow this traffic to pass freely on the network.  If a port other than 16101 is used, make sure that other port number is not being used by a different application on the network.  Additionally, that other port needs to be allowed to pass any firewalls, IDSes, and the like.
  7. Set the number of listening threads for a connection.  99 is the maximum number of threads that can be allocated to listen to the port.  The default and recommended number is two.
  8. Certificate information/SSL:  To help simplify the installation, install without certificates or SSL.  That way if there are problems, you are not trying to troubleshoot if this is an SSL/certificate issue, or is this a BCAAA issue.  Later on if you decide to enable SSL communications between the ProxySG and BCAAA and there are problems, then you can work on fixing the SSL/certificate issues.
  9. The BCAAA service will need to start as a user instead of a service.  Make sure the user you select has sufficient rights to view the information contained in Active Directory.  For information on how to add the log on as a service right to an account, please talk to your Active Directory or Windows administrator, or see http://technet.microsoft.com/en-us/library/cc739424(WS.10).aspx .

 

STEP II:  Modifying the SSO.INI file on the Windows server

The BCAAA agent in a Windows SSO environment must query a domain controller or a client workstation for the IP address to user name mapping.  There are three choices to use.  They are, query the domain controller only; query the client only; or query the domain controller first and then fall back to client query.  For further information and if you are running SGOS 5.x, please see the Configuration and Management Guide, Volume 4: Securing the Blue Coat ProxySG; Chapter 16: Windows Single Sign-on Authentication; How Windows SSO Realms Work for additional information.  For 6.2, see SGOS 6.2.x Administration Guide; Chapter 61: Windows Single Sign-on Authentication. You can go to https://bto.bluecoat.com/documentation/ to find the Configuration and Management Guide or Administration Guide for your version of SGOS.  Or you can search the Knowledgebase for "cmg".


Configuring Windows SSO for domain controller querying:

  1. Go to /Program Files/Blue Coat Systems/BCAAA/ and look for the SSO.INI file.  Open the file using a text editor.
  2. Look for the DCQSetup section of the file.  remove ";" to enalbe this line:  DCQEnabled=1
  3. Also in the DCQSetup section, set the ValidTTL time to mark users as logged out after a defined number of seconds.  This prevents stale mappings in the IP-to-user-table.  For example, setting ValidTTL to 86400 seconds (one day) requires users log into their workstations at least once per day in order to be considered logged in by the ProxySG.  By default, logons are valid until another user logs on with the same IP address.
  4. [DCQSetup]
    DCQEnabled=1
    DCQTTL=900
  5. In the section DCQDomainControllers, list the domain controllers you want to query or the IP address ranges of interest.  By default all domain controllers that are in the forest or are trusted are queried.  In large organizations, domain controllers that are not of interest for the ProxySG installation might be queried.  The SSO.INI file can be used to list the domain controllers of interest or IP address ranges of interest.  See the examples in the SSO.INI file for further details.
  6. (Optional:)  In the SSOSerivceUsers section, list the domain names of users who can access the domain controller on behalf of the service and mask the identity of the logged-on user.  Listing these users here forces the BCAAA service to ignore them for authentication purposes.
  7. Save the SSO.INI file and restart the BCAAA service for the changes to take effect.  If there are other SSO.INI file changes that need to be made, you can defer the BCAAA agent restart until all changes have been made to your SSO.INI file.


Configuring Windows SSO for client querying:

  1. By default client querying is blocked by Microsoft Windows XP SP2 firewall.  This can be overridden through domain policy.  If the firewall setting "Allow remote adninistration exception" or "Allow file and printer sharing exception" or "Define port exceptions (with port 445)" is enabled, then client querying will work.  Make sure that any firewall on the workstion allows this traffic to be passed.
  2. Go to /Program Files/Blue Coat Systems/BCAAA/ and look for the SSO.INI file.  Open the file using a text editor.
  3. Go to the ClientQuerySetup section and make sure the values for ValidTTL, InvalidTTL, and DCQTTL are all valid for your environment.  Please see the SSO.INI file proper for a description of these various variables.
  4. Save the SSO.INI file and restart the BCAAA service for the changes to take effect.  If there are other SSO.INI file changes that need to be made, you can defer the BCAAA agent restart until all changes have been made to your SSO.INI file.
  5. [ClientQuerySetup]
    ValidTTL=900
    InvalidTTL=900
    [Setup]
    MaxSSOThreads=25


(Optional:)  Configuring the SSO.INI file for synchronization:

Optionally, when using Domain Controller Querying, you can configure a BCAAA service to use another BCAAA service as a synchronization server.  Whenever a BCAAA service restarts, it contacts its synchronization server and updates the logon state.  Two given BCAAA services can use each other as their synchronization server.  Thus, each BCAAA service can act as a synchronization server to provide logon state to other BCAAA services, as well as acting as a synchronization client to update its logon state from another BCAAA service.

Each BCAAA service has a synchronization priority that determines synchronization behavior.  If the client BCAAA has the same or higher priority than the server BCAAA, synchronization is done once at restart to update the client state.  Once synchronization is complete the client BCAAA drops the synchronization connection and begins querying the domain controllers. 

However, if the server BCAAA has higher priority, then the client BCAAA keeps the synchronization link open and continuously updates its logon state from the higher priority BCAAA.  The client BCAAA does not query the domain controllers itself unless the synchronization link fails.

This makes it possible to manage the query load on the domain controllers.  If there is no issue with load, then the default configuration (without synchronization), with all BCAAA agents querying the domain controllers is acceptable.  However, if load on the domain controllers is an issue, synchronization can be used to minimize this load while still providing fail-over capabilities.

By default, all BCAAA agents have the same synchronization priority, meaning that they synchronize on startup and then do their own domain controller querying.  Here are the steps necessary if you wish to synchronize your BCAAA agents:

  1. Go to /Program Files/Blue Coat Systems/BCAAA/ and look for the SSO.INI file.  Open the file using a text editor.
  2. Update the SSOSyncSetup section.  The settings along with their default values are listed below.  For explanations as to what each setting does, please see the SSO.INI file.
  • ServerPriority=100
  • EnableSyncServer=1
  • SyncPortNumber=16102
  • UseSSL=0
  • VerifyCertificate=0
  • QueryDelta=10
  • RetrySyncTime=60
  1. Update the SSOSyncServer section with the IP address or hostname of the BCAAA service to use a synchronization server.
  2. In the SSOSyncClients section, list the IP addresses or hostnames of the BCAAA services that will use this BCAAA service as their synchronization service.
  3. Save the SSO.INI file and restart the BCAAA service for the changes to take effect.  If there are other SSO.INI file changes that need to be made, you can defer the BCAAA agent restart until all changes have been made to your SSO.INI file.

 

STEP III:  Configuring the Windows SSO authentication realm on the ProxySG.

  1. Login to the Management Console ( https://<ip.address.of.proxysg>:8082/ ) and go to the Configuration tab > Authentication > Windows SSO > Windows SSO Realm tab.
  2. Click on the "New" button and and give your Windows SSO realm a name and then click on the OK and the Apply buttons respectively.  In this example, we will use MyWindowsSSO as the name of the Windows SSO realm.
  3. Click on the "Agents" tab next to the Windows SSO Realm tab. 
    1. If you have multiple Windows SSO realms, select the correct realm name at the top of the page. 
    2. For primary agent, enter the IP address of the domain controller or member server that is running the BCAAA agent. Verify the port number is the same port number used when the BCAAA agent was installed.  If there is an alternate BCAAA agent, enter the alternate's IP address and hot port.
    3. For the SSL options, make sure "Enable SSL" is unchecked.  This is for simplicity sake.  Once Windows SSO is up and running correctly, then SSL can be enabled.
    4. The Timeout Request field is the number of seconds the ProxySG allows for each request attempt before timing out.  The default is 60 seconds.
    5. Select the Query Type (Query Domain Controler, Query Client, or Query Domain Controller and Client).  The default is "Query Domain Controller".  NOTE:  If an authentication mode without surrogate credentials is being used, such as "proxy" or "origin" authentication modes, then the Query Domain Controller and Client and Query Client options can cause a lot of traffic when querying the clients, as each authentication request results in a request to the BCAAA service.  Depending on the client time-to-live (TTL), this can result in a client workstation query.  If the client workstation querying traffic is a concern, the Query Domain Controllers option should be used instead.
    6. Click on the Apply button to save your changes.
  4. Click on the Authorization tab.  Setting up authorization may be optional.  If policy decisions are not made on groups, then authorization is not necessary.  If policy decisions are made based on group membership, then authorization is required. 
    1. Select the Windows SSO realm name.  In this example, it is MyWindowsSSO.
    2. Select the authorization realm name.  An LDAP authorization and authentication realm should have been created prior.  Select the appropriate LDAP realm.  If an LDAP authentication and authorization realm has not been created, please see KB3350 titled "Setting up and configuring LDAP authentication and authorization on the ProxySG".
    3. For "Authorization username", you can leave it with the default, unless the user's authorization information resides in a different root DN.
    4. Click on the Apply button to save your changes.
  5. Click on the Windows SSO General tab.  Verify that the information found on that page is correct. There is no need to configure a Virtual URL for a Windows SSO realm regardless of deployment so you can leave that box blank.

 

STEP IV:  Configuring policy

  1. In the Management Console ( https://<ip.address.of.proxysg>:8082/ ) go to the Configuration tab > Policy > Visual Policy Manager > Launch.  The Visual Policy Manager (VPM) will launch.
  2. Click on Policy > Add Web Authentication Layer... > and give it an appropriate name, such as WinSSOAuth and click on the OK button.  Your new web authentication layer called WinSSOAuth will be created.
  3. Since this is a new web authentication layer, the first rule has been created.  In that rule, do the following:
    1. Go to the Action column, right click and select Set > New... > Authenticate...  Give it a name, such as WinSSO. 
    2. For the Realm, select the realm name given in step 3.2 above.  In this example, we used MyWindowsSSO as the name. 
    3. For simplicity sake, you can leave the authentication mode as Auto.  (For additional information about authentication modes, please see KB2877 or the Configuration and Management Guide (CMG).)  NOTE:  If an authentication mode without surrogate credentials is being used (Proxy or Origin authentication mode), then the Query Domain Controller and Client and Query Client options can cause too much traffic when querying the clients, as each authentication request results in a request to the BCAAA service, which can result in a client workstation query depending on the client query time-to-live.  If the client workstation querying traffic is a concern, the Query Domain Controllers options should be used instead.
    4. Click the OK button twice and make sure the "WinSSO" authentication object is displayed in the Action Column.
  4. Go to your existing Web Access Layer.  If you do not have a web access layer, create a new web access layer (Policy > Add Web Access Layer...).  If you have an existing web access layer, add a rule after your deny rules.  This assumes that your default policy is "Allow" and not deny.
  5. In the newly created rule, right click on the Source column and select Set... > Authenticated user > OK.  In the Action column, right click and select Allow.
  6. Install policy and test.

 

ADDITIONAL INFORMATION:

If you are running SGOS 5.x and you want to see what is included in the documentation on Windows SSO, please see Volume 4: Securing the Blue Coat ProxySG; Chapter 16: Windows Single Sign-on Authentication. For 6.2, see SGOS 6.2.x Administration Guide; Chapter 61: Windows Single Sign-on Authentication.


Rate this Page

Please take a moment to complete this form to help us better serve you.

Did this document help answer your question?
 
 
If you are finished providing feedback, please click the RATE CONTENT button. Otherwise, please add more detail in the following text box and then click RATE CONTENT.
 
 

Your response will be used to improve our document content.

Ask a Question