Name: SG

Text: Volume 4: Securing the Blue Coat SG Appliance

Contact Information
Blue Coat Systems Inc.
420 North Mary Ave
Sunnyvale, CA 94085-4121
http://www.bluecoat.com/support/contact.html
[email protected]
http://www.bluecoat.com
For concerns or feedback about the documentation: [email protected]

Copyright© 1999-2007 Blue Coat Systems, Inc. All rights reserved worldwide. No part of this document may be reproduced by any means
nor modified, decompiled, disassembled, published or distributed, in whole or in part, or translated to any electronic medium or other
means without the written consent of Blue Coat Systems, Inc. All right, title and interest in and to the Software and documentation are
and shall remain the exclusive property of Blue Coat Systems, Inc. and its licensors. ProxyAV™, CacheOS™, SGOS™, SG™, Spyware
Interceptor™, Scope™, RA Connector™, RA Manager™, Remote Access™ and MACH5™ are trademarks of Blue Coat Systems, Inc. and
CacheFlow®, Blue Coat®, Accelerating The Internet®, ProxySG®, WinProxy®, AccessNow®, Ositis®, Powering Internet Management®,
The Ultimate Internet Sharing Solution®, Cerberian®, Permeo®, Permeo Technologies, Inc.®, and the Cerberian and Permeo logos are
registered trademarks of Blue Coat Systems, Inc. All other trademarks contained in this document and in the Software are the property of
their respective owners.
BLUE COAT SYSTEMS, INC. DISCLAIMS ALL WARRANTIES, CONDITIONS OR OTHER TERMS, EXPRESS OR IMPLIED,
STATUTORY OR OTHERWISE, ON SOFTWARE AND DOCUMENTATION FURNISHED HEREUNDER INCLUDING WITHOUT
LIMITATION THE WARRANTIES OF DESIGN, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL BLUE COAT SYSTEMS, INC., ITS SUPPLIERS OR ITS LICENSORS BE LIABLE FOR
ANY DAMAGES, WHETHER ARISING IN TORT, CONTRACT OR ANY OTHER LEGAL THEORY EVEN IF BLUE COAT SYSTEMS,
INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Document Number: 231-02841
Document Revision: SGOS 5.2.2—09/2007

ii

Contents
Contact Information

Chapter 1: About Security
Controlling SG Appliance Access ...................................................................................................................11
Controlling User Access with Identity-based Access Controls ..................................................................11
SSL Between the SG Appliance and the Authentication Server.................................................................12
About This Book ................................................................................................................................................12
Document Conventions....................................................................................................................................13
Chapter 2: Controlling Access to the SG Appliance
Limiting Access to the SG Appliance .............................................................................................................15
Requiring a PIN for the Front Panel........................................................................................................15
Limiting Workstation Access ...................................................................................................................16
Securing the Serial Port .............................................................................................................................16
About Password Security.................................................................................................................................16
Limiting User Access to the SG Appliance—Overview ..............................................................................17
Moderate Security: Restricting Management Console Access Through the Console Access Control List
(ACL) ..........................................................................................................................................................19
Maximum Security: Administrative Authentication and Authorization Policy......................................20
Defining Administrator Authentication and Authorization Policies.................................................20
Defining Policies Using the Visual Policy Manager .............................................................................20
Defining Policies Directly in Policy Files................................................................................................21
Admin Transactions and Layers............................................................................................21
Example Policy Using CPL Syntax ..........................................................................................................24
Chapter 3: Controlling Access to the Internet and Intranet
Section A: Managing Users
About User Login ..............................................................................................................................................26
Viewing Logged-In Users ................................................................................................................................26
Logging Out Users ............................................................................................................................................27
Inactivity Timeout......................................................................................................................................27
Administrator Action ................................................................................................................................28
Policy............................................................................................................................................................28
Refreshing User Data .......................................................................................................................................28
Credential Refresh Time............................................................................................................................29
Authorization Refresh Time ....................................................................................................................29
Surrogate Refresh Time.............................................................................................................................30
Policy............................................................................................................................................................30

iii

Volume 4: Securing the Blue Coat SG Appliance

Related CLI Syntax to Manage Users............................................................................................................. 30
Section B: Using Authentication and Proxies
Understanding Authentication Modes................................................................................................... 32
Understanding Origin-Style Redirection ............................................................................................... 34
Selecting an Appropriate Surrogate Credential .................................................................................... 35
Configuring Transparent Proxy Authentication ................................................................................... 35
Permitting Users to Login with Authentication or Authorization Failures...................................... 37
Using Guest Authentication..................................................................................................................... 38
Using Default Groups ............................................................................................................................... 39
Section C: Using SSL with Authentication and Authorization Services
Using SSL Between the Client and the SG Appliance .......................................................................... 41
Section D: Creating a Proxy Layer to Manage Proxy Operations
Using CPL ................................................................................................................................................... 42
Chapter 4: Understanding and Managing X.509 Certificates
Section A: Concepts
Public Keys and Private Keys.......................................................................................................................... 52
Certificates.......................................................................................................................................................... 52
SSL Certificates........................................................................................................................................... 52
CA Certificates ........................................................................................................................................... 53
External Certificates................................................................................................................................... 53
Keyrings.............................................................................................................................................................. 53
Cipher Suites Supported by SGOS Software ................................................................................................ 53
Server-Gated Cryptography and International Step-Up............................................................................. 54
Section B: Using Keyrings and SSL Certificates
Creating a Keyring ............................................................................................................................................ 56
Deleting an Existing Keyring and Certificate ........................................................................................ 58
Section C: Managing Certificates
Managing Certificate Signing Requests......................................................................................................... 59
Creating a CSR ........................................................................................................................................... 59
Viewing a Certificate Signing Request ................................................................................................... 60
Managing SSL Certificates ............................................................................................................................... 60
Creating Self-Signed SSL Certificates ..................................................................................................... 61
Importing a Server Certificate.................................................................................................................. 62
Using Certificate Revocation Lists ................................................................................................................. 62
Troubleshooting Certificate Problems ........................................................................................................... 64
Section D: Using External Certificates
Importing and Deleting External Certificates............................................................................................... 65
Deleting an External Certificate............................................................................................................... 65
Digitally Signing Access Logs ......................................................................................................................... 66

iv

Contents

Section E: Advanced Configuration
Importing an Existing Keypair and Certificate............................................................................................. 67
About Certificate Chains.................................................................................................................................. 69
Importing a CA Certificate .............................................................................................................................. 69
Creating CA Certificate Lists........................................................................................................................... 70
Chapter 5: Certificate Realm Authentication
How Certificate Realm Works ........................................................................................................................ 73
Creating a Certificate Realm............................................................................................................................ 74
Defining a Certificate Realm ........................................................................................................................... 74
Defining Certificate Realm General Properties ............................................................................................ 75
Revoking User Certificates .............................................................................................................................. 76
Creating the Certificate Authorization Policy .............................................................................................. 77
Tips...................................................................................................................................................................... 78
Chapter 6: Oracle COREid Authentication
Understanding COREid Interaction with Blue Coat ................................................................................... 79
Configuring the COREid Access System....................................................................................................... 79
Additional COREid Configuration Notes ..................................................................................................... 80
Configuring the SG Realm............................................................................................................................... 80
Participating in a Single Sign-On (SSO) Scheme .......................................................................................... 81
Avoiding SG Appliance Challenges........................................................................................................ 81
Creating a COREid Realm ............................................................................................................................... 82
Configuring Agents .......................................................................................................................................... 82
Configuring the COREid Access Server ........................................................................................................ 83
Configuring the General COREid Settings.................................................................................................... 84
Creating the CPL ............................................................................................................................................... 86
Chapter 7: Forms-Based Authentication
Section A: Understanding Authentication Forms
User/Realm CPL Substitutions for Authentication Forms......................................................................... 93
Tip........................................................................................................................................................................ 94
Section B: Creating and Editing a Form
Section C: Setting Storage Options
Section D: Using CPL with Forms-Based Authentication
Tips.................................................................................................................................................................... 100
Chapter 8: IWA Realm Authentication and Authorization
How Blue Coat Works with IWA ................................................................................................................. 101
Creating an IWA Realm ................................................................................................................................ 101
IWA Servers ..................................................................................................................................................... 102
Defining IWA Realm General Properties .................................................................................................... 103
Creating the CPL ............................................................................................................................................. 107
Notes ................................................................................................................................................................. 107

v

Volume 4: Securing the Blue Coat SG Appliance

Chapter 9: LDAP Realm Authentication and Authorization
Overview .......................................................................................................................................................... 109
Creating an LDAP Realm .............................................................................................................................. 110
LDAP Servers .................................................................................................................................................. 111
Defining LDAP Base Distinguished Names ............................................................................................... 112
LDAP Search & Groups Tab (Authorization and Group Information) .................................................. 114
Customizing LDAP Objectclass Attribute Values...................................................................................... 116
Defining LDAP General Realm Properties.................................................................................................. 117
Creating the CPL ............................................................................................................................................. 119
Notes .......................................................................................................................................................... 120
Chapter 10: Local Realm Authentication and Authorization
Creating a Local Realm .................................................................................................................................. 121
Changing Local Realm Properties ................................................................................................................ 121
Notes .......................................................................................................................................................... 123
Defining the Local User List .......................................................................................................................... 123
Creating a Local User List....................................................................................................................... 123
Populating a List using the .htpasswd File .......................................................................................... 125
Uploading the .htpasswd File ............................................................................................................... 125
Populating a Local User List through the SG Appliance ................................................................... 126
Enhancing Security Settings for the Local User List........................................................................... 128
Creating the CPL ............................................................................................................................................. 129
Chapter 11: Policy Substitution Realm
How Policy Substitution Realms Work ....................................................................................................... 131
Creating a Policy Substitution Realm .......................................................................................................... 134
Configuring User Information ...................................................................................................................... 134
Creating a List of Users to Ignore ................................................................................................................. 136
Configuring Authorization............................................................................................................................ 137
Defining Policy Substitution Realm General Properties ........................................................................... 138
Notes .......................................................................................................................................................... 139
Creating the Policy Substitution Policy ....................................................................................................... 140
Using Single Sign-On Realms and Proxy Chains................................................................................ 141
Chapter 12: CA eTrust SiteMinder Authentication
Understanding SiteMinder Interaction with Blue Coat ............................................................................ 143
Configuring the SiteMinder Policy Server ........................................................................................... 143
Additional SiteMinder Configuration Notes ....................................................................................... 144
Configuring the SG Realm...................................................................................................................... 145
Participating in a Single Sign-On (SSO) Scheme ........................................................................................ 145
Avoiding SG Appliance Challenges...................................................................................................... 146
Creating a SiteMinder Realm ....................................................................................................................... 146
Configuring Agents ................................................................................................................................. 146
Configuring SiteMinder Servers ................................................................................................................... 147
Defining SiteMinder Server General Properties......................................................................................... 148

vi

Contents

Configuring General Settings for SiteMinder...................................................................................... 150
Creating the CPL ............................................................................................................................................. 153
Chapter 13: RADIUS Realm Authentication and Authorization
Creating a RADIUS Realm............................................................................................................................. 156
Defining RADIUS Realm Properties ............................................................................................................ 156
Defining RADIUS Realm General Properties ............................................................................................. 158
Creating the Policy.......................................................................................................................................... 160
Fine-Tuning RADIUS Realms ................................................................................................................ 160
Creating RADIUS Groups ...................................................................................................................... 161
CPL Example ............................................................................................................................................ 162
Troubleshooting .............................................................................................................................................. 162
Notes ................................................................................................................................................................. 162
Chapter 14: Novell Single Sign-on Authentication and Authorization
How Novell SSO Realms Work .................................................................................................................... 164
How Novell SSO Authorization Works ............................................................................................... 164
Creating a Novell SSO Realm ....................................................................................................................... 165
Novell SSO Agents.......................................................................................................................................... 165
Adding LDAP Servers to Search and Monitor ........................................................................................... 167
Querying the LDAP Search Realm ............................................................................................................... 168
Configuring Authorization............................................................................................................................ 169
Defining Novell SSO Realm General Properties ........................................................................................ 169
Modifying the sso.ini File for Novell SSO Realms ..................................................................................... 171
Creating the CPL ............................................................................................................................................. 172
Using Single Sign-On Realms and Proxy Chains................................................................................ 172
Notes ................................................................................................................................................................. 173
Chapter 15: Sequence Realm Authentication
Adding Realms to a Sequence Realm........................................................................................................... 175
Creating a Sequence Realm ........................................................................................................................... 176
Adding Realms to a Sequence Realm........................................................................................................... 176
Defining Sequence Realm General Properties ........................................................................................... 178
Tips.................................................................................................................................................................... 179
Chapter 16: Windows Single Sign-on Authentication
How Windows SSO Realms Work ............................................................................................................... 181
How Windows SSO Works with BCAAA............................................................................................ 182
BCAAA Synchronization........................................................................................................................ 182
How Windows SSO Authorization Works .......................................................................................... 183
Creating a Windows SSO Realm ................................................................................................................. 183
Windows SSO Agents..................................................................................................................................... 184
Configuring Authorization............................................................................................................................ 185
Defining Windows SSO Realm General Properties ................................................................................... 186
Modifying the sso.ini File for Windows SSO Realms ................................................................................ 188

vii

Volume 4: Securing the Blue Coat SG Appliance

Using Single Sign-On Realms and Proxy Chains................................................................................ 190
Notes ................................................................................................................................................................. 191
Chapter 17: Using XML Realms
About XML Realms ........................................................................................................................................ 193
Before Creating an XML Realm .................................................................................................................... 194
Creating an XML Realm................................................................................................................................. 194
Configuring XML Servers.............................................................................................................................. 195
Configuring XML Options............................................................................................................................. 196
Configuring XML Realm Authorization...................................................................................................... 196
Configuring XML General Realm Properties.............................................................................................. 198
Creating the CPL ............................................................................................................................................. 200
Viewing Statistics ............................................................................................................................................ 200
Appendix A: Glossary
Appendix B: Using the Authentication/Authorization Agent
Using the BCAAA Service ............................................................................................................................. 215
Performance Notes .................................................................................................................................. 216
Installing the BCAAA Service on a Windows System............................................................................... 217
Notes on SSL and Systems Running pre-Windows 2003................................................................... 222
Notes on SSL and Systems Running Windows 2003 and Later ........................................................ 222
Installing the BCAAA Service on a Solaris System.................................................................................... 222
Creating Service Principal Names for IWA Realms................................................................................... 223
Troubleshooting Authentication Agent Problems ..................................................................................... 225
Common BCAAA Event Messages .............................................................................................................. 225
Appendix C: Managing the SSL Client
Understanding the SSL Client....................................................................................................................... 233
Creating an SSL Client.................................................................................................................................... 233
Associating a Keyring and Protocol with the SSL Client .......................................................................... 233
Changing the Cipher Suites of the SSL Client ..................................................................................... 234
Troubleshooting Server Certificate Verification.................................................................................. 237
Setting the SSL Negotiation Timeout ........................................................................................................... 237
Appendix D: XML Protocol
Section A: Authenticate Request
GET Method (User Credentials in Request)................................................................................................ 240
GET Method (User Credentials in Headers) ............................................................................................... 240
POST Method (User Credentials in Request).............................................................................................. 240
POST Method (User Credentials in Headers)............................................................................................. 240
Section B: Authenticate Response
Success .............................................................................................................................................................. 242
Failed/Denied ................................................................................................................................................. 242

viii

Contents

Section C: Authorize Request
GET Method..................................................................................................................................................... 244
POST Method................................................................................................................................................... 244
Section D: Authorize Response
Success .............................................................................................................................................................. 245
Failed................................................................................................................................................................. 245
Appendix E: Authentication and Authorization Errors
Index

ix

Volume 4: Securing the Blue Coat SG Appliance

x

Chapter 1: About Security

Enterprise-wide security begins with security on the SG appliance, and continues with
controlling user access to the Intranet and Internet.
SSH and HTTPS are the recommended (and default) methods for managing access to
the SG appliance. SSL is the recommended protocol for communication between the
appliance and a realm's off-box authentication server.

Controlling SG Appliance Access
You can control access to the SG appliance several ways: by limiting physical access to
the system, by using passwords, restricting the use of console account, through peruser RSA public key authentication, and through Blue Coat Content Policy Language
(CPL). How secure the system needs to be depends upon the environment.
You can limit access to the SG appliance by:


Restricting physical access to the system and by requiring a PIN to access the front
panel.



Restricting the IP addresses that are permitted to connect to the SG appliance CLI.



Requiring a password to secure the Setup Console.

These methods are in addition to the restrictions placed on the console account (a
console account user password) and the Enable password. For information on using the
console account, refer to Volume 1: Getting Started.
By using every possible method (physically limiting access, limiting workstation IP
addresses, and using passwords), the SG appliance is very secure.
Once the SG appliance is secure, you can limit access to the Internet and intranet. It is
possible to control access to the network without using authentication. You only need
to use authentication if you want to use identity-based access controls.

Controlling User Access with Identity-based Access Controls
The SG appliance provides a flexible authentication architecture that supports multiple
services with multiple backend servers (for example, LDAP directory servers together
with NT domains with no trust relationship) within each authentication scheme with
the introduction of the realm.
A realm authenticates and authorizes users for access to SG services using either explicit
proxy or transparent proxy mode, discussed in Volume 2: Proxies and Proxy Services.
Multiple authentication realms can be used on a single SG appliance. Multiple realms
are essential if the enterprise is a managed provider or the company has merged with
or acquired another company. Even for companies using only one protocol, multiple
realms might be necessary, such as the case of a company using an LDAP server with
multiple authentication boundaries. You can use realm sequencing to search the
multiple realms all at once.

11

Volume 4: Securing the Blue Coat SG Appliance

A realm configuration includes:


Realm name.



Authentication service—(IWA, LDAP, RADIUS, Local, Certificate, Sequences, CA
eTrust SiteMinder®, Oracle COREid™, Policy Substitution, Windows SSO, Novell
SSO).



External server configuration—Backend server configuration information, such as
host, port, and other relevant information based on the selected service.



Authentication schema—The definition used to authenticate users.



Authorization schema—The definition used to authorize users for membership in
defined groups and check for attributes that trigger evaluation against any defined
policy rules.



One-time passwords are supported for RADIUS realms only.

You can view the list of realms already created by clicking Configuration > Authentication >
Realms. Realms are created on the home page for each realm.

SSL Between the SG Appliance and the Authentication Server
SSL communication between the SG appliance and LDAP and IWA authentication servers
is supported. In addition, you can also use SSL between the client and the SG appliance.
For more information on using SSL between the client and the appliance, see “Using SSL
with Authentication and Authorization Services” on page 41.
Configuring a realm to use SSL between the SG appliance and the authentication server is
performed on a per-realm basis. Part of the SSL configuration is specifying whether to
verify the server's certificate. If the server certificate is to be verified, then the server's
certificate must be signed by a Certificate Authority that the SG appliance trusts, and the
common name in the server certificate must match the server host as specified in the
realm configuration.
The realms use the default SSL client defined on the SG appliance for SSL
communications to the authentication servers.
Note: If the browser is configured for on-line checking of certificate revocation, the
status check must be configured to bypass authentication.

About This Book
The first few chapters of Volume 4: Securing the Blue Coat SG Appliance deal with limiting
access to the SG appliance . The remainder of the book discusses the various realms:


Chapter 2: "Controlling Access to the SG Appliance"



Chapter 3: "Controlling Access to the Internet and Intranet"



Chapter 4: "Understanding and Managing X.509 Certificates"



Chapter 5: "Certificate Realm Authentication"



Chapter 6: "Oracle COREid Authentication"



Chapter 7: "Forms-Based Authentication"



Chapter 8: "IWA Realm Authentication and Authorization"



Chapter 9: "LDAP Realm Authentication and Authorization"

12

Chapter 1: About Security



Chapter 10: "Local Realm Authentication and Authorization"



Chapter 11: "Policy Substitution Realm"



Chapter 12: "CA eTrust SiteMinder Authentication"



Chapter 13: "RADIUS Realm Authentication and Authorization"



Chapter 14: "Novell Single Sign-on Authentication and Authorization"



Chapter 15: "Sequence Realm Authentication"



Chapter 16: "Windows Single Sign-on Authentication"



Chapter 17: "Using XML Realms"



Appendix A: "Glossary"



Appendix D: "XML Protocol"



Appendix C: "Managing the SSL Client"



Appendix B: "Using the Authentication/Authorization Agent"

Document Conventions
The following section lists the typographical and Command Line Interface (CLI) syntax
conventions used in this manual.
Table 1-1. Document Conventions
Conventions

Definition

Italics

The first use of a new or Blue Coat-proprietary term.

Courier font

Command line text that appears on your administrator workstation.

Courier Italics

A command line variable that is to be substituted with a literal name or
value pertaining to the appropriate facet of your network system.

Courier Boldface

A Blue Coat literal to be entered as shown.

{ }

One of the parameters enclosed within the braces must be supplied

[ ]

An optional parameter or parameters.

|

Either the parameter before or after the pipe character can or must be
selected, but not both.

13

Volume 4: Securing the Blue Coat SG Appliance

14

Chapter 2: Controlling Access to the SG Appliance

You can control access to the SG appliance several ways: by limiting physical access to
the system, by using passwords, restricting the use of console account, through peruser RSA public key authentication, and through Blue Coat Content Policy Language
(CPL). How secure the system needs to be depends upon the environment.
This section contains:


“Limiting Access to the SG Appliance”



“About Password Security” on page 16



“Limiting User Access to the SG Appliance—Overview” on page 17



“Moderate Security: Restricting Management Console Access Through the Console
Access Control List (ACL)” on page 19



“Maximum Security: Administrative Authentication and Authorization Policy” on
page 20

Limiting Access to the SG Appliance
You can limit access to the SG appliance by:


Restricting physical access to the system and by requiring a PIN to access the front
panel.



Restricting the IP addresses that are permitted to connect to the SG appliance CLI.



Requiring a password to secure the Setup Console.

These methods are in addition to the restrictions placed on the console account (a
console account user password) and the Enable password. For information on using the
console account, refer to Volume 1: Getting Started.
By using every possible method (physically limiting access, limiting workstation IP
addresses, and using passwords), the SG appliance is very secure.
This section discusses:


“Requiring a PIN for the Front Panel”



“Limiting Workstation Access” on page 16



“Securing the Serial Port” on page 16

Requiring a PIN for the Front Panel
On systems that have a front panel display, you can create a four-digit PIN to protect
the system from unauthorized use. The PIN is hashed and stored. You can only create a
PIN from the command line.
To create a front panel PIN, after initial configuration is complete:
From the (config) prompt:
SGOS#(config) security front-panel-pin PIN

where PIN is a four-digit number.

15

Volume 4: Securing the Blue Coat SG Appliance

To clear the front-panel PIN, enter:
SGOS#(config) security front-panel-pin 0000

Limiting Workstation Access
During initial configuration, you have the option of preventing workstations with
unauthorized IP addresses from accessing the CLI. If this option is not enabled, all
workstations are allowed to access the CLI. You can also add allowed workstations later to
the access control list (ACL). (For more information on limiting workstation access, see
“Moderate Security: Restricting Management Console Access Through the Console
Access Control List (ACL)” on page 19.)

Securing the Serial Port
If you choose to secure the serial sort, you must provide a Setup Console password that is
required to access the Setup Console in the future.
Once the secure serial port is enabled:


The Setup Console password is required to access the Setup Console.



An authentication challenge (username and password) is issued to access the CLI
through the serial port.

To recover from a lost Setup Console password, you can:


Use the Front Panel display to either disable the secure serial port or enter a new
Setup Console password.



Use the CLI restore-defaults factory-defaults command to delete all system
settings. For information on using the restore-defaults factory-defaults
command, refer to Volume 9: Managing the Blue Coat SG Appliance.



Use the reset button (if the appliance has a reset button) to delete all system settings.

To enable the secure serial port, refer to the Installation Guide for your platform.

About Password Security
In the SG appliance, the console administrator password, the Setup Console password,
and Enable (privileged-mode) password are hashed and stored. It is not possible to
reverse the hash to recover the plaintext passwords.
In addition, the show config and show security CLI commands display these
passwords in their hashed form. The length of the hashed password depends on the hash
algorithm used so it is not a fixed length across the board.
Passwords that the SG appliance uses to authenticate itself to outside services are
encrypted using triple-DES on the appliance, and using RSA public key encryption for
output with the show config CLI command. You can use a third-party encryption
application to create encrypted passwords and copy them into the SG appliance using an
encrypted-password command (which is available in several modes and described in
those modes). If you use a third-party encryption application, verify it supports RSA
encryption, OAEP padding, and Base64 encoded with no new lines.
These passwords, set up during configuration of the external service, include:


Access log FTP client passwords (primary, alternate)—For configuration information,
refer to Volume 8: Access Logging.

16

Chapter 2: Controlling Access to the SG Appliance



Archive configuration FTP password—For configuration information, refer to the
archive configuration information in Volume 1: Getting Started.



RADIUS primary and alternate secret—For configuration information, see
Chapter 13: "RADIUS Realm Authentication and Authorization".



LDAP search password—For configuration information, see “LDAP Search & Groups
Tab (Authorization and Group Information)” on page 114.



Content filter download passwords—For configuration information, refer to the
content filtering information in Volume 7: Managing Content.

Limiting User Access to the SG Appliance—Overview
When deciding how to give other users read-only or read-write access to the SG
appliance, sharing the basic console account settings is only one option. The following
summarizes all available options:
Note: If Telnet Console access is configured, Telnet can be used to manage the SG
appliance with behavior similar to SSH with password authentication.

SSL configuration is not allowed through Telnet, but is permissible through SSH.
Behavior in the following sections that applies to SSH with password authentication also
applies to Telnet. Use of Telnet is not recommended because it is not a secure protocol.


Console account—minimum security
The console account username and password are evaluated when the SG appliance is
accessed from the Management Console through a browser and from the CLI through
SSH with password authentication. The Enable (privileged-mode) password is
evaluated when the console account is used through SSH with password
authentication and when the CLI is accessed through the serial console and through
SSH with RSA authentication. The simplest way to give access to others is sharing this
basic console account information, but it is the least secure and is not recommended.
To give read-only access to the CLI, do not give out the Enable (privileged-mode)
password.



Console access control list—moderate security
Using the access control list (ACL) allows you to further restrict use of the console
account and SSH with RSA authentication to workstations identified by their IP
address and subnet mask. When the ACL is enforced, the console account can only be
used by workstations defined in the console ACL. Also, SSH with RSA authentication
connections are only valid from workstations specified in the console ACL (provided
it is enabled).
After setting the console account username, password, and Enable (privileged-mode)
password, use the CLI or the Management Console to create a console ACL. See
“Moderate Security: Restricting Management Console Access Through the Console
Access Control List (ACL)” on page 19.



Per-user RSA public key authentication—moderate security
Each administrator’s public keys are stored on the appliance. When connecting
through SSH, the administrator logs in with no password exchange. Authentication
occurs by verifying knowledge of the corresponding private key. This is secure
because the passwords never go over the network.

17

Volume 4: Securing the Blue Coat SG Appliance

This is a less flexible option than CPL because you cannot control level of access with
policy, but it is a better choice than sharing the console credentials.


Blue Coat Content Policy Language (CPL)—maximum security
CPL allows you to control administrative access to the SG appliance through policy. If
the credentials supplied are not the console account username and password, policy is
evaluated when the SG appliance is accessed through SSH with password
authentication or the Management Console. Policy is never evaluated on direct serial
console connections or SSH connections using RSA authentication.


Using the CLI or the Management Console GUI, create an authentication realm to
be used for authorizing administrative access. For administrative access, the realm
must support BASIC credentials—for example, LDAP, RADIUS, Local, or IWA
with BASIC credentials enabled.



Using the Visual Policy Manager, or by adding CPL rules to the Local or Central
policy file, specify policy rules that: (1) require administrators to log in using
credentials from the previously-created administrative realm, and (2) specify the
conditions under which administrators are either denied all access, given readonly access, or given read-write access. Authorization can be based on IP address,
group membership, time of day, and many other conditions. For more
information, refer to Volume 6: VPM and Advanced Policy.



To prevent anyone from using the console credentials to manage the SG
appliance, set the console ACL to deny all access (unless you plan to use SSH with
RSA authentication). For more information, see “Moderate Security: Restricting
Management Console Access Through the Console Access Control List (ACL)” on
page 19. You can also restrict access to a single IP address that can be used as the
emergency recovery workstation.

The following chart details the various ways administrators can access the SG console and
the authentication and authorization methods that apply to each.
Table 2-1. SG Console Access Methods/Available Security Measures
Security Measures Available

Serial
Console

SSH with
Password
Authentication

Username and password evaluated
(console-level credentials)

3

Console Access List evaluated

3

CPL Layer evaluated

SSH with RSA
Authentication

3
3

3(if console

(if console
credentials are
offered)

credentials are
offered)

3(see Note 1
below)

3(see Note 2
below)

Enable password required to enter
privileged mode (see Note 2 below)

3

3

3

CLI line-vty timeout command
applies.

3

3

3

Management Console Login/Logout

Management
Console

3

18

Volume 4: Securing the Blue Coat SG Appliance

Related CLI Syntax to Create an ACL
SGOS#(config) security allowed-access add ip_address [subnet_mask]
SGOS#(config) security enforce-acl enable | disable
SGOS#(config) security allowed-access remove ip_address [subnet_mask]

Maximum Security: Administrative Authentication and Authorization Policy
The SG appliance permits you to define a rule-based administrative access policy. This
policy is enforced when accessing:


the Management Console through http or https



the CLI through SSH when using password authentication



the CLI through telnet



the CLI through the serial port if the secure serial port is enabled

These policy rules can be specified either by using the VPM or by editing the Local policy
file. Using policy rules, you can deny access, allow access without providing credentials,
or require administrators to identify themselves by entering a username and password. If
access is allowed, you can specify whether read-only or read-write access is given. You
can make this policy contingent on IP address, time of day, group membership (if
credentials were required), and many other conditions.
Serial-console access is not controlled by policy rules. For maximum security to the serial
console, physical access must be limited.
SSH with RSA authentication also is not controlled by policy rules. You can configure
several settings that control access: the enable password, the console ACL, and per-user
keys configured through the Configuration > Services > SSH > SSH Client page. (If you use
the CLI, SSH commands are under config > services > ssh-console.)

Defining Administrator Authentication and Authorization Policies
The SG appliance uses CPL to define policies, including administrator, authentication,
and authorization policies. CPL also allows you to give administrator privileges to users
in any external authentication service.
The following summarizes the steps required to define Administrator Authentication and
Authorization policies on the SG appliance:


(Optional) If you need to give administrative access to existing users or groups, create
and configure the authentication realm.



Define the policies in the appropriate policy file where you keep the Layer
layers and rules.



Load the policy file on the SG appliance.

When you define such policies, make sure you define them in the appropriate policy
file(s). For more information on policy files and how they are used, refer to Volume 6: VPM
and Advanced Policy.

Defining Policies Using the Visual Policy Manager
To define policies through the Management Console, use the Visual Policy Manager.
When you use the VPM, policies are configured in CPL and saved in the VPM policy file.
For examples of Administrator authentication or authorization policy CPL, continue with
the next section. The VPM is described in detail in Volume 6: VPM and Advanced Policy.

20

Chapter 2: Controlling Access to the SG Appliance

Defining Policies Directly in Policy Files
To define policies manually, type CPL rules directly in one of the two policy files, Central
or Local.
Important: For specific information on creating policies within the policy files, refer
to Volume 10: Blue Coat SG Appliance Content Policy Language Guide.
Following are the CPL elements that can be used to define administrator policies for the
SG appliance.
To define administrator policies by editing a policy file:
1.

Open the policy file in a text editor.

2.

Define the policies, using the correct CPL syntax.

3.

Save the file.

4.

Load the policy file (refer to Volume 6: VPM and Advanced Policy).

Admin Transactions and Layers
Admin transactions execute layers. Only a restricted set of conditions, properties,
and actions are permitted in layers. The table below lists the conditions
permitted in the layer.
Table 2-2. Network Connection Conditions
Network Connection Conditions
client_address=ip_address
[.subnetmask]

Tests for a match between ip_address and the IP address of
the client transaction source.

proxy.port=number

Tests for a match between number and the port number for
which the request is destined.

proxy.address=ip_address

Tests for a match between ip_address and the IP address of
the network interface card for which the request is destined.

proxy.card=number

Tests for a match between number and the ordinal number
associated with the network interface card for which the request
is destined.

General Conditions
condition=condition.label

Tests if the specified defined condition is true.

release.id=

Tests the SG release id.

Date/Time Conditions
date[.utc]=[date | date…date]

Tests for a match between date and the date timestamp
associated with the source of the transaction. date specifies a
single date of the form YYYY-MM-DD or an inclusive range, as in
YYYY-MM-DD…YYYY-MM-DD. By default, date is calculated based
on local time. To calculate year based on the Coordinated
Universal Time, include the .utc qualifier

21

Volume 4: Securing the Blue Coat SG Appliance

Table 2-2. Network Connection Conditions (Continued)
year[.utc]=[year | year…year]

Tests for a match between year and the year timestamp
associated with the source of the transaction. year specifies a
single Gregorian calendar year of the form YYYY or an inclusive
range of years, as in YYYY…YYYY. By default, year is calculated
based on local time. To calculate year based on the Coordinated
Universal Time, include the .utc qualifier.

month[.utc]=[month | month…month]

Tests for a match between month and the month timestamp
associated with the source of the transaction. month specifies a
single Gregorian calendar month of the form MM or an inclusive
range of months, as in MM…MM. By default, month is calculated
based on local time. To calculate month based on the
Coordinated Universal Time, include the .utc qualifier.

weekday[.utc]=[number |
number…number]

Tests for a match between weekday and the weekday timestamp
associated with the source of the transaction. weekday specifies
a single day of the week (where Monday=1, Tuesday=2, and
Sunday=7) or an inclusive range of weekdays, as in
number…number. By default, weekday is calculated based on
local time. To calculate weekday based on the Coordinated
Universal Time, include the .utc qualifier.

day[.utc]=[day | day…day]

Tests for a match between day and the day timestamp
associated with the source of the transaction. day specifies a
single Gregorian calendar day of the month of the form DD or
an inclusive range of days, as in DD…DD. By default, day is
calculated based on local time. To calculate day based on the
Coordinated Universal Time, include the .utc qualifier.

hour[.utc]=[hour | hour…hour]

Tests for a match between hour and the hour timestamp
associated with the source of the transaction. hour specifies a
single Gregorian hour of the form HH (00, 01, and so forth,
through 23) or an inclusive range of hours, as in HH…HH. By
default, hour is calculated based on local time. To calculate hour
based on the Coordinated Universal Time, include the .utc
qualifier.

minute[.utc]=[minute |
minute…minute]

Tests for a match between minute and the minute timestamp
associated with the source of the transaction. minute specifies a
single Gregorian minute of the form MM (00, 01, and so forth,
through 59) or an inclusive range of minutes, as in MM…MM. By
default, minute is calculated based on local time. To calculate
minute based on the Coordinated Universal Time, include
the .utc qualifier.

time[.utc]=[time | time…time]

Tests for a match between time and the time timestamp
associated with the source of the transaction. time specifies
military time of the form TTTT (0000 through 2359) or an
inclusive range of times, as in TTTT…TTTT. By default, time is
calculated based on local time. To calculate time based on the
Coordinated Universal Time, include the .utc qualifier.

Authorization Conditions
attribute.name =value

Tests if the current transaction is authorized in a RADIUS or
LDAP realm, and if the authenticated user has the specified
attribute with the specified value. This trigger is unavailable if
the current transaction is not authenticated

22

Chapter 2: Controlling Access to the SG Appliance

Table 2-2. Network Connection Conditions (Continued)
authenticated={yes | no}

Tests if authentication was requested and the credentials could
be verified.

group=group_name

If authenticate=yes, the group condition tests the source of
the transaction for membership in the specified groupname.

has_attribute.name=boolean

Tests if the current transaction is authorized in an LDAP realm
and if the authenticated user has the specified LDAP attribute.

realm=realm_name

If authenticate=yes, the realm condition tests the source of
the transaction for membership in the specified realm name.

user=username

If authenticate=yes, the user condition tests the source of
the transaction for the expected username.

user.domain=
windows_domain_name

(This condition is IWA-realm specific.) If authenticate=yes,
the user_domain condition tests whether the realm type is IWA
and whether the domain component of the username is the
expected domain name.

Read-only or Read-write Conditions
admin_access=read | write

read tests whether the source of the transaction has read-only
permission for the SG console. write tests whether the source
has read-write permission.
When an Administrator logs into the CLI, the SG appliance
executes an transaction that includes the condition
admin_access=read. If the transaction is ultimately allowed
(all conditions have been met), the user will have read-only
access to configuration information through the CLI. Further,
when that user executes the CLI enable command, or logs into
the Management Console, the SG appliance executes an
transaction with admin_access=write. If the
transaction is allowed, the user will have read-write access
within the CLI or the Management Console.

The table below lists the properties permitted in the layer:
Table 2-3. Properties in the Layer
Properties
deny

Refuse service to the source of the transaction.

authenticate(realm_name)

Requests authentication of the transaction source for the
specified realm.

authenticate.force( )

If yes is specified then forces authentication even if the
transaction is denied. This results in the user information
being available for logging. If no, then early denial
without authentication is possible.

allow

Permit further service to the source of the transaction.

log.suppress.field-id ( )

Controls suppression of the specified field-id in all
facilities

log.suppress.field-id[log_list]( )

Controls suppression of the specified field-id in the
specified facilities.

23

Volume 4: Securing the Blue Coat SG Appliance

Table 2-3. Properties in the Layer (Continued)
log.rewrite.field-id( )

Controls rewrites of a specific log field in all facilities.

log.rewrite.field-id[log_list]
( )

Controls rewrites of a specific log field in a specified list of
log facilities.

The table below lists the actions permitted in the layer:
Table 2-4. Actions permitted in the Layer
Actions
notify_email( )

Sends an e-mail notification to the list of recipients specified in the
Event Log mail configuration when the transaction terminates.

notify_snmp( )

The SNMP trap is sent when the transaction terminates.

Example Policy Using CPL Syntax
To authenticate users against an LDAP realm, use the following syntax in the Local Policy
file:

authenticate(LDAP_Realm)

group="cn=Administrators,cn=Groups,dc=bluecoat,dc=com" allow

This authenticates users against the specified LDAP realm. If the users are successfully
authenticated and belong to group Administrators, they are allowed to administer the
SG appliance.

24

Chapter 3: Controlling Access to the Internet and Intranet

After you have physically secured the SG appliance and limited access to it through
passwords, you can limit users’ access to the Internet and intranet.
This chapter includes the following sections:


Section A: "Managing Users" on page 26



Section B: "Using Authentication and Proxies" on page 32



Section C: "Using SSL with Authentication and Authorization Services" on page 41



Section D: "Creating a Proxy Layer to Manage Proxy Operations" on page 42

25

Chapter 3: Controlling Access to the Internet and Intranet

Section A: Managing Users

Section A: Managing Users
When a user is first authenticated to an SG appliance, a user login is created. You can view
users who are logged in and configure the SG appliance to log them out and refresh their
data.
This section includes the following topics:


“About User Login” on page 26



“Viewing Logged-In Users” on page 26



“Logging Out Users” on page 27



“Refreshing User Data” on page 28



“Related CLI Syntax to Manage Users” on page 30

About User Login
A user login is the combination of:


An IP address



A username



A realm

For a specific realm, a user is only considered to be logged in once from a given
workstation, even if using multiple user agents. However:


If policy authenticates the user against multiple realms, the user is logged in once for
each realm.



If a user logs in from multiple workstations, the user is logged in once per
workstation.



If multiple users share an IP address (same server, terminal services, or are behind a
NAT, which allows a local-area network to use one set of IP addresses), each user is
logged in once.



If a user logs in from multiple workstations behind a NAT, the user is logged in once.

Viewing Logged-In Users
You can browse all users logged into the SG appliance. You can also filter the displayed
users by Glob-username pattern, by IP address subnet, and by realm.
The glob-based username pattern supports three operators:


'*' : match zero or more characters



'?' : match exactly one character



'[x-y]': match any character in the character range from 'x' to 'y'

The IP address subnet notation is based on Classless Inter-Domain_Routing (CIDR), a
way of interpreting IP addresses, as follows:


1.2.3.4 : the IP address 1.2.3.4



1.2.3.0/24: the subnet 1.2.3.0 with netmask 255.255.255.0

The realm selection allows an exact realm name or All realms to be selected.

26

Chapter 3: Controlling Access to the Internet and Intranet

Section A: Managing Users

Administrator Action
The administrator can explicitly log out a set of users using the Logout link at the bottom
of the user login information pages. See “Viewing Logged-In Users” on page 26 for
information about displaying user login information. For information about using the CLI
to logout users, see “Related CLI Syntax to Manage Users” on page 30.

Policy
Policy has three properties and three conditions to manage user logouts. These properties
and conditions can be used to dynamically log out users. For example, you can create a
logout link for users.
For information about using policy, refer to Volume 6: VPM and Advanced Policy and
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.

New Properties
Policy has three properties for logging out users.


user.login.log_out(yes)

This property logs out the user referenced by the current transaction.


user.login.log_out_other(yes)

If a user is logged in at more than one IP address, this property logs the user out from
all IP addresses except the current IP address.


client.address.login.log_out_other(yes)

If more than one user is logged in at the IP address of the current transaction, this
property logs out all users from the current IP address except the current user.

New Conditions
Several conditions support different logout policies.


user.login.count

This condition matches the number of times that a specific user is logged in with the
current realm. You can use this condition to ensure that a user can be logged in only at
one workstation. If the condition is combined with the user.login.log_out_other
property, old login sessions on other workstations are automatically logged out.


client.address.login.count

This condition matches the number of different users who are logged into the current
IP address, and you can use it to limit the user number.


user.login.time

This condition matches the number of seconds since the current login started, and you
can use it to limit the length of a login session.

Refreshing User Data
You can refreshing user data with the following refresh-time options on the SG appliance:


Credential refresh time: This option specifies how long a cached username and
password is trusted (do not require revalidation).

28

Chapter 3: Controlling Access to the Internet and Intranet

Section A: Managing Users


Surrogate refresh time: This option specifies how long surrogate credentials are
trusted in a particular realm.



Authorization refresh time: This option specifies how long authorization data, such as
groups and attributes, are trusted.

While the realms have the baseline settings for the different refresh times, policy and
administrator actions can override the realm settings. Using the same interface and filters
as used for viewing logins, the administrator can select logins and refresh the
authorization data, the credentials, or the surrogates using the links available on the user
login information page. Refreshing user data might be necessary if users are added to new
groups or there is concern about the actual identity of the user on a long-lived IP
surrogate.

Credential Refresh Time
You can set the credential refresh time with realms that can cache the username and
password on the SG appliance. This is limited to realms that use Basic username and
password credentials, including LDAP, RADIUS, XML, IWA (with Basic credentials),
SiteMinder, and COREid.
Note:

The local realm uses Basic credentials but does not need to cache them since
they are stored already on the appliance.

Cached Usernames and Passwords
You can use a cached username and password to verify a user's credentials without
having to verify the credentials with the offbox authentication server. Essentially, this
reduces the load on the authentication server. For authentication modes that do not use
surrogate credentials (that is, proxy or origin modes), this can greatly reduce the traffic to
the authentication server.
The credential refresh time value determines how long a cached username and password
is trusted. After that time has expired, the next transaction that needs credential
authentication sends a request to the authentication server. A password different than the
cached password also results in a request to the authentication server.

One-Time Passwords
One-time passwords are trusted for the credential refresh time. Only when the credential
refresh time expires is the user challenged again.

Authorization Refresh Time
Realms (Local, LDAP, Windows SSO, Novell SSO, Certificate, XML, and Policy
Substitution) that can do authorization and authentication separately can use the
authorization refresh time value to manage the load on the authorization server.
These realms determine authorization data (group membership and attribute values)
separately from authentication, allowing the time the authorization data is trusted to be
increased or decreased
For realms that must authenticate the user to determine authorization data, the
authorization data is updated only when the user credentials are verified by the
authentication server.

29

Chapter 3: Controlling Access to the Internet and Intranet

Section A: Managing Users

Surrogate Refresh Time
This value manages how long surrogate credentials are trusted in a particular realm. The
authentication mode determines the type of surrogate that is used.


Cookie surrogates are used with one of the cookie authentication modes; IP address
surrogates are used with one of the IP authentications modes; and the Auto
authentication mode attempts to select the best surrogate for the current transaction.



IP address surrogates work with all user agents, but require that each workstation has
a unique IP address; they do not work with users behind a NAT. An IP surrogate
authenticates all transactions from a given IP address as belonging to the user who
was last authenticated at that IP address.

When a user is logged out, all surrogates are discarded, along with the cached credentials
and authorization data.
For more information about using cookie and IP address surrogates, see “Understanding
Authentication Modes” on page 32.

Policy
Policy has three properties for setting the refresh times for individual transactions.


authenticate.authorization_refresh_time(x)

where x is the number of seconds to use for the authorization refresh time during this
transaction. The refresh time cannot exceed the time configured in the realm; policy
can be used only to reduce the authorization refresh time. You can use this property to
dynamically force the user's authorization data to be refreshed.


authenticate.credential_refresh_time(x)

where x is the number of seconds to use for the credential refresh time during this
transaction. The refresh time cannot exceed the time configured in the realm; policy
can be used only to reduce the credential refresh time. You can use this property to
dynamically force the user's credentials to be refreshed.


authenticate.surrogate_refresh_time(x)

where x is the number of seconds to use for the surrogate refresh time during this
transaction. The refresh time cannot exceed the time configured in the realm; policy
can be used only to reduce the surrogate refresh time. You can use this property to
dynamically force the user's surrogate to be refreshed.
For information about using policy, refer to Volume 6: VPM and Advanced Policy and
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.

Related CLI Syntax to Manage Users


To enter the manage users submode, use the following commands:
SGOS#(config) security users
SGOS#(config users)



The following commands are available:
(config users) authorization-refresh {ip-addresses prefix [realm_name]
| realms [realm_name]| users glob_user_name [realm_name]}
(config users) credentials-refresh {ip-addresses prefix [realm_name] |
realms [realm_name]| users glob_user_name [realm_name]}

30

Chapter 3: Controlling Access to the Internet and Intranet

Section A: Managing Users
(config users) log-out {ip-addresses prefix [realm_name] | realms
[realm_name]| users glob_user_name [realm_name]}
(config users) surrogates-refresh {ip-addresses prefix [realm_name] |
realms [realm_name]| users glob_user_name [realm_name]}
(config users) view {detailed {ip-addresses prefix [realm_name] |
realms [realm_name]| users glob_user_name [realm_name]} | ip-addresses
prefix [realm_name] | realms [realm_name] | users glob_user_name
[realm_name]}

31

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies

Section B: Using Authentication and Proxies
Authentication means that the SG appliance requires proof of user identity in order to
make decisions based on that identity. This proof is obtained by sending the client (a
browser, for example) a challenge—a request to provide credentials. Browsers can respond
to different kinds of credential challenges:


Proxy-style challenges—Sent from proxy servers to clients that are explicitly proxied.
In HTTP, the response code is 407.
An authenticating explicit proxy server sends a proxy-style challenge (407/ProxyAuthenticate) to the browser. The browser knows it is talking to a proxy and that the
proxy wants proxy credentials. The browser responds to a proxy challenge with proxy
credentials (Proxy-Authorization: header). The browser must be configured for
explicit proxy in order for it to respond to a proxy challenge.



Origin-style challenges—Sent from origin content servers (OCS), or from proxy
servers impersonating a OCS. In HTTP, the response code is 401 Unauthorized.
In transparent proxy mode, the SG appliance uses the OCS authentication challenge
(HTTP 401 and WWW-Authenticate)—acting as though it is the location from which
the user initially requested a page. A transparent proxy, including a reverse proxy,
must not use a proxy challenge, because the client might not be expecting it.

Once the browser supplies the credentials, the SG appliance authenticates them.

Understanding Authentication Modes
You can control the way the SG appliance interacts with the client for authentication by
controlling the authentication mode. The mode specifies the challenge type and the
accepted surrogate credential.
Note: Challenge type is the kind of challenge (for example, proxy or origin-ip-redirect)

issued.
Surrogate credentials are credentials accepted in place of the user’s real credentials.


Auto: The default; the mode is automatically selected, based on the request. Auto can
choose any of proxy, origin, origin-ip, or origin-cookie-redirect, depending on the kind

of connection (explicit or transparent) and the transparent authentication cookie
configuration.


Proxy: The SG appliance uses an explicit proxy challenge. No surrogate credentials are
used. This is the typical mode for an authenticating explicit proxy. In some situations
proxy challenges do not work; origin challenges are then issued.

If you have many requests consulting the back-end authentication authority (such as
LDAP, RADIUS, or the BCAAA service), you can configure the SG appliance (and
possibly the client) to use persistent connections. This dramatically reduces load on
the back-end authentication authority and improves the all-around performance of
the network.

32

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies

Important: Windows supports Kerberos authentication only to origin servers; proxy
servers cannot participate. Therefore, explicit authentication modes are not
compatible with Kerberos. However, because Internet Explorer automatically selects
NTLM for an explicit challenge (where the browser is configured with the proxy as a
proxy server), no special processing is required for explicit authentication. An origin
redirect authentication mode, such as authenticate.mode (origin-cookieredirect), can be used to obtain Kerberos authentication when using an explicit
proxy if the browser is configured to bypass the proxy for the virtual URL.


Proxy-IP: The SG appliance uses an explicit proxy challenge and the client's IP address

as a surrogate credential. Proxy-IP specifies an insecure forward proxy, possibly
suitable for LANs of single-user workstations. In some situations proxy challenges do
not work; origin challenges are then issued.


Origin: The SG appliance acts like an OCS and issues OCS challenges. The

authenticated connection serves as the surrogate credential.


Origin-IP: The SG appliance acts like an OCS and issues OCS challenges. The client IP
address is used as a surrogate credential. Origin-IP is used to support IWA

authentication to the upstream device when the client cannot handle cookie
credentials. This mode is primarily used for automatic downgrading, but it can be
selected for specific situations.


Origin-cookie: The SG appliance acts like an origin server and issues origin server
challenges. A cookie is used as the surrogate credential. Origin-cookie is used in
forward proxies to support pass-through authentication more securely than origin-ip

if the client understands cookies. Only the HTTP and HTTPS protocols support
cookies; other protocols are automatically downgraded to origin-ip.
This mode could also be used in reverse proxy situations if impersonation is not
possible and the origin server requires authentication.


Origin-cookie-redirect: The client is redirected to a virtual URL to be authenticated,
and cookies are used as the surrogate credential. The SG appliance does not support
origin-redirects with the CONNECT method. For forward proxies, only origin-*redirect modes are supported for Kerberos/IWA authentication. (Any other mode
uses NTLM authentication.)
Note: During cookie-based authentication, the redirect to strip the authentication
cookie from the URL is logged as a 307 (or 302) TCP_DENIED.



Origin-IP-redirect: The client is redirected to a virtual URL to be authenticated, and the
client IP address is used as a surrogate credential. The SG appliance does not support
origin-redirects with the CONNECT method. For forward proxies, only origin-*redirect modes are supported for Kerberos/IWA authentication. (Any other mode
uses NTLM authentication.)



SG2: The mode is selected automatically, based on the request, and uses the SGOS 2.x-

defined rules.


Form-IP: A form is presented to collect the user's credentials. The form is presented
whenever the user’s credential cache entry expires.

33

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies


Form-Cookie: A form is presented to collect the user's credentials. The cookies are set

on the OCS domain only, and the user is presented with the form for each new
domain. This mode is most useful in reverse proxy scenarios where there are a limited
number of domains.


Form-Cookie-Redirect: A form is presented to collect the user's credentials. The user is
redirected to the authentication virtual URL before the form is presented. The
authentication cookie is set on both the virtual URL and the OCS domain. The user is
only challenged when the credential cache entry expires.



Form-IP-redirect: This is similar to form-ip except that the user is redirected to the
authentication virtual URL before the form is presented.

Important: Modes that use an IP surrogate credential are insecure: After a user has
authenticated from an IP address, all further requests from that IP address are treated
as from that user. If the client is behind a NAT, or on a multi-user system, this can
present a serious security problem.
The default value is auto.
For more information about using authentication modes, refer to Volume 10: Blue Coat SG
Appliance Content Policy Language Guide.

Setting the Default Authenticate Mode Property
Setting the authentication.mode property selects a challenge type and surrogate
credential combination. In auto mode, explicit IWA uses connection surrogate credentials.
In sg2 mode, explicit IWA uses IP surrogate credentials.
To configure the IWA default authenticate mode settings:
SGOS#(config) security default-authenticate-mode {auto | sg2}

Understanding Origin-Style Redirection
Some authentication modes redirect the browser to a virtual authentication site before
issuing the origin-style challenge. This gives the user feedback as to which credentials are
required, and makes it possible to (but does not require) send the credentials over a secure
connection.
Since browser requests are transparently redirected to the SG appliance, the appliance
intercepts the request for the virtual authentication site and issues the appropriate
credential challenge. Thus, the challenge appears to come from the virtual site, which is
usually named to make it clear to the user that SG credentials are requested.
If authentication is successful, the SG appliance establishes a surrogate credential and
redirects the browser back to the original request, possibly with an encoded surrogate
credential attached. This allows the SG appliance to see that the request has been
authenticated, and so the request proceeds. The response to that request can also carry a
surrogate credential.
To provide maximum flexibility, the virtual site is defined by a URL. Requests to that URL
(only) are intercepted and cause authentication challenges; other URLs on the same host
are treated normally. Thus, the challenge appears to come from a host that in all other
respects behaves normally.

34

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies

Note: Sharing the virtual URL with other content on a real host requires additional
configuration if the credential exchange is over SSL.

You can configure the virtual site to something that is meaningful for your company. The
default, which requires no configuration, is www.cfauth.com. See “Configuring
Transparent Proxy Authentication” on page 35 to set up a virtual URL for transparent
proxy.

Tip: Using CONNECT and Origin-Style Redirection
You cannot use the CONNECT method with origin-style redirection or form redirect
modes. An error message similar to the following is displayed:
Cannot use origin-redirect for CONNECT method (explicit proxy of https
URL)

Instead, you can add policy to either bypass authentication on the CONNECT method, or
use proxy authentication. For example:

allow http.method=CONNECT authenticate.mode(proxy)
authenticate(ldap)
allow authenticate(cert) authenticate.mode(origin-cookie-redirect)

Selecting an Appropriate Surrogate Credential
IP surrogate credentials are less secure than cookie surrogate credentials and should be
avoided if possible. If multiple clients share an IP address (such as when they are behind a
NAT firewall or on a multi-user system), the IP surrogate mechanism cannot distinguish
between those users.

Configuring Transparent Proxy Authentication
The following sections provide general instructions on configuring for transparent proxy
authentication.
In addition to configuring transparent proxy authentication, you must also enable a
transparent proxy port before the transparent proxy is functional. To enable a transparent
proxy port, refer to Volume 2: Proxies and Proxy Services.
To set transparent proxy options:
1.

Select Configuration > Authentication > Transparent Proxy.

35

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies

Permitting Users to Login with Authentication or Authorization Failures
You can configure policy (VPM or CPL) to attempt user authentication while permitting
specific authentication or authorization errors. The policy can specify that, after certain
authentication or authorization failures, the user transaction should be allowed to proceed
and not be terminated.
Note:

For a list of permitted authentication and authorization errors, see
Appendix E: "Authentication and Authorization Errors" on page 247.

Permitted Errors
Authentication and authorization can be permitted to fail if policy has been written to
allow specific failures. The behavior is as follows:




Authentication Failures: After an authentication failure occurs, the authentication
error is checked against the list of errors that policy specifies as permitted.


If the error is not on the list, the transaction is terminated.



If the error is on the list, the transaction is allowed to proceed although the user is
unauthenticated. Because the transaction is not considered authenticated, the
authenticated=yes policy condition evaluates to false and the user has no
username, group information, or surrogate credentials. Policy that uses the user,
group, domain, or attribute conditions does not match.

Authorization Failures: After an authorization failure occurs, the authorization error
is checked against the list of errors that policy specifies as permitted.


If the error is not on the list, the transaction is terminated.



If the error is on the list, the transaction is allowed to proceed and the user is
marked as not having authorization data.



If a user is successfully authenticated but does not have authorization data, the
authenticated=yes condition evaluates to true and the user has valid
authentication credentials.



The user.authorization_error=any is evaluate to true if user authorization
failed, the user object contains username and domain information, but not group
or attribute information. As a result, policy using user or domain actions still
match, but policy using group or attribute conditions do not.

To view all authentication and authorization errors, use the SGOS# show security
authentication-errors CLI command.

Policy Used with Permitted Errors
Before creating policy to permit errors, you must:


Identify the type of access the transactions should be permitted.



Identify under which circumstances transactions can proceed even if authentication
or authorization fails.



Identify which errors correspond to those circumstances.

37

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies
You can use the advanced authentication URL (Statistics > Advanced > Show
Authentication Error Statistics as a troubleshooting guide. The policy substitutions $(xsc-authentication-error) and $(x-sc-authorization-error) can also be used to
log the errors on a per-transaction basis.
Policy conditions and properties that are available include:


authenticate.tolerate_error( )



authorize.tolerate_error( )



user.authentication_error=



user.authorization_error=



has_authorization_data=
Note: You are not limited to these conditions and properties in creating policy. For a
discussion and a complete list of policy conditions and properties you can use, refer to
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.

You can also use the following policy substitutions:


x-sc-authentication-error: If authentication has failed, this is the error

corresponding to the failure. If authentication has not been attempted, the value is
not_attempted. If authentication has succeeded, the value is none.


x-sc-authorization-error: If authorization has failed, this is the error
corresponding to the failure. If authorization has not been attempted, the value is
not_attempted. If authorization has succeeded, the value is none.

Using Guest Authentication
Using policy (VPM or CPL), you can allow a user to log in as a guest user. Guest
authentication allows you to assign a username to a user who would have otherwise been
considered unauthenticated.
Note: You can use guest authentication with or without default groups. If you use
default groups, you can assign guest users to groups for tracking and statistics
purposes. For more information about default groups, see “Using Default Groups” on
page 39.

In the case of guest authentication, a user is not actually authenticated against the realm,
but is:


Assigned the specified guest username



Marked as authenticated in the specified realm



Marked as a guest user



Tracked in access logs

Since the user is not actually authenticated, the username does not have to be valid in that
realm.

38

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies

Using Policy with Guest Authentication
Before creating policy for guest authentication:


Determine the circumstances in which guest access is permitted. Guest users are
typically allowed in circumstances where no authentication is needed.



Determine authentication policy. Will the realms attempt to authenticate users first
and fallback to guest authentication or authenticate users as guest users without
attempting authentication?
Note: If a transaction matches both a regular authentication action and guest
authentication action, regular authentication is attempted first. This can result in a
user challenge before dropping back to guest authentication. If you inadvertently
enter invalid credentials and so drop back to guest access, you must log out as guest
or close and reopen the browser if using session cookies or connection surrogates. You
then can enter the correct credentials to obtain regular access.

Write the corresponding policy. Policy available for guest authentication includes:


authenticate.guest



user.is_guest



authenticated
Note: You are not limited to these conditions and properties in creating policy. For a
complete list of policy conditions and properties you can use, refer to Volume 10: Blue
Coat SG Appliance Content Policy Language Guide.

Using Policy Substitutions with Guest Authentication
The following policy substitution was created for use with guest authentication.


x-cs-user-type: If the user is an authenticated guest user, the value is guest. If the
user is an authenticated non-guest user, the value is authenticated. If the user is not
authenticated, the value is unauthenticated.

You are not limited to this substitution, and you can use the substitution in other
circumstances. For a complete list of policy substitutions, refer to access log substitutions
in Volume 8: Access Logging.

Using Default Groups
You can use default groups with any realm, and they can be used when authorization
succeeds, fails or wasn't attempted at all. Default groups allow you to assign users to
groups and use those groups in reporting and subsequent authorization decisions.
Note:

You can use default groups in conjunction with guest users (see “Using Guest
Authentication” on page 38) or it can be used with regular user authentication.

39

Chapter 3: Controlling Access to the Internet and Intranet

Section B: Using Authentication and Proxies

Using Policy with Default Groups
Before creating policy for default groups, you must determine which set of groups are
assigned as default.
You can specify a single or multiple groups here. In most cases, only a single group will be
required, but occasionally you might need to assign the user to multiple groups:


For extra reporting abilities.



If the policy is structured in a way that users should receive the same access as if they
belonged in multiple different groups.

Policy available for default groups includes:


group



authorize.add_group
Note: You are not limited to these conditions and properties in creating policy. For a
complete list of policy conditions and properties you can use, refer to Volume 10: Blue
Coat SG Appliance Content Policy Language Guide.

40

Chapter 3: Controlling Access to the Internet and Intranet

Section C: Using SSL with Authentication and Authorization Services

Section C: Using SSL with Authentication and Authorization Services
Blue Coat recommends that you use SSL during authentication to secure your user
credentials. Blue Coat supports SSL between the client and the SG appliance and between
the SG appliance and LDAP and IWA authentication servers.

Using SSL Between the Client and the SG Appliance
To configure SSL to use origin-cookie-redirect or origin-ip-redirect challenges, you must:


Specify a virtual URL with the HTTPS protocol (for example,
https://virtual_address).



Create a keyring and certificate on the SG appliance.



Create an HTTPS service to run on the port specified in the virtual URL and to use the
keyring you just created.

Note: You can use SSL between the client and the SG appliance for origin-style
challenges on transparent and explicit connections (SSL for explicit proxy authentication
is not supported).

In addition, if you use a forward proxy, the challenge type must use redirection; it cannot
be an origin or origin-ip challenge type.
When redirected to the virtual URL, the user is prompted to accept the certificate offered
by the SG appliance (unless the certificate is signed by a trusted certificate authority). If
accepted, the authentication conversation between the SG appliance and the user is
encrypted using the certificate.
Note: If the hostname does not resolve to the IP address of the SG appliance, then the
network configuration must redirect traffic for that port to the appliance. Also, if you use
the IP address as the virtual hostname, you might have trouble getting a certificate signed
by a CA-Certificate authority (which might not be important).

For information about creating a keyring and a certificate, refer to Volume 2: Proxies and
Proxy Services.
You can use SSL between the SG appliance and IWA and LDAP authentication servers.
For more information, see “SSL Between the SG Appliance and the Authentication
Server” on page 12.

41

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations

Section D: Creating a Proxy Layer to Manage Proxy Operations
Once hardware configuration is complete and the system configured to use transparent or
explicit proxies, use CPL or VPM to provide on-going management of proxy operations.

Using CPL
Below is a table of all commands available for use in proxy layers of a policy. If a
condition, property, or action does not specify otherwise, it can be used only in
layers. For information about creating effective CPL, refer to Volume 10: Blue Coat SG
Appliance Content Policy Language Guide.
Table 3-1. CPL Commands Available in the Layer
Layer Conditions

Meaning

admin.access=

Tests the administrative access requested by the current transaction. Can also
be used in layers.

attribute.name=

Tests if the current transaction is authenticated in a RADIUS or LDAP realm,
and if the authenticated user has the specified attribute with the specified
value. Can also be used in layers.

authenticated=

Tests if authentication was requested and the credentials could be verified;
otherwise, false. Can also be used in layers.

bitrate=

Tests if a streaming transaction requests bandwidth within the specified range
or an exact match. Can also be used in layers.

category=

Tests if the content categories of the requested URL match the specified
category, or if the URL has not been categorized. Can also be used in
layers.

client_address=

Tests the IP address of the client. Can also be used in layers.

client.connection.
negotiated_cipher=

Test the cipher suite negotiated with a securely connected client. Can also be
used in layers.

client.connection.
negotiated_cipher.
strength=

Test the cipher strength negotiated with a securely connected client. Can also
be used in layers.

client.host=

Test the hostname of the client (obtained through RDNS). Can also be used in
, , and layers.

client.host.has_name=

Test the status of the RDNS performed to determine 'client.host'. Can also be
used in , , and layers.

client_protocol=

Tests true if the client transport protocol matches the specification. Can also be
used in layers.

condition=

Tests if the specified defined condition is true. Can be used in all layers.

console_access=

(This trigger was formerly admin=yes|no.) Tests if the current request is
destined for the admin layer. Can also be used in and
layers.

42

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-1. CPL Commands Available in the Layer (Continued)
content_management=

(This trigger was formerly content_admin=yes|no.) Tests if the current
request is a content-management transaction. Can also be used in
and layers.

date[.utc]=

Tests true if the current time is within the startdate..enddate range, inclusive.
Can be used in all layers.

day=

Tests if the day of the month is in the specified range or an exact match. Can be
used in all layers.

exception.id=

Indicates that the requested object was not served, providing this specific
exception page.
Can also be used in layers.

ftp.method=

Tests ftp request methods against any of a well-known set of FTP methods.
Can also be used in and layers.

group=

Tests if the authenticated condition is set to yes, the client is authenticated, and
the client belongs to the specified group. Can also be used in layers.

has_attribute.name=

Tests if the current transaction is authenticated in an LDAP realm and if the
authenticated user has the specified LDAP attribute. Can also be used in
layers.

hour=

Tests if the time of day is in the specified range or an exact match. Can be used
in all layers.

http.method=

Tests HTTP request methods against any of a well known set of HTTP
methods. Can also be used in and layers.

http.method.regex=

Test the HTTP method using a regular expression. Can also be used in
layers.

http.request_line.regex=

Test the HTTP protocol request line. Can also be used in layers.

http.request.version=

Tests the version of HTTP used by the client in making the request to the SG
appliance. Can also be used in and layers.

http.response_code=

Tests true if the current transaction is an HTTP transaction and the response
code received from the origin server is as specified. Can also be used in
and layers.

http.response.version=

Tests the version of HTTP used by the origin server to deliver the response to
the SG appliance. Can also be used in and layers.

http.transparent_
authentication=

This trigger evaluates to true if HTTP uses transparent proxy authentication
for this request. Can also be used in and layers.

im.buddy_id=

Tests the buddy_id associated with the IM transaction. Can also be used in
layers.

im.chat_room.conference=

Tests whether the chat room associated with the transaction has the conference
attribute set. Can also be used in layers.

im.chat_room.id=

Tests the chat room ID associated with the transaction. Can also be used in
layers.

im.chat_room.invite_
only=

Tests whether the chat room associated with the transaction has the
invite_only attribute set. Can also be used in layers.

43

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-1. CPL Commands Available in the Layer (Continued)
im.chat_room.type=

Tests whether the chat room associated with the transaction is public or
private. Can also be used in layers.

im.chat_room.member=

Tests whether the chat room associated with the transaction has a member
matching the specified criterion. Can also be used in layers.

im.chat_room.voice_
enabled=

Tests whether the chat room associated with the transaction is voice enabled.
Can also be used in layers.

im.client=

Test the type of IM client in use. Can also be used in ,
, and layers.

im.file.extension=

Tests the file extension. Can also be used in layers.

im.file.name=

Tests the file name (the last component of the path), including the extension.
Can also be used in layers.

im.file.path=

Tests the file path against the specified criterion. Can also be used in
layers.

im.file.size=

Performs a signed 64-bit range test. Can also be used in layers.

im.message.reflected

Test whether IM reflection occurred. Can also be used in and
layers.

im.message.route=

Tests how the IM message reaches its recipients. Can also be used in
layers.

im.message.size=

Performs a signed 64-bit range test. Can also be used in layers.

im.message.text.
substring=

Performs a signed 64-bit range test. Can also be used in layers.

im.message.opcode=

Tests the value of an opcode associated with an im.method of
unknown_send or unknown_receive.

im.message.type=

Tests the message type. Can also be used in layers.

im.method=

Tests the method associated with the IM transaction. Can also be used in
and layers.

im.user_id=

Tests the user_id associated with the IM transaction. Can also be used in
layers.

live=

Tests if the streaming content is a live stream. Can also be used in
layers.

minute=

Tests if the minute of the hour is in the specified range or an exact match. Can
be used in all layers.

month=

Tests if the month is in the specified range or an exact match. Can be used in all
layers.

proxy.address=

Tests the IP address of the network interface card (NIC) on which the request
arrives. Can also be used in layers.

proxy.card=

Tests the ordinal number of the network interface card (NIC) used by a request.
Can also be used in layers.

proxy.port=

Tests if the IP port used by a request is within the specified range or an exact
match. Can also be used in layers.

44

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-1. CPL Commands Available in the Layer (Continued)
raw_url

Test the value of the raw request URL. Can also be used in
layers.

raw_url.host

Test the value of the 'host' component of the raw request URL. Can also be
used in layers.

raw_url.path

Test the value of the 'path' component of the raw request URL. Can also be
used in layers.

raw_url.pathquery

Test the value of the 'path and query' component of the raw request URL. Can
also be used in layers.

raw_url.port

Test the value of the 'port' component of the raw request URL. Can also be used
in layers.

raw_url.query

Test the value of the 'query' component of the raw request URL. Can also be
used in layers.

realm=

Tests if the authenticated condition is set to yes, the client is authenticated, and
the client has logged into the specified realm. an also be used in
layers.

release.id=

Tests the SG release ID. Can be used in all layers.

request.header_address.
header_name=

Tests if the specified request header can be parsed as an IP address. Can also be
used in layers.

request.header.header_
name=

Tests the specified request header (header_name) against a regular
expression. Can also be used in layers.

request.header.header_
name.count

Test the number of header values in the request for the given header_name.
Can also be used in layers.

request.header.header_
name.length

Test the total length of the header values for the given header_name. Can also
be used in layers.

request.header.Referer.
url.host.has_name=

Test whether the Referer URL has a resolved DNS hostname. Can also be used
in layers.

request.header.Referer.
url.is_absolute

Test whether the Referer URL is expressed in absolute form. Can also be used
in layers.

request.raw_headers.
count

Test the total number of HTTP request headers. Can also be used in
layers.

request.raw_headers.
length

Test the total length of all HTTP request headers. Can also be used in
layers.

request.raw_headers.
regex

Test the value of all HTTP request headers with a regular expression. Can also
be used in layers.

request.x_header.header_
name.count

Test the number of header values in the request for the given header_name.
Can also be used in layers.

request.x_header.header_
name.length

Test the total length of the header values for the given header_name. Can also
be used in layers.

response.header.header_
name=

Tests the specified response header (header_name) against a regular
expression. Can also be used in layers.

45

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-1. CPL Commands Available in the Layer (Continued)
response.x_header.
header_name=

Tests the specified response header (header_name) against a regular
expression. Can also be used in layers.

server_url[.case_
sensitive|.no_lookup]=

Tests if a portion of the requested URL exactly matches the specified pattern.
Can also be used in layers.

socks.accelerated=

Controls the SOCKS proxy handoff to other protocol agents.

socks.method=

Tests the protocol method name associated with the transaction. Can also be
used in and layers.

socks.version=

Switches between SOCKS 4/4a and 5. Can also be used in and
layers.

streaming.content=

(This trigger has been renamed from streaming.) Can also be used in ,
, and layers.

time=

Tests if the time of day is in the specified range or an exact match. Can be used
in all layers.

tunneled=
url.domain=

Tests if the requested URL, including the domain-suffix portion, matches the
specified pattern. Can also be used in layers.

url.extension=

Tests if the filename extension at the end of the path matches the specified
string. Can also be used in layers.

url.host=

Tests if the host component of the requested URL matches the IP address or
domain name. Can also be used in layers.

url.host.has_name

Test whether the request URL has a resolved DNS hostname. Can also be used in
layers

url.is_absolute

Test whether the request URL is expressed in absolute form. Can also be used
in layers

url.host.is_numeric=

This is true if the URL host was specified as an IP address. Can also be used in
layers.

url.host.no_name=

This is true if no domain name can be found for the URL host. Can also be used
in layers.

url.host.regex=

Tests if the specified regular expression matches a substring of the domain
name component of the request URL. Can also be used in layers.

url.host.suffix=

Can also be used in layers.

url.path=

Tests if a prefix of the complete path component of the requested URL, as well
as any query component, matches the specified string. Can also be used in
layers.

url.path.regex=

Tests if the regex matches a substring of the path component of the request
URL. Can also be used in layers.

url.port=

Tests if the port number of the requested URL is within the specified range or
an exact match. Can also be used in layers.

url.query.regex=

Tests if the regex matches a substring of the query string component of the
request URL. Can also be used in layers.

46

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-1. CPL Commands Available in the Layer (Continued)
url.regex=

Tests if the requested URL matches the specified pattern. Can also be used in
layers.

url.scheme=

Tests if the scheme of the requested URL matches the specified string. Can also
be used in layers.

user=

Tests the authenticated user name of the transaction. Can also be used in
layers.

user.domain=

Tests if the authenticated condition is set to yes, the client is authenticated, the
logged-into realm is an IWA realm, and the domain component of the user
name is the specified domain. Can also be used in layers.

weekday=

Tests if the day of the week is in the specified range or an exact match. Can be
used in all layers.

year=

Tests if the year is in the specified range or an exact match. Can be used in all
layers.

Table 3-2. Properties Available in the Layer
Layer Properties

Meaning

action.action_label( )

Selectively enables or disables a specified define action block. Can also be used
in layers.

allow

Allows the transaction to be served. Can be used in all layers except
and layers.

always_verify( )

Determines whether each request for the objects at a particular URL must be
verified with the origin server.

authenticate( )

Identifies a realm that must be authenticated against. Can also be used in
layers.

authenticate.force( )

Either disables proxy authentication for the current transaction (using the
value no) or requests proxy authentication using the specified authentication
realm. Can also be used in layers.

authenticate.form( )

When forms-based authentication is in use, authenticate.form ( ) selects the
form used to challenge the user.

authenticate.mode(auto)
authenticate.mode(sg2)

Setting the authentication.mode property selects a challenge type and
surrogate credential combination. In auto mode, explicit IWA uses connection
surrogate credentials. In sg2.mode, explicit IWA uses IP surrogate credentials.

authenticate.redirect_
stored_requests

Sets whether requests stored during forms-based authentication can be
redirected if the upstream host issues a redirecting response.

bypass_cache( )

Determines whether the cache is bypassed for a request.

check_authorization( )

In connection with CAD (Caching Authenticated Data) and CPAD (Caching
Proxy Authenticated Data) support, check_authorization( ) is used
when you know that the upstream device will sometimes (not always or
never) require the user to authenticate and be authorized for this object. Can
also be used in layers.

47

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-2. Properties Available in the Layer (Continued)
delete_on_abandonment( )

If set to yes, then if all clients requesting an object close their connections prior
to the object being delivered, the object fetch from the origin server is
abandoned. Can also be used in layers.

deny

Denies service. Can be used in all layers except and
layers.

dynamic_bypass( )

Used to indicate that a particular transparent request should not be handled by
the proxy, but instead be subjected to our dynamic bypass methodology.

exception( )

Indicates not to serve the requested object, but instead serve this specific
exception page.
Can be used in all layers except layers.

ftp.server_connection( )

Determines when the control connection to the server is established.

ftp.welcome_banner( )

Sets the welcome banner for a proxied FTP transaction.

http.client.recv.timeout

Sets the socket timeout for receiving bytes from the client.

http.request.version( )

The http.request.version( ) property sets the version of the HTTP
protocol to be used in the request to the origin content server or upstream
proxy. Can also be used in layers.

http.response.parse_meta
_tag.
Cache-Control( )

Controls whether the 'Cache-Control' META Tag is parsed in an HTML
response body. Can also be used in layers.

http.response.parse_meta
_tag. Expires

Controls whether the 'Expires' META Tag is parsed in an HTML response
body. Can also be used in layers.

http.response.parse_meta
_tag. Pragma.no-cache

Controls whether the 'Pragma: no-cache' META Tag is parsed in an HTML
response body. Can also be used in layers.

http.response.version( )

The http.response.version( ) property sets the version of the HTTP
protocol to be used in the response to the client's user agent.

http.server.recv.
timeout( )

Sets the socket timeout for receiving bytes from the upstream host. Can also be
used in layers.

im.block_encryption

Prevents the encryption of AOL IM messages by modifying messages during
IM login time.

im.reflect

Sets whether IM reflection should be attempted.

im.strip_attachments( )

Determines whether attachments are stripped from IM messages.

im.transport

Sets the type of upstream connection to make for IM traffic.

log.suppress.field-id( )

The log.suppress.field-id( ) controls suppression of the specified
field-id in all facilities (individual logs that contain all properties for that
specific log in one format). Can be used in all layers.

log.suppress.field-id
[log_list]( )

The log.suppress.field-id [log_list]( ) property controls
suppression of the specified field-id in the specified facilities. Can be used in
all layers.

log.rewrite.field-id( )

The log.rewrite.field-id( ) property controls rewrites of a specific log
field in all facilities. Can be used in all layers.

48

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations
Table 3-2. Properties Available in the Layer (Continued)
log.rewrite.field-id
[log_list]( )

The log.rewrite.field-id [log_list]( ) property controls rewrites
of a specific log field in a specified list of log facilities. Can be used in all layers.

reflect_ip( )

Determines how the client IP address is presented to the origin server for
explicitly proxied requests. Can also be used in layers.

request.filter_service(
)

Websense is the built in service name for the off-box content filtering service.
Can also be used in layers.

request.icap_service( )

Determines whether a request from a client should be processed by an external
ICAP service before going out.

shell.prompt

Sets the prompt for a proxied Shell transaction.

shell.realm_banner

Sets the realm banner for a proxied Shell transaction.

shell.welcome_banner

Sets the welcome banner for a proxied Shell transaction.

socks.accelerate( )

The socks.accelerate property controls the SOCKS proxy handoff to other
protocol agents.

socks.authenticate( )

The same realms can be used for SOCKS proxy authentication as can be used
for regular proxy authentication.

socks.authenticate.
force( )

The socks.authenticate.force( ) property forces the realm to be
authenticated through SOCKS.

Table 3-3. Actions Available in the Layer
Layer Actions

Meaning

log_message( )

Writes the specified string to the SG event log. Can be used in all layers except
.

notify_email( )

Sends an e-mail notification to the list of recipients specified in the Event Log
mail configuration. Can be used in all layers.

notify_snmp( )

The SNMP trap is sent when the transaction terminates. Can be used in all
layers.

redirect( )

Ends the current HTTP transaction and returns an HTTP redirect response to the
client.

transform

Invokes the active content or URL rewrite transformer.

49

Chapter 3: Controlling Access to the Internet and Intranet

Section D: Creating a Proxy Layer to Manage Proxy Operations

50

Chapter 4: Understanding and Managing X.509 Certificates

Blue Coat uses certificates for various applications, including:


authenticating the identity of a server



authenticating an SG appliance



securing an intranet



encrypting data

The certificates Blue Coat uses are X.509 certificates. X.509 is a cryptographic standard
for public key infrastructure (PKI) that specifies standard formats for public key
certificates. Several RFCs and books exist on the public key cryptographic system
(PKCS). This discussion of the elements of PKCS is relevant to their implementation in
SGOS.


Section A: "Concepts" on page 52



"Section B: Using Keyrings and SSL Certificates" on page 55



Section C: "Managing Certificates" on page 59



Section D: "Using External Certificates" on page 65



"Section E: Advanced Configuration" on page 67

51

Volume 4: Securing the Blue Coat SG Appliance
Section A: Concepts

Section A: Concepts
This section discusses concepts surrounding certificates and SGOS.

Public Keys and Private Keys
In PKCS systems, the intended recipient of encrypted data generates a private/public
keypair, and publishes the public key, keeping the private key secret. The sender encrypts
the data with the recipient's public key, and sends the encrypted data to the recipient. The
recipient uses the corresponding private key to decrypt the data.
For two-way encrypted communication, the endpoints can exchange public keys, or one
endpoint can choose a symmetric encryption key, encrypt it with the other endpoint's
public key, and send it.

Certificates
The SGOS software uses:


SSL Certificates.



CA Certificates.



External Certificates.

You can also use wildcard certificates during HTTPS termination. Microsoft’s
implementation of wildcard certificates is as described in RFC 2595, allowing an *
(asterisk) in the leftmost-element of the server's common name only. For information on
wildcards supported by Internet Explorer, refer to the Microsoft knowledge base, article:
258858. Any SSL certificate can contain a common name with wildcard characters.

SSL Certificates
SSL certificates are used to authenticate the identity of a server or a client. A certificate is
confirmation of the association between an identity (expressed as a string of characters)
and a public key. If a party can prove they hold the corresponding private key, you can
conclude that the party is who the certificate says it is. The certificate contains other
information, such as its expiration date.
The association between a public key and a particular server is done by generating a
certificate signing request using the server's or client’s public key. A certificate signing
authority (CA) verifies the identity of the server or client and generates a signed
certificate. The resulting certificate can then be offered by the server to clients (or from
clients to servers) who can recognize the CA's signature. Such use of certificates issued by
CAs has become the primary infrastructure for authentication of communications over the
Internet.
The SG trusts all root CA certificates trusted by Internet Explorer and Firefox. The list is
updated periodically to be in sync with the latest versions of IE and Firefox.
CA certificates installed on the SG are used to verify the certificates presented by HTTPS
servers and the client certificates presented by browsers. Browsers offer a certificate if the
server is configured to ask for one and an appropriate certificate is available to the
browser.

52

Chapter 4: Understanding and Managing X.509 Certificates

Section A: Concepts

CA Certificates
CA certificates are certificates that belong to certificate authorities. CA certificates are
used by SGdevices to verify X.509 certificates presented by a client or a server during
secure communication. SG appliances are pre-installed with the most common CA
certificates.
SG appliances come with many popular CA certificates already installed. You can review
these certificates using the Management Console or the CLI. You can also add certificates
for your own internal certificate authorities.

External Certificates
An external certificate is any X509 certificate for which the SG appliance does not have the
private key. The certificate can be used to encrypt data, such as access logs, with a public
key so that it can only be decrypted by someone who has the corresponding private key.
Refer to Volume 8: Access Logging for information about encrypting access logs.

Keyrings
A keyring contains a public/private keypair. It can also contain a certificate signing
request or a signed certificate. Keyrings are named, can be created, deleted and viewed;
there are built-in keyrings for specified purposes. For information on managing keyrings,
see Section B: "Using Keyrings and SSL Certificates" on page 55.

Cipher Suites Supported by SGOS Software
A cipher suite specifies the algorithms used to secure an SSL connection. When a client
makes an SSL connection to a server, it sends a list of the cipher suites that it supports.
The server compares this list with its own supported cipher suites and chooses the first
cipher suite proposed by the client that they both support. Both the client and server then
use this cipher suite to secure the connection.
Note:

You can delete cipher suites that you do not trust. However, SGOS does not
provide any mechanism to change the ordering of the ciphers used.
All cipher suites supported by the SG appliance use the RSA key exchange algorithm,
which uses the public key encoded in the server's certificate to encrypt a piece of secret
data for transfer from the client to server. This secret is then used at both endpoints to
compute encryption keys.
By default, the SG appliance is configured to allow SSLv2 and v3 as well as TLSv1 traffic.
The cipher suites available for use differ depending on whether you configure SSL for
version 2, version 3, TLS, or a combination of these.
Table 4-1. Cipher Suites Shipped with the SG Appliance
SGOS Cipher #

Cipher Name

Strength

Exportable

Description

1

RC4-MD5

Medium

No

128-bit key size.

2

RC4-SHA

Medium

No

128-bit key size.

3

DES-CBC3-SHA

High

No

168-bit key size.

53

Volume 4: Securing the Blue Coat SG Appliance
Section A: Concepts
Table 4-1. Cipher Suites Shipped with the SG Appliance (Continued)
SGOS Cipher #

Cipher Name

Strength

Exportable

Description

4

DES-CBC3-MD5

High

No

168-bit key size.

5

RC2-CBC-MD5

Medium

No

128-bit key size.

6

RC4-64-MD5

Low

No

64-bit key size.

7

DES-CBC-SHA

Low

No

56-bit key size.

8

DES-CBC-MD5

Low

No

56-bit key size.

9

EXP1024-RC4-MD5

Export

Yes

56-bit key size.

10

EXP1024-RC4-SHA

Export

Yes

56-bit key size.

11

EXP1024-RC2-CBC-MD5

Export

Yes

56-bit key size.

12

EXP1024-DES-CBC-SHA

Export

Yes

56-bit key size.

13

EXP-RC4-MD5

Export

Yes

40-bit key size.

14

EXP-RC2-CBC-MD5

Export

Yes

40-bit key size.

15

EXP-DES-CBC-SHA

Export

Yes

40-bit key size.

16

AES128-SHA

Medium

No

128-bit key size.

17

AES256-SHA

High

No

256-bit key size.

Cipher Suite configuration is discussed in “Changing the Cipher Suites of the SSL Client”
on page 234.

Server-Gated Cryptography and International Step-Up
Due to US export restrictions, international access to a secure site requires that the site
negotiates export-only ciphers. These are relatively weak ciphers ranging from 40-bit to
56-bit key lengths, and are vulnerable to attack.
Server Gated Cryptography (SGC) is a Microsoft extension to the certificate that allows
the client receiving the certificate to first negotiate export strength ciphers, followed by a
re-negotiation with strong ciphers. Netscape has a similar extension called International
Step-up.
SGOS supports both SGC and International Step-up in its SSL implementation. There are,
however, known anomalies in Internet Explorer's implementation that can cause SSL
negotiation to fail. Refer to the following two documents for more detail and check for
recent updates on the Microsoft support site.
http://support.microsoft.com/support/kb/articles/Q249/8/63.ASP
http://support.microsoft.com/support/kb/articles/Q244/3/02.ASP

To take advantage of this technology, SGOS supports VeriSign's Global ID Certificate
product. The Global ID certificate contains the extra information necessary to implement
SGC and International Step-up.

54

Chapter 4: Understanding and Managing X.509 Certificates

Section B: Using Keyrings and SSL Certificates

Section B: Using Keyrings and SSL Certificates
Keyrings are virtual containers, holding a public/private keypair with a customized
keylength and a certificate or certificate signing request.
Certificates can be meant for internal use (self-signed) or they can be meant for external
use.
In general, SSL certificates involve three parties:


The subject of the certificate.



The Certificate Authority (CA), which signs the certificate, attesting to the binding
between the public key in the certificate and the subject.



The "relying party,” which is the entity that trusts the CA and relies on the certificate
to authenticate the subject.

Keyrings and certificates are used in:


Encrypting data.



Digitally Signing Access Logs.



Authenticating end users.



Authenticating an SG appliance.

The steps in creating keyrings and certificates include:


Create a keyring. A default keyring is shipped with the system and is used for
accessing the Management Console, although you can use others. You can also use the
default keyring for other purposes. You can create other keyrings for each SSL service.
(See “Creating a Keyring” on page 56.)
Note: You can also import keyrings. For information on importing keyrings, see
“Importing an Existing Keypair and Certificate” on page 67.



(Optional) Create Certificate Signing Requests (CSRs) to be sent to Certificate Signing
Authorities (CAs).



Import X.509 certificates issued by trusted CA authorities for external use and
associate them with the keyring. (See “Managing SSL Certificates” on page 60.)
-orCreate certificates and associate them with the keyring. (See “Creating Self-Signed
SSL Certificates” on page 61.)



(Optional, if using SSL Certificates from CAs) Import Certificate Revocation Lists
(CRLs) so the SG appliance can verify that certificates are still valid.



Creating an HTTP Reverse Proxy Service and associating the keyring with the service.
(Refer to Volume 2: Proxies and Proxy Services.)

Note: These steps must be done using a secure connection such as HTTPS, SSH, or a

serial console.

55

Volume 4: Securing the Blue Coat SG Appliance
Section B: Using Keyrings and SSL Certificates
The grayed-out Keyring field becomes enabled, allowing you to paste in an
already existing private key. Any certificate or certificate request associated with
this private key must be imported separately. For information on importing a
certificate, see “Importing a Server Certificate” on page 62.
If the private key that is being imported has been encrypted with a password,
select Keyring Password and enter the password into the field.
Note: The only way to retrieve a keyring's private key from the SG appliance is
by using Director or the command line —it cannot be exported through the
Management Console.

4.

Click OK.

To view or edit a keyring:
1.

Select Configuration > SSL > Keyrings > SSL Keyrings.

2.

Click View/Edit.

Related CLI Syntax to Create an SSL Keyring
SGOS#(config) ssl
SGOS#(config ssl) create keyring {show | show-director | no-show}
keyring_id [key_length]

Notes


To view the keypair in an encrypted format, you can optionally specify des or des3
before the keyring_id, along with an optional password. If the optional password is
provided on the command line, the CLI does not prompt for a password.



If the optional password is not provided on the command line, the CLI asks for the
password (interactive). If you specify either des or des3, you are prompted.



To view the keypair in unencrypted format, select either the optional keyring_id or
use the unencrypted command option.



You cannot view a keypair over a Telnet connection because of the risk that it could be
intercepted.

Deleting an Existing Keyring and Certificate
To delete a keyring and the associated certificate:
1.

Select Configuration > SSL > Keyrings > SSL Keyrings.

2.

Highlight the name of the keyring to delete.

3.

Click Delete.
The Confirm delete dialog appears.

4.

Click OK in the Confirm delete dialog.

Related CLI Syntax to Delete a Keyring and the Associated Certificate
SGOS#(config) ssl
SGOS#(config ssl) delete keyring keyring_id

58

Volume 4: Securing the Blue Coat SG Appliance
Section C: Managing Certificates


E-mail Address—The e-mail address you enter must be 40 characters or less. A
longer e-mail address generates an error.



Company—Enter the name of the company.

5.

The Create tab displays the message: Creating....

6.

Click OK.

Related CLI Syntax to Create a CSR
SGOS#(config) ssl
SGOS#(config ssl) create signing-request keyring_id
SGOS#(config ssl) create signing-request keyring_id [attribute_value]
[attribute_value]

Viewing a Certificate Signing Request
Once a CSR is created, you must submit it to a CA in the format the CA requires. You can
view the output of a certificate signing request either through the Management Console or
the CLI.
To view the output of a certificate signing request:
1.

Select Configuration > SSL > SSL Keyrings.

2.

Click Edit/View.

3.

From the drop-down list, select the keyring for which you have created a certificate
signing request.
The certificate signing request displays in the Certificate Signing Request window
and can be copied for submission to a CA.

Managing SSL Certificates
SSL certificates can be obtained two ways:


Created on the SG appliance as a self-signed certificate
To create a SSL self-signed certificate on the SG appliance using a Certificate Signing
Request, continue with the next section.



Imported after receiving the certificate from the signing authority
If you plan to use SSL certificates issued by Certificate Authorities, the procedure is:


Obtain the keypair and Certificate Signing Requests (CSRs), either off box or on
box, and send them to the Certificate Authority for signing.



After the signed request is returned to you from the CA, you can import the
certificate into the SG appliance. To import a certificate, see “Importing a Server
Certificate” on page 62.

60

Volume 4: Securing the Blue Coat SG Appliance
Section C: Managing Certificates


Unit—Enter the name of the group that is managing the machine.



Common Name—A common name should be the one that contains the URL with

client access to that particular origin server.


Challenge—Enter a 4-16 character alphanumeric challenge.



E-mail Address—The e-mail address you enter must be 40 characters or less. A

longer e-mail address generates an error.

6.

Company—Enter the name of the company.

The Create tab displays the message: Creating.....

Related CLI Syntax to Create a Self-Signed SSL Certificate
SGOS#(config ssl) create certificate keyring_id
SGOS#(config ssl) create certificate keyring-id [attribute_value]
[attribute_value]

Example:
SGOS#(config ssl) create certificate keyring-id cn bluecoat challenge
test c US state CA company bluecoat

Importing a Server Certificate
After the CA signs the server certificate and returns it to you, you can import the
certificate onto the SG appliance.
To import a server certificate:
1.

Copy the certificate to your clipboard. Be sure to include the “Begin Certificate” and
“End Certificate” statements.

2.

Select Configuration > SSL > Keyrings.

3.

Highlight the keyring for which you want to import a certificate.

4.

Click Edit/View in the Keyrings tab.

5.

In the Certificate panel, click Import.

6.

Paste the certificate you copied into the dialog box. Click OK.
The certificate should display in the SSL Certificates Pane, associated with the keyring
you selected earlier.

Using Certificate Revocation Lists
Certificate Revocation Lists (CRLs) enable checking server and client certificates against
lists provided and maintained by CAs that show certificates that are no longer valid. Only
CRLs that are issued by a trusted issuer can be successfully verified by the SG appliance.
The CRL can be imported only when the CRL issuer certificate exists as a CA certificate on
the SG appliance.
You can determine if the SG appliance SSL certificates are still valid by checking Certificate
Revocation Lists (CRLs) that are created and issued by trusted Certificate Signing
Authorities. A certificate on the list is no longer valid.

62

Chapter 4: Understanding and Managing X.509 Certificates

Section C: Managing Certificates
Only CRLs that are issued by a trusted issuer can be verified by the SG appliance
successfully. The CRL can be imported only when the CRL issuer certificate exists as a CA
certificate on the SG appliance.
SGOS allows:


One local CRL list per certificate issuing authority.



An import of a CRL that is expired; a warning is displayed in the log.



An import of a CRL that is effective in the future; a warning is displayed in the log.

CRLs can be used for the following purposes:


Checking revocation status of client or server certificates with HTTPS Reverse Proxy.



Checking revocation status of client or server certificates with SSL proxy. (For more
information on using CRLS with the SSL proxy, refer to Volume 2: Proxies and Proxy
Services.)



SG appliance-originated HTTPS downloads (secure image download, content filter
database download, and the like).



PEM-encoded CRLs, if cut and pasted through the inline command.



DER-format (binary) CRLs, if downloaded from a URL.

To import a CRL:
You can choose from among four methods to install a CRL on the SG appliance:


Use the Text Editor, which allows you to enter the installable list (or copy and paste
the contents of an already-created file) directly onto the SG appliance.



Create a local file on your local system.



Enter a remote URL, where you placed an already-created file on an FTP or HTTP
server to be downloaded to the SG appliance.



Use the CLI inline command.

To update a CRL:
1.

Select Configuration > SSL > CRLs.

2.

Click New or highlight an existing CRL and click Edit.

3.

Give the CRL a name.

4.

From the drop-down list, select the method to use to install the CRL; click Install.


Remote URL:
Enter the fully-qualified URL, including the filename, where the CRL is located.
To view the file before installing it, click View. Click Install.
The Install CRL dialog displays. Examine the installation status that displays; click
OK.



Local File:
Click Browse to display the Local File Browse window. Browse for the CRL file on
the local system. Open it and click Install. When the installation is complete, a
results window opens. View the results, close the window, click Close.

63

Volume 4: Securing the Blue Coat SG Appliance
Section C: Managing Certificates


Text Editor:

Copy a new CRL file into the window, and click Install.
When the installation is complete, a results window opens. View the results, close
the window, click Close.
Note: The Management Console text editor can be used to enter a CRL file. You

cannot use it to enter CLI commands.
5.

Click OK; click Apply

Related CLI Syntax to Create a CRL
At the (config) command prompt, enter the following commands:
SGOS#(config) ssl
SGOS#(config ssl) create crl list_name
or
SGOS#(config) ssl
SGOS#(config ssl) inline crl CRL_list_name eof
Paste CRL here
eof

Troubleshooting Certificate Problems
Two common certificate problems are discussed below.


If the client does not trust the Certificate Signing Authority that has signed the
appliance’s certificate, an error message similar to the following appears in the event
log:
2004-02-13 07:29:28-05:00EST "CFSSL:SSL_accept error:14094416:SSL
routines:SSL3_READ_BYTES:sslv3 alert certificate unknown" 0
310000:1
../cf_ssl.cpp:1398

This commonly occurs when you use the HTTPS-Console service on port 8082, which
uses a self-signed certificate by default. When you access the Management Console
over HTTPS, the browser displays a pop-up that says that the security certificate is not
trusted and asks if you want to proceed. If you select No instead of proceeding, the
browser sends an unknown CA alert to the SG appliance.
You can eliminate the error message one of two ways:





If this was caused by the Blue Coat self-signed certificate (the certificate
associated with the default keyring), import the certificate as a trusted Certificate
Signing Authority certificate . See “Importing a Server Certificate” on page 62 for
more information.



Import a certificate on the SG appliance for use with HTTPS-Console that is
signed by a CA that a browser already trusts.

If the SG appliance’s certificate is not accepted because of a host name mismatch or it is
an invalid certificate, you can correct the problem by creating a new certificate and
editing the HTTPS-Console service to use it. For information on editing the HTTPSConsole service, refer to Volume 2: Proxies and Proxy Services.

64

Volume 4: Securing the Blue Coat SG Appliance
Section D: Using External Certificates

Digitally Signing Access Logs
You can digitally sign access logs to certify that a particular SG appliance wrote and
uploaded a specific log file. Signing is supported for both content types—text and gzip—
and for both upload types—continuous and periodic. Each log file has a signature file
associated with it that contains the certificate and the digital signature used for verifying
the log file. When you create a signing keyring (which must be done before you enable
digital signing), keep in mind the following:


The keyring must include a certificate. .



The certificate purpose must be set for smime signing. If the certificate purpose is set
to anything else, you cannot use the certificate for signing.



Add the %c parameter in the filenames format string to identify the keyring used for
signing. If encryption is enabled along with signing, the %c parameter expands to
keyringName_Certname.

For more information about digitally signing access logs, refer to Volume 8: Access Logging.

66

Volume 4: Securing the Blue Coat SG Appliance
Section E: Advanced Configuration
4.

Fill in the dialog window as follows:
a.

Show keypair allows the keys to be exported.

b.

Do not show keypair prevents the keypair from being exported.

c.

Show keypair to director is a keyring viewable only if Director is issuing the

command using a SSH-RSA connection.
Note: The choice among show, do not show and show keypair to director has
implications for whether keyrings are included in profiles and backups created by
Director. For more information, refer to the Blue Coat Director Configuration and
Management Guide.

d. Select the Import keyring radio button.
The grayed-out Keyring field becomes enabled, allowing you to paste in the
already existing keypair. The certificate associated with this keypair must be
imported separately.
If the keypair that is being imported has been encrypted with a password, select
Keyring Password and enter the password into the field.
5.

Click OK.

To import a certificate and associate it with a keyring:
1.

Copy the certificate onto the clipboard.

2.

Select Configuration > SSL > Keyrings and click Edit/View.

3.

From the drop-down list, select the keyring that you just imported.

4.

Click Import in the Certificate field.

5.

Paste the certificate into the Import Certificate dialog that appears. Be sure to include
the ----BEGIN CERTIFICATE---- and -----END CERTIFICATE---- statements.

6.

Click OK.

Related CLI Syntax to Import a Keyring
SGOS#(config ssl) inline {keyring show | show-director | no-show}
keyring_id eof
Paste keypair here
eof

Related CLI Syntax to Import a Certificate and Associate it with a Keyring
SGOS#(config) ssl
SGOS#(config ssl) inline certificate keyring_id eof
Paste certificate here
eof

68

Chapter 4: Understanding and Managing X.509 Certificates

Section E: Advanced Configuration
5.

To remove CA Certificates from the list, highlight the certificate in the Add list and
click Remove.

6.

Click OK

Related CLI Syntax to Manage CA-Certificate Lists


To enter configuration mode:
SGOS#(config ssl) create ccl list_name
SGOS#(config ssl) edit ccl list_name



The following subcommands are available:
SGOS#(config ssl ccl list_name) add ca_cert_name
SGOS#(config ssl) delete ca-certificate ca_certificate_name

To import a CA certificate:
1.

Copy the certificate to your clipboard. Be sure to include the “Begin Certificate” and
“End Certificate” statements.

2.

Select Configuration > SSL > Keyrings.

3.

Highlight the keyring for which you want to import a certificate.

4.

Click Edit/View in the Keyrings tab.

5.

In the Certificate panel, click Import.

6.

Paste the certificate you copied into the dialog box. Click OK.
The certificate should display in the SSL Certificates Pane, associated with the keyring
you selected earlier.

7.

Click Apply to commit the changes to the SG appliance.

71

Volume 4: Securing the Blue Coat SG Appliance
Section E: Advanced Configuration

72

Chapter 5: Certificate Realm Authentication

Certificate realms are useful for companies that have a Public Key Infrastructure (PKI)
in place and would like to have the SG appliance authenticate their end-users using the
client's X.509 certificates. If the users are members of an LDAP or Local group, the
Certificate Realm can also forward the user credentials to the specified authorization
realm, which determines the user’s authorization (permissions).
This section discusses the following topics:


“How Certificate Realm Works”



“Creating a Certificate Realm” on page 74



“Defining a Certificate Realm” on page 74



“Defining Certificate Realm General Properties” on page 75



“Revoking User Certificates” on page 76

How Certificate Realm Works
Once an SSL session has been established, the user is asked to select the certificate to
send to the SG appliance. If the certificate was signed by a Certificate Signing Authority
that the SG appliance trusts, including itself, then the user is considered authenticated.
The username for the user is the one extracted from the certificate during
authentication.
At this point the user is authenticated. If an authorization realm has been specified,
such as LDAP or Local, the certificate realm then passes the username to the specified
authorization realm, which figures out which groups the user belongs to.
Note:

If you authenticate with a certificate realm, you cannot also challenge for a
password.
Certificate realms do not require an authorization realm. If no authorization realm is
configured, the user cannot be a member of any group.
You do not need to specify an authorization realm if:


The policy does not make any decisions based on groups



The policy works as desired when all certificate realm-authenticated users are not in
any group

To use a Certificate Realm, you must:


Configure SSL between the client and SG appliance (for more information, see
“Using SSL with Authentication and Authorization Services” on page 41).



Enable verify-client on the HTTPS service to be used (for more information, refer to
Volume 2: Proxies and Proxy Services).



Verify that the certificate authority that signed the client's certificates is in the SG
trusted list.

73

Volume 4: Securing the Blue Coat SG Appliance

7.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

8.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

9.

Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.

10. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
11. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure a Certificate Realm


To enter configuration mode:
SGOS#(config) security certificate create-realm realm_name
SGOS#(config) security certificate edit-realm realm_name



The following commands are available:
SGOS#(config certificate realm_name) inactivity-timeout seconds
SGOS#(config certificate realm_name) refresh-time surrogate-refresh
seconds
SGOS#(config certificate realm_name) refresh-time authorizationrefresh seconds
SGOS#(config certificate realm_name) cookie {persistent {enable |
disable} | verify-ip {enable | disable}}
SGOS#(config certificate realm_name) virtual-url url

Revoking User Certificates
Using policy, you can revoke certain certificates by writing policy that denies access to
users who have authenticated with a certificate you want to revoke. You must maintain
this list on the SG appliance; it is not updated automatically.
Note: This method of revoking user certificates is meant for those with a small number of

certificates to manage.
For information on using automatically updated lists, refer to Volume 2: Proxies and Proxy
Services.
A certificate is identified by its issuer (the Certificate Signing Authority that signed it) and
its serial number, which is unique to that CA.
Using that information, you can use the following strings to create a policy to revoke user
certificates:


user.x509.serialNumber—This is a string representation of the certificate’s serial
number in HEX. The string is always an even number of characters long, so if the
number needs an odd number of characters to represent in hex, there is a leading zero.
Comparisons are case insensitive.



user.x509.issuer—This is an RFC2253 LDAP DN. Comparisons are case sensitive.



(optional) user.x509.subject: This is an RFC2253 LDAP DN. Comparisons are case
sensitive.

76

Chapter 5: Certificate Realm Authentication

Example
If you have only one Certificate Signing Authority signing user certificates, you do not
need to test the issuer. In the layer of the Local Policy file:

deny user.x509.serialnumber=11
deny user.x509.serialNumber=0F

If you have multiple Certificate Signing Authorities, test both the issuer and the serial
number. In the layer of the Local Policy file:

deny
user.x509.issuer="Email=name,CN=name,OU=name,O=company,L=city,ST=state
or province,C=country" user.x509.serialnumber=11\
deny user.x509.issuer="CN=name,OU=name,O=company, L=city,ST=state or
province,C=country" \
deny user.x509.serialnumber=2CB06E9F00000000000B

Creating the Certificate Authorization Policy
When you complete Certificate realm configuration, you can create CPL policies. Be aware
that the examples below are just part of a comprehensive authentication policy. By
themselves, they are not adequate.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file and other
layers.
Be aware that the default policy condition for these examples is allow. On new SGOS 5.x
systems, the default policy condition is deny.


Every Certificate realm authenticated user is allowed access the SG appliance.

authenticate(CertificateRealm)



A subnet definition determines the members of a group, in this case, members of the
Human Resources department. (They are allowed access to the two URLs listed.
Everyone else is denied permission.)

authenticate(CertificateRealm)

Define subnet HRSubnet
192.168.0.0/16
10.0.0.0/24
End subnet HRSubnet
[Rule] client_address=HRSubnet
url.domain=monster.com
url.domain=hotjobs.com
deny
.
.
.
[Rule]
deny

77

Volume 4: Securing the Blue Coat SG Appliance

Tips
If you use a certificate realm and see an error message similar to the following
Realm configuration error for realm "cert": connection is not SSL.

This means that certificate authentication was requested for a transaction, but the
transaction was not done on an SSL connection, so no certificate was available.
This can happen in three ways:


The authenticate mode is either origin-IP-redirect/origin-cookie-redirect or
origin-IP/origin-cookie, but the virtual URL does not have an https: scheme.
This is likely if authentication through a certificate realm is selected with no other
configuration, because the default configuration does not use SSL for the virtual URL.



In a server accelerator deployment, the authenticate mode is origin and the
transaction is on a non-SSL port.



The authenticate mode is origin-IP-redirect/origin-cookie-redirect, the user
has authenticated, the credential cache entry has expired, and the next operation is a
POST or PUT from a browser that does not handle 307 redirects (that is, from a
browser other than Internet Explorer). The workaround is to visit another URL to
refresh the credential cache entry and then try the POST again.



Forms authentication modes cannot be used with a Certificate realm. If a form mode
is in use and the authentication realm is a Certificate realm, a Policy Substitution
realm, or an IWA realm, you receive a configuration error.

78

Chapter 6: Oracle COREid Authentication

The SG appliance can be configured to consult an Oracle COREid (formerly known as
Oracle NetPoint) Access Server for authentication and session management decisions.
This requires that a COREid realm be configured on the SG appliance and policy
written to use that realm for authentication.
The SG appliance supports authentication with Oracle COREid v6.5 and v7.0.
Access to the COREid Access System is done through the Blue Coat Authentication and
Authorization Agent (BCAAA), which must be installed on a Windows 2000 system or
higher with access to the COREid Access Servers.

Understanding COREid Interaction with Blue Coat
Within the COREid Access System, BCAAA acts as a custom AccessGate. It
communicates with the COREid Access Servers to authenticate the user and to obtain a
COREid session token, authorization actions, and group membership information.
HTTP header variables and cookies specified as authorization actions are returned to
BCAAA and forwarded to the SG appliance. They can (as an option) be included in
requests forwarded by the appliance.
Within the SG system, BCAAA acts as its agent to communicate with the COREid
Access Servers. The SG appliance provides the user information to be validated to
BCAAA, and receives the session token and other information from BCAAA.
Each SG COREid realm used causes the creation of a BCAAA process on the Windows
host computer running BCAAA. When a process is created, a temporary working
directory containing the Oracle COREid files needed for configuration is created for
that process. A single host computer can support multiple SG realms (from the same or
different SG appliances); the number depends on the capacity of the BCAAA host
computer and the amount of activity in the realms.
Configuration of the SG COREid realm must be coordinated with configuration of the
Access System. Each must be aware of the AccessGate. In addition, certain
authorization actions must be configured in the Access System so that BCAAA gets the
information the SG appliance needs.

Configuring the COREid Access System
Note: Blue Coat assumes you are familiar with the configuration of the COREid
Access System and WebGates.

Since BCAAA is an AccessGate in the COREid Access System, it must be configured in
the Access System just like any other AccessGate. BCAAA obtains its configuration
from the SG appliance so configuration of BCAAA on the host computer is not
required. If the Cert Transport Security Mode is used by the Access System, then the
certificate files for the BCAAA AccessGate must reside on BCAAA’s host computer.

79

Volume 4: Securing the Blue Coat SG Appliance

COREid protects resources identified by URLs in policy domains. A SG COREid realm is
associated with a single protected resource. This could be an already existing resource in
the Access System, (typical for a reverse proxy arrangement) or it could be a resource
created specifically to protect access to SG services (typical for a forward proxy).
Important: The request URL is not sent to the Access System as the requested resource;
the requested resource is the entire SG realm. Access control of individual URLs is done
on the SG appliance using policy.
The COREid policy domain that controls the protected resource must use one of the
challenge methods supported by the SG appliance.
Supported challenge methods are Basic, X.509 Certificates and Forms. Acquiring the
credentials over SSL is supported as well as challenge redirects to another server.
The SG appliance requires information about the authenticated user to be returned as
COREid authorization actions for the associated protected resource. Since authentication
actions are not returned when a session token is simply validated, the actions must be
authorization and not authentication actions.
The following authorization actions should be set for all three authorization types
(Success, Failure, and Inconclusive):


A HeaderVar action with the name BCSI_USERNAME and with the value corresponding
to the simple username of the authenticated user. For example, with an LDAP
directory this might be the value of the cn attribute or the uid attribute.



A HeaderVar action with the name BCSI_GROUPS and the value corresponding to the
list of groups to which the authenticated user belongs. For example, with an LDAP
directory this might be the value of the memberOf attribute.

Once the COREid AccessGate, authentication scheme, policy domain, rules, and actions
have been defined, the SG appliance can be configured.

Additional COREid Configuration Notes
The SG appliance's credential cache only caches the user's authentication information for
the lesser of the two values of the time-to-live (TTL) configured on the SG appliance and
the session TTL configured in the Access System for the AccessGate.

Configuring the SG Realm
The SG realm must be configured so that it can:


Communicate with the Blue Coat agent(s) that act on its behalf (hostname or IP
address, port, SSL options, and the like).



Provide BCAAA with the information necessary to allow it to identify itself as an
AccessGate (AccessGate id, shared secret).



Provide BCAAA with the information that allows it to contact the primary COREid
Access Server (IP address, port, connection information).



Provide BCAAA with the information that it needs to do authentication and collect
authorization information (protected resource name), and general options (off-box
redirection).

For more information on configuring the SG COREid realm, see “Creating a COREid
Realm” on page 82.

80

Chapter 6: Oracle COREid Authentication

Note: All SG appliance and agent configuration is done on the appliance. The appliance
sends the necessary information to BCAAA when it establishes communication.

Participating in a Single Sign-On (SSO) Scheme
The SG appliance can participate in SSO using the encrypted ObSSOCookie cookie. This
cookie is set in the browser by the first system in the domain that authenticates the user;
other systems in the domain obtain authentication information from the cookie and so do
not have to challenge the user for credentials. The SG appliance sets the ObSSOCookie
cookie if it is the first system to authenticate a user, and authenticates the user based on
the cookie if the cookie is present.
Since the SSO information is carried in a cookie, the SG appliance must be in the same
cookie domain as the servers participating in SSO. This imposes restrictions on the
authenticate.mode() used on the SG appliance.


A reverse proxy can use any origin mode.



A forward proxy must use one of the origin-redirect modes (such as origincookie-redirect). When using origin-*-redirect modes, the virtual URL's
hostname must be in the same cookie domain as the other systems. It cannot be an IP
address; the default www.cfauth.com does not work either.

When using origin-*-redirect, the SSO cookie is automatically set in an appropriate
response after the SG appliance authenticates the user. When using origin mode (in a
reverse proxy), setting this cookie must be explicitly specified by the administrator using
the policy substitution variable $(x-agent-sso-cookie). The variable $(x-agent-ssocookie) expands to the appropriate value of the set-cookie: header.

Avoiding SG Appliance Challenges
In some COREid deployments all credential challenges are issued by a central
authentication service. Protected services do not challenge and process request
credentials; instead, they work entirely with the SSO token. If the request does not include
an SSO token, or if the SSO token is not acceptable, the request is redirected to the central
service, where authentication occurs. Once authentication is complete, the request is
redirected to the original resource with a response that sets the SSO token.
If the COREid authentication scheme is configured to use a forms-based authentication,
the SG appliance redirects authentication requests to the form URL automatically. If the
authentication scheme is not using forms authentication but has specified a challenge
redirect URL, the SG appliance only redirects the request to the central service if alwaysredirect-offbox is enabled for the realm on the SG. If the always-redirect-offbox
option is enabled, the authentication scheme must use forms authentication or have a
challenge redirect URL specified.
Note: The SG appliance must not attempt to authenticate a request for the off-box
authentication URL. If necessary, authenticate(no) can be used in policy to prevent
this.

81

Chapter 6: Oracle COREid Authentication

2.

From the Realm name drop-down list, select the COREid realm for which you want to
change properties.

3.

If needed, change the COREid realm display name. The default value for the display
name is the realm name. The display name cannot be greater than 128 characters and
it cannot be null.

4.

Select the Use the same refresh time for all check box if you would like to use the same
refresh time for all.

5.

Enter the number of seconds in the Credential refresh time field. The Credential
Refresh Time is the amount of time basic credentials (username and password) are
kept on the SG appliance. This feature allows the SG appliance to reduce the load on
the authentication server and enables credential spoofing. It has a default setting of
900 seconds (15 minutes). You can configure this in policy for better control over the
resources as policy overrides any settings made here.
Before the refresh time expires, the SG appliance will authenticate the user supplied
credentials against the cached credentials. If the credentials received do not match the
cached credentials, they are forwarded to the authentication server in case the user
password changed. After the refresh time expires, the credentials are forwarded to the
authentication server for verification.

6.

Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.

7.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

8.

If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.

9.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

85

Volume 4: Securing the Blue Coat SG Appliance

10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. Specify the virtual URL to redirect the user to when they need to be challenged by the
SG appliance. If the appliance is participating in SSO, the virtual hostname must be in
the same cookie domain as the other servers participating in the SSO. It cannot be an
IP address or the default, www.cfauth.com.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure a COREid Realm


To enter configuration mode:
SGOS#(config) security coreid create-realm realm_name
SGOS#(config) security coreid edit-realm realm_name



The following subcommands are available:
SGOS#(config coreid realm_name) primary-agent {host hostname | port
port_number}
SGOS#(config coreid realm_name) alternate-agent {host hostname | port
port_number}
SGOS#(config coreid realm_name) ssl enable
SGOS#(config coreid realm_name) ssl-verify-agent enable
SGOS#(config coreid realm_name) sso-type {query-client | query-dc |
query-dc-client}
SGOS#(config coreid realm_name) inactivity-timeout seconds
SGOS#(config coreid
seconds
SGOS#(config coreid
refresh seconds
SGOS#(config coreid
SGOS#(config coreid
| verify-ip {enable

realm_name) refresh-time credential-refresh
realm_name) refresh-time rejected-credentialsrealm_name) refresh-time surrogate-refresh seconds
realm_name) cookie {persistent {enable | disable}
| disable}}

SGOS#(config coreid realm_name) virtual-url url

Creating the CPL
You can create CPL policies now that you have completed COREid realm configuration.
Be aware that the examples below are just part of a comprehensive authentication policy.
By themselves, they are not adequate for your purposes.
The examples below assume the default policy condition is allow. On new SGOS 5.x
systems, the default policy condition is deny.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file and other
layers.


Every COREid-authenticated user is allowed access the SG appliance.

authenticate(COREidRealm)

86

Chapter 6: Oracle COREid Authentication



Group membership is the determining factor in granting access to the SG appliance.

authenticate(COREidRealm)

group=”cn=proxyusers, ou=groups, o=myco”
deny

87

Volume 4: Securing the Blue Coat SG Appliance

88

Chapter 7: Forms-Based Authentication

You can use forms-based authentication exceptions to control what your users see
during authentication. You can:


Specify the realm the user is to authenticate against.



Specify that the credentials requested are for the SG appliance. This avoids
confusion with other authentication challenges.



Make the form comply with company standards and provide other information,
such as a help link.

The authentication form (an HTML document) is served when the user makes a
request and requires forms-based authentication. If the user successfully authenticates
to the SG appliance, the appliance redirects the user back to the original request.
If the user does not successfully authenticate against the SG appliance and the error is
user-correctable, the user is presented with the authentication form again.
Note: You can configure and install an authentication form and several
properties through the Management Console and the CLI, but you must use policy
to dictate the authentication form’s use.

With forms-based authenticating, you can set limits on the maximum request size to
store and define the request object expiry time. You can also specify whether to verify
the client’s IP address against the original request and whether to allow redirects to the
original request.
To create and put into use forms-based authentication, you must complete the
following steps:


Create a new form or edit one of the existing authentication form exceptions



Set storage options



Set policies

89

Volume 4: Securing the Blue Coat SG Appliance
Section A: Understanding Authentication Forms

Section A: Understanding Authentication Forms
Three authentication forms are created initially:


authentication_form: Enter Proxy Credentials for Realm $(cs-realm). This is the
standard authentication form that is used for authentication with the SG appliance.



new_pin_form: Create New PIN for Realm $(cs-realm). This form is used if you
created a RADIUS realm using RSA SecurID tokens. This form prompts the user to
enter a new PIN. The user must enter the PIN twice in order to verify that it was
entered correctly.



query_form: Query for Realm $(cs-realm). This form is used if you created a RADIUS
realm using RSA SecurID tokens. The form is used to display the series of yes/no
questions asked by the SecurID new PIN process.

You can customize any of the three initial authentication form exceptions or you can create
other authentication forms. (You can create as many authentication form exceptions as
needed. The form must be a valid HTML document that contains valid form syntax.)
Each authentication form can contain the following:


Title and sentence instructing the user to enter SG credentials for the appropriate
realm.



Domain: Text input with maximum length of 64 characters The name of the input
must be PROXY_SG_DOMAIN, and you can specify a default value of $(x-cs-authdomain) so that the user's domain is prepopulated on subsequent attempts (after a
failure).
The input field is optional, used only if the authentication realm is an IWA realm. If it
is used, the value is prepended to the username value with a backslash.



Username: Text input with maximum length of 64 characters. The name of the input
must be PROXY_SG_USERNAME, and you can specify a default value of $(csusername)

so the username is prepopulated on subsequent attempts (after a

failure).


Password: The password should be of type PASSWORD with a maximum length
of 64 characters. The name of the input must be PROXY_SG_PASSWORD.



Request ID: If the request contains a body, then the request is stored on the SG
appliance until the user is successfully authenticated.

The request ID should be of type HIDDEN. The input name must be
PROXY_SG_REQUEST_ID, and the value must be $(x-cs-auth-request-id). The
information to identify the stored request is saved in the request id variable.


Challenge State: The challenge state should be of type HIDDEN. If a RADIUS
realm is using a response/challenge, this field is used to cache identification
information needed to correctly respond to the challenge.
The input name must be PROXY_SG_PRIVATE_CHALLENGE_STATE, and the value must
be $(x-auth-private-challenge-state).



Submit button. The submit button is required to submit the form to the SG appliance.



Clear form button.The clear button is optional and resets all form values to their
original values.

90

Chapter 7: Forms-Based Authentication

Section A: Understanding Authentication Forms


Form action URI: The value is the authentication virtual URL plus the query string
containing the base64 encoded original URL $(x-cs-auth-form-action-url).



Form METHOD of POST. The form method must be POST. The SG appliance does not
process forms submitted with GET.

The SG appliance only parses the following input fields during form submission:


PROXY_SG_USERNAME

(required)



PROXY_SG_PASSWORD

(required)



PROXY_SG_REQUEST_ID



PROXY_SG_PRIVATE_CHALLENGE_STATE (required)



PROXY_SG_DOMAIN (optional) If specified, its value is prepended to the username and
separated with a backslash.

(required)

Authentication_form
The initial form, authentication_form, looks similar to the following:


Enter Proxy Credentials for Realm $(cs-realm)


Enter Proxy Credentials for Realm $(cs-realm)

Reason for challenge: $(exception.last_error)

$(x-auth-challenge-string)


$(x-cs-auth-form-domain-field)

Username: VALUE=$(cs-username)>


Password: MAXLENGTH="64">



VALUE=$(x-auth-private-challenge-state)>



$(exception.contact)



If the realm is an IWA realm, the $(x-cs-auth-form-domain-field) substitution
expands to:

Domain:

If you specify $(x-cs-auth-form-domain-field), you do not need to explicitly add the
domain input field.
For comparison, the new_pin_form and query_form look similar to the following:

91

Volume 4: Securing the Blue Coat SG Appliance
Section A: Understanding Authentication Forms

New_pin_form


Create New PIN for Realm $(cs-realm)
<!-function validatePin() {<br />var info;<br />var pin = document.pin_form.PROXY_SG_PASSWORD;<br />if (pin.value != document.pin_form.PROXY_SG_RETYPE_PIN.value) {<br />info = "The PINs did not match. Please enter them again.";<br />} else {<br />// Edit this regular expression to match local PIN<br />definition<br />var re=/^[A-Za-z0-9]{4,16}$/<br />var match=re.exec(pin.value);<br />if (match == null) {<br />info = "The PIN must be 4 to 16 alphanumeric<br />characters";<br />} else {<br />return true;<br />}<br />}<br />alert(info);<br />pin.select();<br />pin.focus();<br />return false;<br />}// --><br />


Create New PIN for Realm $(cs-realm)

$(x-auth-challenge-string)


$(x-cs-auth-form-domain-field)

Enter New Pin: MAXLENGTH="64">


Retype New Pin: MAXLENGTH="64">







$(exception.contact)



92

Chapter 7: Forms-Based Authentication

Section A: Understanding Authentication Forms

Query_form


Query for Realm $(cs-realm)


Query for Realm $(cs-realm)

$(x-auth-challenge-string)


$(x-cs-auth-form-domain-field)




ONCLICK="PROXY_SG_PASSWORD.value='Y'">

P>


$(exception.contact)




User/Realm CPL Substitutions for Authentication Forms
CPL user/realm substitutions that are common in authentication form exceptions are
listed below. The syntax for a CPL substitution is:
$(CPL_substitution)
group

user-name

x-cs-auth-request-id

groups

user.x509.issuer

x-cs-auth-domain

realm

user.x509.serialNumber

x-cs-auth-form-domain-field

user

user.x509.subject

x-cs-auth-form-action-url

cs-realm

x-cs-auth-request-id

x-auth-challenge-string

x-auth-private-challengestate

Note: Any substitutions that are valid in CPL and in other exceptions are valid in

authentication form exceptions.
For a discussion of CPL and a complete list of CPL substitutions, as well as a description
of each substitution, refer to Volume 10: Blue Coat SG Appliance Content Policy Language
Guide.

93

Volume 4: Securing the Blue Coat SG Appliance
Section A: Understanding Authentication Forms

Tip
There is no realm restriction on the number of authentication form exceptions you can
create. You can have an unlimited number of forms, although you might want to make
them as generic as possible to cut down on maintenance.

94

Volume 4: Securing the Blue Coat SG Appliance
Section C: Setting Storage Options
Related CLI Syntax to Set Storage Options
SGOS#(config) security request-storage max-size megabytes
SGOS#(config) security request-storage expiry-time seconds
SGOS#(config) security request-storage verify-ip enable | disable
SGOS#(config) security request-storage allow-redirects enable |
disable

98

Chapter 7: Forms-Based Authentication

Section D: Using CPL with Forms-Based Authentication

Section D: Using CPL with Forms-Based Authentication
To use forms-based authentication, you must create policies that enable it and also control
which form is used in which situations. A form must exist before it can be referenced in
policy.


Which form to use during authentication is specified in policy using one of the CPL
conditions authenticate.form(form_name),
authenticate.new_pin_form(form_name), or authenticate.query_form
(form_name).

These conditions override the use of the initial forms for the cases where a new pin
form needs to be displayed or a query form needs to be displayed. All three of the
conditions verify that the form name has the correct type.
Note: Each of these conditions can be used with the form authentication modes only.
If no form is specified, the form defaults to the CPL condition for that form. That is, if
no name is specified for authenticate.form(form_name), the default is
authentication_form; if no name is specified for
authenticate.new_pin_form(form_name), the default is
authenticate.new_pin_form, and if no name is specified for
authenticate.query_form(form_name), the default is authenticate.query_form.


Using the authentication.mode( ) property selects a combination of challenge type
and surrogate credentials. The authentication.mode( ) property offers several
options specifically for forms-based authentication:


Form-IP—The user’s IP address is used as a surrogate credential. The form is
presented whenever the user’s credential cache entry expires.



Form-Cookie—Cookies are used as surrogate credentials. The cookies are set on
the OCS domain only, and the user is presented with the form for each new
domain. This mode is most useful in reverse proxy scenarios where there are a
limited number of domains.



Form-Cookie-Redirect—The user is redirected to the authentication virtual URL
before the form is presented. The authentication cookie is set on both the virtual
URL and the OCS domain. The user is only challenged when the credential cache
entry expires.



Form-IP-redirect —This is similar to Form-IP except that the user is redirected to
the authentication virtual URL before the form is presented.



If you authenticate users who have third-party cookies explicitly disabled, you can
use the authenticate.use_url_cookie( ) property.



Since the authentication.mode( ) property is defined as a form mode (above) in
policy, you do not need to adjust the default authenticate mode through the CLI.



Using the authenticate.redirect_stored_requests(yes|no) action allows
granularity in policy over the global allow redirect config option.

For information on using these CPL conditions and properties, refer to Volume 10: Blue
Coat SG Appliance Content Policy Language Guide.

99

Volume 4: Securing the Blue Coat SG Appliance
Section D: Using CPL with Forms-Based Authentication

Tips


If the user is supposed to be challenged with a form on a request for an image or
video, the SG appliance returns a 403 error page instead of the form. If the reason for
the challenge is that the user's credentials have expired and the object is from the same
domain as the container page, then reloading the container page results in the user
receiving the authentication form and being able to authenticate. However, if the
client browser loads the container page using an existing authenticated connection,
the user might still not receive the authentication form.
Closing and reopening the browser should fix the issue. Requesting a different site
might also cause the browser to open a new connection and the user is returned the
authentication form.
If the container page and embedded objects have a different domain though and the
authentication mode is form-cookie, reloading or closing and reopening the browser
might not fix the issue, as the user is never returned a cookie for the domain the object
belongs to. In these scenarios, Blue Coat recommends that policy be written to either
bypass authentication for that domain or to use a different authentication mode such
as form-cookie-redirect for that domain.



Forms-based authentication works with HTTP browsers only.



Because forms only support Basic authentication, authentication-form exceptions
cannot be used with a Certificate realm. If a form is in use and the authentication
realm is or a Certificate realm, you receive a configuration error.



User credentials are sent in plain text. However, they can be sent securely using SSL if
the virtual URL is HTTPS.



Because not all user requests support forms (such as WebDAV and streaming), create
policy to bypass authentication or use a different authentication mode with the same
realm for those requests.

100

Chapter 8: IWA Realm Authentication and Authorization

Integrated Windows Authentication (IWA) is an authentication mechanism available
on Windows networks. (The name of the realm has been changed from NTLM to IWA.)
IWA is a Microsoft-proprietary authentication suite that allows Windows clients
(running on Windows 2000 and higher) to automatically choose between using
Kerberos and NTLM authentication challenge/response, as appropriate. When an IWA
realm is used and a resource is requested by the client from the SG appliance, the
appliance contacts the client's domain account to verify the client's identity and request
an access token. The access token is generated by the domain controller (in case of
NTLM authentication) or a Kerberos server (in the case of Kerberos authentication) and
passed to (and if valid, accepted by) the SG appliance.
Refer to the Microsoft Web site for detailed information about the IWA protocol.
This section discusses the following topics:


“How Blue Coat Works with IWA”



“Creating an IWA Realm” on page 101



“IWA Servers” on page 102



“Defining IWA Realm General Properties” on page 103



“Creating the CPL” on page 107

How Blue Coat Works with IWA
The server side of the Kerberos or NTLM authentication exchange is handled by the
Blue Coat Authentication and Authorization Agent (BCAAA).
A single BCAAA service can support multiple SG appliances; however, the service
starts a processor agent for each realm that only handles authentication requests
coming from that particular realm.
BCAAA must be installed on a domain controller or member server. If the server where
the BCAAA service is installed and its domain have a trust relationship with other
domains, the user is authenticated automatically by the other domains.
For a server to participate in an IWA Kerberos authentication exchange, it must share a
secret with the Kerberos server (called a KDC) and have registered an appropriate
Service Principal Name.
For instructions on installing the BCAAA service and configuring a Service Principal
Name, see Appendix B: "Using the Authentication/Authorization Agent" on page
215.

Creating an IWA Realm
To create an IWA realm, you must provide at least the primary host of the IWA server
for that realm.
To create an IWA realm:
1.

Select Configuration > Authentication > IWA > IWA Realms.

101

Chapter 8: IWA Realm Authentication and Authorization

4.

(Optional) Specify the host and port for the alternate IWA server. The default port is
16101.

5.

(Optional) Under SSL Options, click the SSL enable checkbox to enable SSL.

6.

(Optional) By default, if SSL is enabled, the BCAAA certificate is verified. If you do
not want to verify the BCAAA certificate, deselect this checkbox.

7.

In the Timeout Request field, type the number of seconds the SG appliance allows for
each request attempt before timing out. (The default request timeout is 60 seconds.)

8.

You can enable or disable support for Basic credentials in the realm by selecting or
deselecting the Allow Basic credentials checkbox.
At least one Basic or NTLM/Kerberos credential must be enabled. Note that Basic
credentials cannot be disabled in the IWA realm if the IWA realm is part of a sequence
realm but is not the first realm in the sequence with try IWA authentication only once
enabled.
You can disable both NTLM and Kerberos credentials, leaving a realm that collects
plaintext credentials but validates them against a Windows domain.
Important: The configuration of the realm can have significant security implications.
If an IWA realm accepts Basic credentials, the client can automatically downgrade to
sending the password in plaintext. Similarly, the client can use NTLM instead of
Kerberos.

9.

(Optional) You can enable or disable support for NTLM credentials in the realm by
selecting or deselecting the Allow NTLM credentials checkbox. You can only enable
support for Kerberos credentials in the realm if support for NTLM credentials has
been enabled.

10. (Optional) You can enable or disable support for Kerberos credentials in the realm by
selecting or deselecting the Allow Kerberos credentials.You can only enable support
for Kerberos credentials in the realm if support for NTLM credentials has been
enabled.
11. Select Apply to commit the changes to the SG appliance.
12. Repeat the above steps for additional IWA realms, up to a total of 40.

Defining IWA Realm General Properties
The IWA General tab allows you to specify the display name, the refresh times, an
inactivity timeout value, cookies, and a virtual URL.
To configure IWA general settings:
1.

Select Configuration > Authentication > IWA > IWA General.

103

Chapter 8: IWA Realm Authentication and Authorization

The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

8.

If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.

9.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. In the Virtual URL field, enter the URL to redirect to when the user needs to be
challenged for credentials if using a redirecting authenticate.mode.
Note: The virtual URL is not involved if the challenge does not redirect.

You can specify a virtual URL based on the individual realm. For more information on
the virtual URL, see “Understanding Origin-Style Redirection” on page 34.
When NTLM is in use, requests to the virtual URL must be sent to the proxy. This can
be done either by transparent redirection or by making the virtual URL hostname
resolve to an IP address of the proxy.
When Kerberos is in use:


The virtual URL hostname must be part of the Kerberos realm (this is using the
term realm in the Kerberos sense, not the SG appliance sense).



For a forward proxy, this hostname should be added to the DNS server for the
same domain as the Kerberos protected resources so that requests for this address
go directly to the SG appliance.

In both NTLM and Kerberos, if single-sign on is desired, then the virtual URL
hostname must have no dots and must not be proxied by the browser. The client must
be able to resolve this hostname to an IP address of the proxy.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Select Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure an IWA Realm


To enter configuration mode:

105

Volume 4: Securing the Blue Coat SG Applianc

SGOS#(config) security iwa create-realm realm_name
SGOS#(config) security iwa edit-realm realm_name


The following subcommands are available:
SGOS#(config iwa realm_name) alternate-server host [port]
SGOS#(config iwa realm_name) display-name display_name
SGOS#(config iwa realm_name) ssl enable
SGOS#(config iwa realm_name) ssl-verify-agent enable
SGOS#(config iwa realm_name) sso-type {query-client | query-dc |
query-dc-client}

106

Chapter 8: IWA Realm Authentication and Authorization

SGOS#(config iwa realm_name) inactivity-timeout seconds
SGOS#(config iwa realm_name) refresh-time credential-refresh seconds
SGOS#(config iwa realm_name) refresh-time rejected-credentials-refresh
seconds
SGOS#(config iwa realm_name) refresh-time surrogate-refresh seconds
SGOS#(config iwa realm_name) cookie {persistent {enable | disable} |
verify-ip {enable | disable}}
SGOS#(config iwa realm_name) virtual-url url

Creating the CPL
You can create CPL policies now that you have completed IWA realm configuration. Be
aware that the examples below are just part of a comprehensive authentication policy. By
themselves, they are not adequate for your purposes.
The examples below assume the default policy condition is allow. On new systems, the
default policy condition is deny.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file layers.


Every IWA-authenticated user is allowed access the SG appliance.

authenticate(IWARealm)



Group membership is the determining factor in granting access to the SG appliance.

authenticate(IWARealm)

deny

Notes


Forms authentication modes cannot be used with an IWA realm that allows only
NTLM/Kerberos credentials. If a form mode is in use and the authentication realm is
an IWA realm, you receive a configuration error.



For Windows Internet Explorer IWA users who want true single-sign-on (allowing
Internet Explorer to provide your credentials automatically when challenged), you
must set the virtual URL to a hostname that is resolvable to the IP address of the SG
appliance by the client machines. Dots (for example, 10.1.1.1) are not allowed.
Note: Firefox (1.02 and higher) allows NTLM credentials for single sign-on but not
Kerberos.

To define the information in Internet Explorer, navigate to Internet Options > Security >
Local intranet > Sites > Advanced > Web sites. (For XP, navigate to Internet Options >
Security > Internet > Custom Level, then select Automatic logon with current username
and password.)
For Windows Internet Explorer 6.x, add the virtual host address.

107

Volume 4: Securing the Blue Coat SG Applianc



If you use guest authentication, remember that IWA/NTLM realms retrieve
authorization data at the same time as the user is authenticated. In some cases, the
system can distinguish between an authentication and authorization failure. Where
the system cannot determine if the error was due to authentication or authorization,
both the authentication and authorization are considered to be failed.

108

Chapter 9: LDAP Realm Authentication and Authorization

Many companies and organizations use the Lightweight Directory Access Protocol
(LDAP) as the directory protocol of choice, enabling software to find an individual user
without knowing where that user is located in the network topography.
This section discusses the following topics:


“Overview”



“Creating an LDAP Realm” on page 110



“LDAP Servers” on page 111



“Defining LDAP Base Distinguished Names” on page 112



“LDAP Search & Groups Tab (Authorization and Group Information)” on page 114



“Customizing LDAP Objectclass Attribute Values” on page 116



“Defining LDAP General Realm Properties” on page 117



“Creating the CPL” on page 119

Overview
Blue Coat supports both LDAP v2 and LDAP v3, but recommends LDAP v3 because it
uses Transport Layer Security (TLS) and SSL to provide a secure connection between
the SG appliance and the LDAP server.
An LDAP directory, either version 2 or version 3, consists of a simple tree hierarchy. An
LDAP directory might span multiple LDAP servers. In LDAP v3, servers can return
referrals to others servers back to the client, allowing the client to follow those referrals
if desired.
Directory services simplify administration; any additions or changes made once to the
information in the directory are immediately available to all users and directoryenabled applications, devices, and SG appliances.
The SG appliance supports the use of external LDAP database servers to authenticate
and authorize users on a per-group or per-attribute basis.
LDAP group-based authentication for the SG appliance can be configured to support
any LDAP-compliant directory including:


Microsoft Active Directory Server



Novell NDS/eDirectory Server



Netscape/Sun iPlanet Directory Server



Other

The SG appliance also provides the ability to search for a single user in a single root of
an LDAP directory information tree (DIT), and to search in multiple Base Distinguished
Names (DNs).
You can configure a LDAP realm to use SSL when communicating to the LDAP server.
Configuring LDAP involves the following steps:


Creating a realm (up to 40) and configuring basic settings.

109

Volume 4: Securing the Blue Coat SG Appliance

Defining LDAP Base Distinguished Names
The SG appliance allows you to specify multiple Base Distinguished Names (DNs) to
search per realm, along with the ability to specify a specific branch of a Base DN.
A Base DN identifies the entry that is starting point of the search. You must specify at least
one non-null base-DN for LDAP authentication to succeed.
You must enter complete DNs. See the table below for some examples of distinguished
name attributes.
Table 9-1. Distinguished Name Attributes
DN Attribute Syntax

Parameter Description

c=country

Country in which the user or group resides. Examples:
c=US, c=GB.

cn=common name

Full name of person or object defined by the entry.
Examples: cn=David Smith, cn=Administrators,
cn=4th floor printer

dc=domain component

Component name of a domain. Examples: cn=David
Smith, ou=Sales, dc=MyDomain, dc=com

mail=e-mail address

User or group e-mail address.

givenName=given name

User's first name.

l=locality

Locality in which the user or group resides. This can be
the name of a city, country, township, or other
geographic regions. Examples: l=Seattle,
l=Pacific Northwest, l=King County.

o=organization

Organization to which the user or group is a member.
Examples: o=Blue Coat Inc, o=UW.

ou=organizational unit

Unit within an organization. Examples: ou=Sales,
ou=IT, ou=Compliance.

st=state or province

State or province in which the user or group resides.
Examples: st=Washington, st=Florida.

userPassword=password

Password created by a user.

streetAddress=street
address

Street number and address of user or group defined by
the entry. Example: streetAddress= 4240 North
Mary Avenue, Sunnyvale, California 94085.

sn=surname

User's last name.

telephoneNumber=telephone

User or group telephone number.

title=title

User's job title.

uid=user ID

Name that uniquely identifies the person or object
defined by the entry. Examples: uid=ssmith,
uid=kjones.

112

Chapter 9: LDAP Realm Authentication and Authorization

Some directories require a valid user to be able to perform an LDAP search; they do
not allow anonymous bind. (Active Directory is one such example.) For these
directories, you must specify a valid fully-qualified distinguished username and the
password that permits directory access privileges. (For example,
cn=user1,cn=users,dc=bluecoat,dc=com is a possible fully-qualified distinguished
name.)
To permit users to anonymously bind to the LDAP service, select Anonymous Search
Allowed. For example, with Netscape/iPlanet Directory Server, when anonymous
access is allowed, no username or password is required by the LDAP client to retrieve
information.
The LDAP directory attributes available for an anonymous client are typically a
subset of those available when a valid user distinguished name and password have
been used as search credentials.
To enforce user authentication before binding to the LDAP service, deselect
Anonymous Search Allowed, and set the Search User DN and Search User Password.
Enter a user distinguished name in the Search User DN field. This username can
identify a single user or a user object that acts as a proxy for multiple users (a pool of
administrators, for example). A search user distinguished name can be up to 512
characters long.
You can set or change the user password by clicking Change Password. This password
can be up to 64 alphanumeric characters long.
You might want to create a separate user (such as Blue Coat, for example) instead of
using an Administrator distinguished name and password.
The Dereference level field has four values—always, finding, never, searching—that
allow you to specify when to search for a specific object rather than search for the
object’s alias. The default is Always.
4.

Group Information
Membership type and Membership attribute: The SG appliance enters the appropriate
default:


Microsoft Active Directory:
Membership type: user
Membership attribute type: memberOf



Netscape/Sun iPlanet:
Membership type:group
Membership attribute type:uniqueMember



Novell NDS eDirectory
Membership type:group
Membership attribute type:member



Other
Membership type:user
Membership attribute type:member

Username type to lookup: Select either FQDN or Relative. Only one can be selected at a
time.


Relative can only be selected in the membership type is Group.



FQDN indicates that the lookup is done only on the user object. FQDN can be
selected when the membership type is either Group or User.

115

Volume 4: Securing the Blue Coat SG Appliance

Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7.

Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.

8.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

9.

If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.

10. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
11. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
12. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
13. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
14. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Manage an LDAP Realm


To enter configuration mode:
SGOS#(config) security ldap create-realm {ad | iplanet | nds | other}
realm_name [base_dn] primary_host [primary_port]
#(config) security ldap edit-realm realm_name



The following subcommands are available:
SGOS#(config ldap realm_name) alternate-server host [port]
SGOS#(config ldap realm_name) cache-duration seconds
SGOS#(config ldap realm_name) case-sensitive {disable | enable}
SGOS#(config ldap realm_name) default-group-name default_group_name

118

Chapter 9: LDAP Realm Authentication and Authorization

SGOS#(config ldap realm_name) display-name display_name
SGOS#(config ldap realm_name) distinguished-name user-attribute-type
user_attribute_type
SGOS#(config ldap realm_name) distinguished-name base-dn {add | demote
| promote | remove} {base_dn | clear}
SGOS#(config ldap realm_name) exit
SGOS#(config ldap realm_name) membership-attribute attribute_name
SGOS#(config ldap realm_name) membership-type {group | user}
SGOS#(config ldap realm_name) membership-username {full | relative}
SGOS#(config ldap realm_name) nested-group-attribute attribute_name
SGOS#(config ldap realm_name) no alternate-server
SGOS#(config ldap realm_name) no default-group-name
SGOS#(config ldap realm_name) no membership-attribute
SGOS#(config ldap realm_name) objectclass container {add | remove}
{container_objectclass | clear}
SGOS#(config ldap realm_name) objectclass group {add | remove}
{group_objectclass | clear}
SGOS#(config ldap realm_name) objectclass user {add | remove}
{user_objectclass | clear}
SGOS#(config ldap realm_name) protocol-version {2 | 3}
SGOS#(config ldap realm_name) referrals-follow {disable | enable}
SGOS#(config ldap realm_name) rename new_realm_name
SGOS#(config ldap realm_name) search anonymous {disable | enable}
SGOS#(config ldap realm_name) search dereference {always | finding |
never | searching}
SGOS#(config ldap realm_name) search
encrypted_password

encrypted-password

SGOS#(config ldap realm_name) search password password
SGOS#(config ldap realm_name) search user-dn user_dn
SGOS#(config ldap realm_name) server-type {ad | iplanet | nds | other}
SGOS#(config ldap realm_name) spoof-authentication {none | origin |
proxy}
SGOS#(config ldap realm_name) ssl enable
SGOS#(config ldap realm_name) ssl-verify-agent enable
SGOS#(config ldap realm_name) sso-type {query-client | query-dc |
query-dc-client}
SGOS#(config ldap realm_name) inactivity-timeout seconds
SGOS#(config ldap realm_name) refresh-time credential-refresh seconds
SGOS#(config ldap
refresh seconds
SGOS#(config ldap
SGOS#(config ldap
seconds
SGOS#(config ldap
verify-ip {enable

realm_name) refresh-time rejected-credentialsrealm_name) refresh-time surrogate-refresh seconds
realm_name) refresh-time authorization-refresh
realm_name) cookie {persistent {enable | disable} |
| disable}}

SGOS#(config ldap realm_name) virtual-url url

Creating the CPL
Be aware that the examples below are just part of a comprehensive authentication policy.
By themselves, they are not adequate for your purposes.

119

Volume 4: Securing the Blue Coat SG Appliance

Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file layers.
Be aware that the default policy condition for these examples is allow. The default policy
condition on new SGOS 5.x systems is deny.


Every LDAP-authenticated user is allowed access the SG appliance.

authenticate(LDAPRealm)



Group membership is the determining factor in granting access to the SG appliance.

authenticate(LDAPRealm)

group=”cn=proxyusers, ou=groups, o=myco”
deny



A subnet definition determines the members of a group, in this case, members of the
Human Resources department.

authenticate(LDAPRealm)

Define subnet HRSubnet
192.168.0.0/16
10.0.0.0/24
End subnet HRSubnet
[Rule] client_address=HRSubnet
url.domain=monster.com
url.domain=hotjobs.com
deny
.
.
.
[Rule]
deny

Notes
If you use guest authentication/authorization, note that:


LDAP realms provide split authorization, and it is possible to be successfully
authenticated but have authorization fail.



If the LDAP realm validate authorized user command is disabled and the user
does not exist in the authorization realm, authorization is considered a success and
the user is assigned to the default group if there is one configured and it is of interest
to policy.

120

Chapter 10: Local Realm Authentication and Authorization

11. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Define or Change Local Realm Properties


To enter configuration mode:
SGOS#(config) security local create-realm realm_name
SGOS#(config) security local edit-realm realm_name



The following subcommands are available:
SGOS#(config local realm_name) display-name display_name
SGOS#(config local realm_name) local-user-list local_user_list_name
SGOS#(config local realm_name) inactivity-timeout seconds
SGOS#(config local realm_name) refresh-time surrogate-refresh seconds
SGOS#(config local realm_name) refresh-time authorization-refresh
seconds
SGOS#(config local realm_name) cookie {persistent {enable | disable} |
verify-ip {enable | disable}}
SGOS#(config local realm_name) virtual-url url

Notes
If you use guest authentication/authorization, note that:


Local realms provide split authorization, and it is possible to be successfully
authenticated but have authorization fail.



If the Local realm validate authorized user command is disabled and the user
does not exist in the authorization realm, authorization is considered a success and
the user is assigned to the default group if there is one configured and it is of interest
to policy.

Defining the Local User List
Defining the local user list involves the following steps:


Create a list or customize the default list for your needs.



Upload a user list or add users and groups through the CLI.



Associate the list with the realm.

Creating a Local User List
The user list local_user_database is created on a new system or after an upgrade. It is empty
on a new system. If a password file existed on the SG appliance before an upgrade, then
the list contains all users and groups from the password file; the initial default user list is
local_user_database. If a new user list is created, the default can be changed to point to
it instead by invoking the security local-user-list default list list name
command. You can create up to 50 new lists with 10,000 users each.
Lists can be uploaded or you can directly edit lists through the CLI. If you want to upload
a list, it must be created as a text file using the .htpasswd format of the SG appliance.

123

MACH5: Configuration and Management Guide

Each user entry in the list consists of:


username



List of groups



Hashed password



Enabled/disabled boolean searches

A list that has been populated looks like this:
SGOS#(config) security local-user-list edit list_name
SGOS#(config local-user-list list_name) view
list20
Lockout parameters:
Max failed attempts: 60
Lockout duration:
3600
Reset interval:
7200
Users:
admin1
Hashed Password: $1$TvEzpZE$Z2A/OuJU3w5LnEONDHkmg.
Enabled: true
Groups:
group1
admin2
Hashed Password: $1$sKJvNB3r$xsInBU./2hhBz6xDAHpND.
Enabled: true
Groups:
group1
group2
admin3
Hashed Password: $1$duuCUt30$keSdIkZVS4RyFz47G78X20
Enabled: true
Groups:
group2
Groups:
group1
group2

To create a new empty local user list:
SGOS#(config) security local-user-list create list_name

Username
The username must be case-sensitively unique, and can be no more than 64 characters
long. All characters are valid, except for a colon (:).
A new local user is enabled by default and has an empty password.

List of Groups
You cannot add a user to a group unless the group has previously been created in the list.
The group name must be case-sensitively unique, and can be no more than 64 characters
long. All characters are valid, except for colon (:).
The groups can be created in the list; however, their user permissions are defined through
policies only.

Hashed Password
The hashed password must be a valid UNIX DES or MD5 password whose plain-text
equivalent cannot be more than 64 characters long.

124

Chapter 10: Local Realm Authentication and Authorization

To populate the local user list using an off-box .htpasswd file, continue with the next
section. To populate the local user list using the SG appliance CLI, go to “Defining the
Local User List” on page 123.

Populating a List using the .htpasswd File
To add users to a text file in .htpasswd format, enter the following UNIX htpasswd
command:
prompt> htpasswd [-c] .htpasswd username

The –c option creates a new .htpasswd file and should only be used for the very
first .htpasswd command. You can overwrite any existing .htpasswd file by using the -c
option.
After entering this command, you are prompted to enter a password for the user
identified by username. The entered password is hashed and added to the user entry in
the text file. If the -m option is specified, the password is hashed using MD5; otherwise,
UNIX DES is used.
Important: Because the -c option overwrites the existing file, do not use the option if
you are adding users to an existing .htpasswd file.
Once you have added the users to the .htpasswd file, you can manually edit the file to add
user groups. When the .htpasswd file is complete, it should have the following format:
user:encrypted_password:group1,group2,…
user:encrypted_password:group1,group2,…
Note: You can also modify the users and groups once they are loaded on the SG
appliance. To modify the list once it is on the appliance, see “Populating a Local User List
through the SG Appliance” on page 126.

Uploading the .htpasswd File
When the .htpasswd file is uploaded, the entries from it either replace all entries in the
default local user list or append to the entries in the default local user list. One default
local user list is specified on the SG appliance.
To set the default local user list use the command security local-user-list default
list list_name. The list specified must exist.
To specify that the uploaded .htpasswd file replace all existing user entries in the default
list, enter security local-user-list default append-to-default disable before
uploading the .htpasswd file.
To specify that the .htpasswd file entries should be appended to the default list instead,
enter security local-user-list default append-to-default enable.
To upload the .htpasswd file:
The .htpasswd file is loaded onto the SG appliance with a Perl script found at:
http://download.bluecoat.com/release/tools/set_auth.zip

Unzip the file, which contains the set_auth.pl script.
Note: To use the set_auth.pl script, you must have Perl binaries on the system where

the script is running.

125

MACH5: Configuration and Management Guide

To load the .htpasswd file:
prompt> set_auth.pl username password
path_to_.htpasswd_file_on_local_machine ip_address_of_the_SG

where username and password are valid administrator credentials for the SG
appliance.

Populating a Local User List through the SG Appliance
You can populate a local user list from scratch or modify a local user list that was
populated by loading an .htpasswd file.
To create a new, empty local user list:
SGOS#(config) security local-user-list create list_name

To modify an existing local user list (can be empty or contain users):


To enter configuration mode:
SGOS#(config) security local-user-list edit list_name
SGOS#(config local-user-list list_name)



The following subcommands are available:
Note:

To add users and groups to the list, enter the following commands, beginning
with groups, since they must exist before you can add them to a user account.
SGOS#(config local-user-list list_name) group create group1
SGOS#(config local-user-list list_name) group create group2
SGOS#(config local-user-list list_name) group create group3
SGOS#(config local-user-list list_name) user create username
SGOS#(config local-user-list list_name) user edit username
SGOS#(config local-user-list list_name username) group add groupname1
SGOS#(config local-user-list list_name username) group add groupname2
SGOS#(config local-user-list list_name username) password password
-orSGOS#(config local-user-list list_name username) hashed-password
hashed-password
Note: If you enter a plain-text password, the SG appliance hashes the password. If you

enter a hashed password, the appliance does not hash it again.
1.

(Optional) The user account is enabled by default. To disable a user account:
SGOS#(config local-user-list list_name username) disable
ok

2.

Repeat for each user you want added to the list.

126

Chapter 10: Local Realm Authentication and Authorization

To view the results of an individual user account:
Remain in the user account submode and enter the following command:
SGOS#(config local-user-list list_name username) view
admin1
Hashed Password: $1$TvEzpZE$Z2A/OuJU3w5LnEONDHkmg.
Enabled: true
Failed Logins: 6
Groups:
group1
Note: If a user has no failed logins, the statistic does not display.

To view the users in the entire list:
Exit the user account submode and enter:
SGOS#(config local-user-list list_name username) exit
SGOS#(config local-user-list list_name) view
list20
Lockout parameters:
Max failed attempts: 60
Lockout duration:
3600
Reset interval:
7200
Users:
admin1
Hashed Password: $1$TvEzpZE$Z2A/OuJU3w5LnEONDHkmg.
Enabled: true
Groups:
group1
admin2
Hashed Password: $1$sKJvNB3r$xsInBU./2hhBz6xDAHpND.
Enabled: true
Groups:
group1
group2
admin3
Hashed Password: $1$duuCUt30$keSdIkZVS4RyFz47G78X20
Enabled: true
Groups:
group2
Groups:
group1
group2

To view all the lists on the SG appliance:
SGOS#(config) show security local-user-list
Default List: local_user_database
Append users loaded from file to default list: false
local_user_database
Lockout parameters:
Max failed attempts: 60
Lockout duration:
3600
Reset interval:
7200

127

MACH5: Configuration and Management Guide

Users:
Groups:
test1
Users:
Groups:

To delete groups associated with a user:
SGOS#(config local-user-list list_name username) group remove
group_name

To delete users from a list:
SGOS#(config local-user-list list_name) user delete username
This will permanently delete the object. Proceed with deletion?
(y or n) y
ok

To delete all users from a list:
SGOS#(config local-user-list list_name) user clear
ok

The groups remain but have no users.
To delete all groups from a list:
SGOS#(config local-user-list list_name) group clear
ok

The users remain but do not belong to any groups.

Enhancing Security Settings for the Local User List
You can configure a local user database so that each user account is automatically disabled
if too many failed login attempts occur for the account in too short a period, indicating a
brute-force password attack on the SG appliance. The security settings are available
through the CLI only.
Available security settings are:


Maximum failed attempts: The maximum number of failed password attempts
allowed for an account. When this threshold is reached, the account is disabled
(locked). If this is zero, there is no limit. The default is 60 attempts.



Lockout duration: The time after which a locked account is re-enabled. If this is zero,
the account does not automatically re-enable, but instead remains locked until
manually enabled. The default is 3600 seconds (one hour).



Reset interval: The time after which a failed password count resets after the last failed
password attempt. If this is zero, the failed password count resets only when the
account is enabled or when its password is changed. The default is 7200 seconds (two
hours).

These values are enabled by default on the system for all user account lists. You can
change the defaults for each list that exists on the system.
To change the security settings for a specific user account list:
1.

Enter the following commands from the (config) prompt:
SGOS#(config) security local-user-list edit list_name
SGOS#(config local-user-list list_name) lockout-duration seconds
SGOS#(config local-user-list list_name) max-failed-attempts attempts

128

Chapter 10: Local Realm Authentication and Authorization

SGOS#(config local-user-list list_name) reset-interval seconds

2.

(Optional) View the settings:
SGOS#(config local-user-list list_name) view
listname
Lockout parameters:
Max failed attempts: 45
Lockout duration:
3600
Reset interval:
0

3.

(Optional) To disable any of these settings:
SGOS#(config local-user-list list_name) no [lockout-duration | maxfailed-attempts | reset-interval]

Creating the CPL
Be aware that the examples below are just part of a comprehensive authentication policy.
By themselves, they are not adequate for your purposes. (The default policy in these
examples is deny.)
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file layers.


Every Local-authenticated user is allowed access the SG appliance.

authenticate(LocalRealm)



Group membership is the determining factor in granting access to the SG appliance.

authenticate(LocalRealm)

group=”group1” allow



A subnet definition determines the members of a group, in this case, members of the
Human Resources department.

authenticate(LocalRealm)

Define subnet HRSubnet
192.168.0.0/16
10.0.0.0/24
End subnet HRSubnet
[Rule] client_address=HRSubnet
url.domain=monster.com
url.domain=hotjobs.com
deny
.
.
.
[Rule]
deny

129

MACH5: Configuration and Management Guide

130

Chapter 11: Policy Substitution Realm

A Policy Substitution realm provides a mechanism for identifying and authorizing
users based on information in the request to the SG appliance. The realm uses
information in the request and about the client to identify the user. The realm is
configured to construct user identity information by using policy substitutions.
If authorization data (such as group membership) is needed, the realm can be
configured with the name of an associated authorization realm (such as LDAP or local).
If an authorization realm is configured, the fully-qualified username is sent to the
authorization realm’s authority to collect authorization data.
You can use policy substitutions realms in many situations. For example, a Policy
Substitution realm can be configured to identify the user:


based on the results of a NetBIOS over TCP/IP query to the client computer.



based on the results of a reverse DNS lookup of the client computer's IP address.



based on the contents of a header in the request. This might be used when a
downstream device is authenticating the user.



based on the results of an Ident query to the client computer.

The Policy Substitution realm is used typically for best-effort user discovery, mainly for
logging and subsequent reporting purposes, without the need to authenticate the user.
Be aware that if you use Policy Substitution realms to provide granular policy on a user,
it might not be very secure because the information used to identify the user can be
forged.
This section discusses the following topics:


“How Policy Substitution Realms Work”



“Creating a Policy Substitution Realm” on page 134



“Configuring User Information” on page 134



“Creating a List of Users to Ignore” on page 136



“Configuring Authorization” on page 137



“Defining Policy Substitution Realm General Properties” on page 138

How Policy Substitution Realms Work
The realm is configured the same way as other realms, except that the realm uses policy
substitutions to construct the username and full username from information available
in and about the request. Any policy substitution whose value is available at client
logon can be used to provide information for the name.
The Policy Substitution realm, in addition to allowing you to create and manipulate
realm properties, such as the name of the realm and the number of seconds that
credential cache entries from this realm are valid, also contains attributes to determine
the user's identity. The user's identity can be determined by explicitly defining the
usernames or by searching a LDAP server. The following two fields are used to
determine the user's identity by definition:

131

Volume 4: Securing the Blue Coat SG Appliance



A user field: A string containing policy substitutions that describes how to construct
the simple username.



A full username field: A string containing policy substitutions that describes how to
construct the full username, which is used for authorization realm lookups. This can
either be an LDAP FQDN when the authorization realm is an LDAP realm, or a simple
name when local realms are being used for authorization.
Note:

The user field and username field must include at least one substitution that
successfully evaluates in order for the user to be considered authenticated.
If no policy substitutions exist that map directly to the user's simple and full usernames
but there are substitutions that map to attributes on the user on the LDAP server, the
user's identity can be determined by searching the LDAP server. The following fields are
used to determine the user's identity by LDAP search:


LDAP search realm: The LDAP realm on the SG appliance that corresponds to the
LDAP server where the user resides



Search filter: An LDAP search filter as defined in RFC 2254 to be used in the LDAP
search operation. Similar to the explicitly defined username and full username fields,
the search filter string can contain policy substitutions that are available based on the
user's request. The search filter string must be escaped according to RFC 2254. The
policy substitution modifier escape_ldap_filter is recommended to use with any
policy substitutions that could contain characters that need to be escaped. It will
escape the policy substitution value per RFC 2254.
Note:

The search filter must include at least one substitution that successfully
evaluates before the LDAP search will be issued and the user authenticated.


User attribute: The attribute on the search result entry that corresponds to the user's
full username. If the search result entry is a user entry, the attribute is usually the
FQDN of that entry. The user's full username is the value of the specified attribute. If
the attribute value is an FQDN, the user's simple username is the value of the first
attribute in the FQDN. If the attribute value is not an FQDN, the simple username is
the same as the full username.
Note:

Policy Substitution realms never challenge for credentials. If the username
and full username cannot be determined from the configured substitutions,
authentication in the Policy Substitution realm fails.
Remember that Policy Substitution realms do not require an authorization realm. If no
authorization realm is configured, the user is not a member of any group. The effect this
has on the user depends on the authorization policy. If the policy does not make any
decisions based on groups, you do not need to specify an authorization realm. Also, if
your policy is such that it works as desired when all Policy Substitution realm users are
not in any group, you do not have to specify an authorization realm.
Once the Policy Substitution realm is configured, you must create policy to authenticate
the user.

132

Chapter 11: Policy Substitution Realm

Note:

If all the policy substitutions fail, authentication fails. If any policy
substitution works, authentication succeeds in the realm.
Example
The following is an example of how to use substitutions with Policy Substitution realms.
Assumptions:


The user susie.smith is logged in to a Windows client computer at IP address
10.25.36.47.



The Windows messenger service is enabled on the client computer.



The client computer is in the domain AUTHTEAM.



The customer has an LDAP directory in which group information is stored. The DN
for a user's group information is
cn=username,cn=users,dc=computer_domain,dc=company,dc=com

where username is the name of the user, and computer_domain is the domain to
which the user's computer belongs.


A login script that runs on the client computer updates a DNS server so that a reverse
DNS lookup for 10.25.36.47 results in
susie.smith.authteam.location.company.com.

Results:
Under these circumstances, the following username and full username attributes might be
used:


Username: $(netbios.messenger-username)@$(client.address).

This results in [email protected]


Full username: cn=$(netbios.messenger-username),cn=users,
dc=$(netbios.computer-domain),dc=company,dc=com.

This results in cn=SUSIE.SMITH,cn=users, dc=AUTHTEAM,dc=company,dc=com.


Username: $(netbios.computer-domain)\$(netbios.messenger-username).

This results in AUTHTEAM\SUSIE.SMITH.


Username: $(client.host:label(6)).$(client.host:label(5)).

This results in SUSIE.SMITH.
Example
The following is an example of how to determine the user's identity by search.
Assumptions:


The user susie.smith is logged in to a Windows client computer.



The customer has an LDAP directory in which group information is stored. The
FQDN for Susie Smith is "cn=Susie Smith, cn=Users, dc=Eng, dc=company, dc=com".

133

Chapter 11: Policy Substitution Realm

5.

Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.

6.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

7.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

8.

Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.

9.

You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.

10. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure Policy Substitution Realm General Settings
Enter the following commands to modify Policy Substitution realm properties:
SGOS#(config policy-substitution realm_name) inactivity-timeout
seconds
SGOS#(config policy-substitution realm_name) refresh-time surrogaterefresh seconds
SGOS#(config policy-substitution realm_name) refresh-time
authorization-refresh seconds
SGOS#(config policy-substitution realm_name) cookie {persistent
{enable | disable} | verify-ip {enable | disable}}
SGOS#(config policy-substitution realm_name) virtual-url url

Notes


Following are examples of how to configure four different types of Policy Substitution
realms. For a list of available substitutions, see Volume 8: Access Logging.


Identity to be determined by sending a NetBIOS over TCP/IP query to the client
computer, and using LDAP authorization
SGOS#(config) security policy-substitution create-realm netbios
SGOS#(config) security policy-substitution edit-realm netbios
SGOS#(config policy-substitution netbios) username \
$(netbios.messenger-username)
SGOS#(config policy-substitution netbios) full-username \
cn=$(netbios.messenger-username),cn=users,dc=company,dc=com
SGOS#(config policy-substitution netbios) authorization-realm-name
ldap



Identity to be determined by reverse DNS, using local authorization. Blue Coat
assumes login scripts on the client computer update the DNS record for the client.

139

Volume 4: Securing the Blue Coat SG Appliance

SGOS#(config) security policy-substitution create-realm RDNS
SGOS#(config) security policy-substitution edit-realm RDNS
SGOS#(config policy-substitution RDNS) username \
$(client.host:label(5)).$(client.host:label(6))
#SGOS#(config policy-substitution RDNS) full-username \
$(client.host:label(5)).$(client.host:label(6))
SGOS#(config policy-substitution RDNS) authorization-realm-name
local



Identity to be determined by a header in the request, using LDAP authorization.
SGOS#(config) security policy-substitution create-realm header
SGOS#(config) security policy-substitution edit-realm header
SGOS#(config policy-substitution header) username \
$(request.x_header.username)
SGOS#(config policy-substitution header) full-username \
cn=$(request.x_header.username),cn=users,dc=company,dc=com
SGOS#(config policy-substitution header) username \ authorizationrealm-name ldap



Identity to be determined by sending an Ident query to the client computer
SGOS#(config) security policy-substitution create-realm ident
SGOS#(config) security policy-substitution edit-realm ident
SGOS#(config policy-substitution ident) username $(ident.username)
SGOS#(config policy-substitution ident) full-username
"cn=$(ident.username),cn=Users,dc=company,dc=com"



If you need to change the NetBIOS defaults of 5 seconds and 3 retries, use the nbstat
requester option from the netbios command submode. (For more information on
using the NetBIOS commands, refer to Volume 11: Blue Coat SG Appliance Command Line
Reference.)



If you need to change the Ident defaults of 30 second timeout, treating username
whitespace as significant and querying Ident port 113, use the client commands in the
identd command submode. (For more information on using the Ident commands,
refer to Volume 11: Blue Coat SG Appliance Command Line Reference.)

Creating the Policy Substitution Policy
When you complete Policy Substitution realm configuration, you must create CPL policies
for the policy-substitution realm to be used. Be aware that the example below is just part
of a comprehensive authentication policy. By themselves, they are not adequate.
Note that, for policy substitution realms, the username and group values are casesensitive.
Note:

Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for
details about CPL and how transactions trigger the evaluation of policy file
and other layers.
Be aware that the default policy condition for this example is allow. On new SGOS 5.x
systems, the default policy condition is deny.


Every Policy Substitution realm authenticated user is allowed to access the SG
appliance.

authenticate(PolicySubstitutionRealm)

140

Chapter 11: Policy Substitution Realm

Using Single Sign-On Realms and Proxy Chains
Some Application Delivery Network (ADN) configurations mask the source IP address of
the request. For example, if the path for a request is:
client workstation > branch proxy > data center proxy > gateway proxy

policy running on the gateway might see the IP address of the data center proxy rather
than the IP address of the client workstation.
Note:

The source IP address is not masked if you use the reflect client ip attribute.

In this ADN configuration, policy needs to be configured so that Windows SSO,
Novell SSO, and policy substitution realms can authenticate users correctly.
Use the user.login.address and authenticate.credentials.address policy
gestures to override the IP address of the credentials used for authentication and match
the IP address of the authenticated user.
Note: The user.login.address condition only works correctly if you use the
authenticate.credentials.address property to set the address.

You can also use the x-cs-user-login-address substitution to log this event.
Examples
In the following example, the address to use for authenticating with myrealm is set to the
address received from the HTTP Client-IP header.

authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))

In the following example, the user is authenticated if logged in from the 1.2.3.0/24 subnet.

user.login.address=1.2.3.0/24 allow

141

Volume 4: Securing the Blue Coat SG Appliance

142

Chapter 12: CA eTrust SiteMinder Authentication

The SG appliance can be configured to consult a SiteMinder policy server for
authentication and session management decisions. This requires that a SiteMinder
realm be configured on the SG appliance and policy written to use that realm for
authentication.
Access to the SiteMinder policy server is done through the Blue Coat Authentication
and Authorization Agent (BCAAA), which must be installed on a Windows 2000
system or higher with access to the SiteMinder policy servers.

Understanding SiteMinder Interaction with Blue Coat
Within the SiteMinder system, BCAAA acts as a custom Web agent. It communicates
with the SiteMinder policy server to authenticate the user and to obtain a SiteMinder
session token, response attribute information, and group membership information.
Custom header and cookie response attributes associated with OnAuthAccept and
OnAccessAccept attributes are obtained from the policy server and forwarded to the
SG appliance. They can (as an option) be included in requests forwarded by the
appliance.
Within the SG system, BCAAA acts as its agent to communicate with the SiteMinder
server. The SG appliance provides the user information to be validated to BCAAA, and
receives the session token and other information from BCAAA.
Each SG SiteMinder realm used causes the creation of a BCAAA process on the
Windows host computer running BCAAA. A single host computer can support
multiple SG realms (from the same or different SG appliances); the number depends on
the capacity of the BCAAA host computer and the amount of activity in the realms.
Note:

Each (active) SiteMinder realm on the SG appliance should reference a
different agent on the Policy Server.
Configuration of the SG’s realm must be coordinated with configuration of the
SiteMinder policy server. Each must be configured to be aware of the other. In addition,
certain SiteMinder responses must be configured so that BCAAA gets the information
the SG appliance needs.

Configuring the SiteMinder Policy Server
Note: Blue Coat assumes you are familiar with configuration of SiteMinder policy

servers and Web agents.
Since BCAAA is a Web agent in the SiteMinder system, it must be configured on the
SiteMinder policy server. Configuration of BCAAA on the host computer is not
required; the agent obtains its configuration information from the SG appliance.
A suitable Web agent must be created and configured on the SiteMinder server. This
must be configured to support 5.x agents, and a shared secret must be chosen and
entered on the server (it must also be entered in the SG SiteMinder realm
configuration).

143

Volume 4: Securing the Blue Coat SG Appliance

SiteMinder protects resources identified by URLs. An SG realm is associated with a single
protected resource. This could be an already existing resource on a SiteMinder server,
(typical for a reverse proxy arrangement) or it could be a resource created specifically to
protect access to SG services (typical for a forward proxy).
Important: The request URL is not sent to the SiteMinder policy server as the
requested resource; the requested resource is the entire SG realm. Access control of
individual URLs is done on the SG appliance using CPL or VPM.
The SiteMinder realm that controls the protected resource must be configured with a
compatible authentication scheme. The supported schemes are Basic (in plain text and
over SSL), Forms (in plain text and over SSL), and X.509 certificates. Configure the
SiteMinder realm with one of these authentication schemes.
Note: Only the following X.509 Certificates are supported: X.509 Client Cert Template,
X.509 Client Cert and Basic Template, and X.509 Client Cert and Form Template.

The SG appliance requires information about the authenticated user to be returned as a
SiteMinder response. The responses should be sent by an OnAuthAccept rule used in the
policy that controls the protected resource.
The responses must include the following:


A Web-Agent-HTTP-Header-variable named BCSI_USERNAME. It must be a user
attribute; the value of the response must be the simple username of the authenticated
user. For example, with an LDAP directory this might be the value of the cn attribute
or the uid attribute.



A Web-Agent-HTTP-Header-variable named BCSI_GROUPS. It must be a user attribute
and the value of the response must be SM_USERGROUPS.

If the policy server returns an LDAP FQDN as part of the authentication response, the SG
appliance uses that LDAP FQDN as the FQDN of the user.
Once the SiteMinder agent object, configuration, realm, rules, responses and policy have
been defined, the SG appliance can be configured.

Additional SiteMinder Configuration Notes
Note: Additional configuration might be needed on the SiteMinder server depending on
specific features being used.


If using single-sign on (SSO) with off-box redirection (such as to a forms login page),
the forms page must be processed by a 5.x or later Web Agent, and that agent must be
configured with fcccompatmode=no. This precludes that agent from doing SSO with
5.x agents.



For SSO to work with other Web agents, the other agents must have the
AcceptTPCookie=YES as part of their configuration. This is described in the
SiteMinder documentation.



Blue Coat does not extract the issuerDN from X.509 certificates in the same way as the
SiteMinder agent. Thus, a separate certificate mapping might be needed for the SGOS
agent and the SiteMinder agents.

144

Chapter 12: CA eTrust SiteMinder Authentication

For example, the following was added to the SiteMinder policy server certificate
mappings:
CN=Waterloo Authentication and Security Team,OU=Waterloo R&D, O=Blue
Coat\, Inc.,L=Waterloo,ST=ON,C=CA


In order to use off-box redirection (such as an SSO realm), all agents involved must
have the setting EncryptAgentName=no in their configurations.



The SG appliance's credential cache only caches the user's authentication information
for the smaller of the time-to-live (TTL) configured on the SG appliance and the
session TTL configured on the SiteMinder policy server.

Configuring the SG Realm
The SG realm must be configured so that it can:


Find the Blue Coat agent(s) that acts on its behalf (hostname or IP address, port, SSL
options, and the like).



Provide BCAAA with the information necessary to allow it to identify itself as a Web
agent (agent name, shared secret).



Provide BCAAA with the information that allows it to find the SiteMinder policy
server (IP address, ports, connection information.)



Provide BCAAA with the information that it needs to do authentication and collect
authorization information (protected resource name), and general options (server failover and off-box redirection)

For more information on configuring the SG SiteMinder realm, see “Creating a SiteMinder
Realm” on page 146.
Note: All SG appliance and agent configuration is done on the appliance. The appliance
sends the necessary information to BCAAA when it establishes communication.

Participating in a Single Sign-On (SSO) Scheme
The SG appliance can participate in SSO with other systems that use the same SiteMinder
policy server. Users must supply their authentication credentials only once to any of the
systems participating. Participating in SSO is not a requirement, the SG appliance can use
the SiteMinder realm as an ordinary realm.
When using SSO with SiteMinder, the SSO token is carried in a cookie (SMSESSION). This
cookie is set in the browser by the first system that authenticates the user; other systems
obtain authentication information from the cookie and so do not have to challenge the
user for credentials. The SG appliance sets the SMSESSION cookie if it is the first system to
authenticate a user, and authenticates the user based on the cookie if the cookie is present.
Since the SSO information is carried in a cookie, all the servers participating must be in the
same cookie domain, including the SG appliance. This imposes restrictions on the
authenticate.mode() used on the SG appliance.


A reverse proxy can use any origin mode.



A forward proxy must use one of the origin-redirect modes (such as origincookie-redirect). When using origin-*-redirect modes, the virtual URL
hostname must be in the same cookie domain as the other systems. It cannot be an IP
address and the default www.cfauth.com does not work either.

145

Chapter 12: CA eTrust SiteMinder Authentication

Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

8.

If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.

9.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. Specify the virtual URL to redirect the user to when they need to be challenged by the
SG appliance. If the appliance is participating in SSO, the virtual hostname must be in
the same cookie domain as the other servers participating in the SSO. It cannot be an
IP address or the default, www.cfauth.com.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure a SiteMinder Realm


To enter configuration mode:
SGOS#(config) security siteminder create-realm realm_name
SGOS#(config) security siteminder edit-realm realm_name



The following subcommands are available:
SGOS#(config siteminder realm_name) add-header-responses {enable |
disable}
SGOS#(config siteminder realm_name) alternate-agent agent-name
SGOS#(config siteminder realm_name) alternate-agent encrypted-secret
encrypted-shared-secret
SGOS#(config siteminder realm_name) alternate-agent host
SGOS#(config siteminder realm_name) alternate-agent port
SGOS#(config siteminder realm_name) alternate-agent shared-secret
secret

151

Volume 4: Securing the Blue Coat SG Appliance

SGOS#(config siteminder realm_name) alternate-agent always-redirectoffbox
SGOS#(config siteminder realm_name) always-redirect-offbox {enable |
disable}
SGOS#(config siteminder realm_name) cache-duration seconds
SGOS#(config siteminder realm_name) case-sensitive {enable | disable}
SGOS#(config siteminder realm_name) display-name display_name
SGOS#(config siteminder realm_name) exit
SGOS#(config siteminder realm_name) no alternate-agent
SGOS#(config siteminder realm_name) primary-agent agent-name
SGOS#(config siteminder realm_name) primary-agent encrypted-secret
encrypted-shared-secret
SGOS#(config siteminder realm_name) primary-agent host
SGOS#(config siteminder realm_name) primary-agent port
SGOS#(config siteminder realm_name) primary-agent shared-secret secret
SGOS#(config siteminder realm_name) primary-agent always-redirectoffbox
SGOS#(config siteminder realm_name) protected-resource-name resourcename
SGOS#(config siteminder realm_name) rename new_realm_name
SGOS#(config siteminder realm_name) server-mode {failover | roundrobin}
SGOS#(config siteminder realm_name) validate-client-ip {enable |
disable}
SGOS#(config siteminder realm_name) siteminder-server create
server_name
SGOS#(config siteminder realm_name) siteminder-server delete
server_name
SGOS#(config siteminder realm_name) siteminder-server edit server_name
SGOS#(config siteminder realm_name server_name)
SGOS#(config siteminder realm_name server_name) accounting-port
port_number
SGOS#(config siteminder realm_name server_name) authentication-port
port_number
SGOS#(config siteminder realm_name server_name) authorization-port
port_number
SGOS#(config siteminder realm_name server_name) connectionincrement number
SGOS#(config siteminder realm_name server_name) exit
SGOS#(config siteminder realm_name server_name) ip-address
ip_address
SGOS#(config siteminder realm_name server_name) max-connections
number
SGOS#(config siteminder realm_name server_name) min-connections
number
SGOS#(config siteminder realm_name server_name) timeout seconds
SGOS#(config siteminder realm_name server_name) view

152

Chapter 12: CA eTrust SiteMinder Authentication

SGOS#(config siteminder realm_name) ssl enable
SGOS#(config siteminder realm_name) ssl-verify-agent enable
SGOS#(config siteminder realm_name) sso-type {query-client | querydc | query-dc-client}
SGOS#(config siteminder realm_name) inactivity-timeout seconds
SGOS#(config siteminder realm_name) refresh-time credential-refresh
seconds
SGOS#(config siteminder realm_name) refresh-time rejectedcredentials-refresh seconds
SGOS#(config siteminder realm_name) refresh-time surrogate-refresh
seconds
SGOS#(config siteminder realm_name) cookie {persistent {enable |
disable} | verify-ip {enable | disable}}
SGOS#(config siteminder realm_name) virtual-url url

Creating the CPL
You can create CPL policies now that you have completed SiteMinder realm
configuration. Be aware that the examples below are just part of a comprehensive
authentication policy. By themselves, they are not adequate for your purposes.
The examples below assume the default policy condition is allow. On new SGOS 5.x
systems, the default policy condition is deny.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file and other
layers.


Every SiteMinder-authenticated user is allowed access the SG appliance.

authenticate(SiteMinderRealm)



Group membership is the determining factor in granting access to the SG appliance.

authenticate(LDAPRealm)

group=”cn=proxyusers, ou=groups, o=myco”
deny

153

Volume 4: Securing the Blue Coat SG Appliance

154

Chapter 13: RADIUS Realm Authentication and Authorization

RADIUS is often the protocol of choice for ISPs or enterprises with very large numbers
of users. RADIUS is designed to handle these large numbers through centralized user
administration that eases the repetitive tasks of adding and deleting users and their
authentication information. RADIUS also inherently provides some protection against
sniffing.
Some RADIUS servers support one-time passwords. One-time passwords are
passwords that become invalid as soon as they are used. The passwords are often
generated by a token or program, although pre-printed lists are also used. Using onetime passwords ensures that the password cannot be used in a replay attack.
The SG appliance’s one-time password support works with products such as Secure
Computing SafeWord synchronous and asynchronous tokens and RSA SecurID tokens.
The SG appliance supports RADIUS servers that use challenge/response as part of the
authentication process. SafeWord asynchronous tokens use challenge/response to
provide authentication. SecurID tokens use challenge/response to initialize or change
PINs.
Note: For this release, HTTP is the only supported protocol.

The challenge is displayed as the realm information in the authentication dialog; Blue
Coat recommends that you use form authentication if you create a challenge/response
realm, particularly if you use SecurID tokens.
If you set an authentication mode that uses forms, the system detects what type of
question is being asked. If it is a yes/no question, it displays the query form with a yes
and no button. If it is a new PIN question, the system displays a form with entry fields
for the new PIN.
For information on using form authentication, see Chapter 7: "Forms-Based
Authentication" on page 89.
Using policy, you can fine-tune RADIUS realms based on RADIUS attributes. If you use
the Blue Coat attribute, groups are supported within a RADIUS realm.
This section discusses the following topics:


“Creating a RADIUS Realm”



“Defining RADIUS Realm Properties” on page 156



“Defining RADIUS Realm General Properties” on page 158



“Creating the Policy” on page 160



“Troubleshooting” on page 162

155

Chapter 13: RADIUS Realm Authentication and Authorization

The Surrogate Refresh Time allows you to set a realm default for how often a user’s
surrogate credentials are refreshed. Surrogate credentials are credentials accepted in
place of a user’s actual credentials. The default setting is 900 seconds (15 minutes).
You can configure this in policy for better control over the resources as policy
overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.
7.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

8.

If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field.
This setting, enabled by default and set to one second, allows failed authentication
attempts to be automatically rejected for up to 10 seconds. Any Basic credentials that
match a failed result before its cache time expires are rejected without consulting the
back-end authentication service. The original failed authentication result is returned
for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.

9.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

10. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
11. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
12. Select the Challenge user after logout check box if the realm requires the users to enter
their credentials after they have logged out.
13. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure a RADIUS Realm


To enter configuration mode:
SGOS#(config) security radius create-realm realm_name secret primaryserver_host [primary-server_port]
-orSGOS#(config) security radius create-realm-encrypted realm_name
encrypted_secret primary_host [primary_port]



The following subcommands are available:

159

Volume 4: Securing the Blue Coat SG Appliance

SGOS#(config radius realm_name) alternate-server encrypted-secret
encrypted_secret
SGOS#(config radius realm_name) alternate-server host [port]
SGOS#(config radius realm_name) alternate-server secret secret
SGOS#(config radius realm_name) case-sensitive {disable | enable}
SGOS#(config radius realm_name) display-name display_name
SGOS#(config radius realm_name) exit
SGOS#(config radius realm_name) no alternate-server
SGOS#(config radius realm_name) one-time-passwords {disable | enable}
SGOS#(config radius realm_name) primary-server encrypted-secret
encrypted_secret
SGOS#(config radius realm_name) primary-server host [port]
SGOS#(config radius realm_name) primary-server secret secret
SGOS#(config radius realm_name) timeout seconds
SGOS#(config radius realm_name) server-charset charset
SGOS#(config radius realm_name) server-retry count
SGOS#(config radius realm_name) spoof-authentication {none | origin |
proxy}
SGOS#(config radius realm_name) inactivity-timeout seconds
SGOS#(config radius
seconds
SGOS#(config radius
refresh seconds
SGOS#(config radius
SGOS#(config radius
seconds
SGOS#(config radius
| verify-ip {enable

realm_name) refresh-time credential-refresh
realm_name) refresh-time rejected-credentialsrealm_name) refresh-time surrogate-refresh seconds
realm_name) refresh-time authorization-refresh
realm_name) cookie {persistent {enable | disable}
| disable}}

SGOS#(config radius realm_name) virtual-url url

Creating the Policy
Fine-tune RADIUS realms through attributes configured by policy—CPL or VPM. You can
also create RADIUS groups. To fine-tune RADIUS realms, continue with the next section.
To create RADIUS groups, see “Creating RADIUS Groups” on page 161.
Note: RADIUS groups can only be configured through policy. This feature is not
available through either the Management Console or the CLI.

Fine-Tuning RADIUS Realms
Fine-tune RADIUS Realms by using the following attributes in the attribute.
and has_attribute. CPL conditions and source objects in VPM.
Table 13-1. RADIUS Attributes for the attribute. and has_attribute. Conditions
RADIUS Attribute Name

CPL Gesture Name

Type (Possible Value)

Callback-ID

attribute.Callback-ID

String

Callback-Number

attribute.Callback-Number

String

160

Chapter 13: RADIUS Realm Authentication and Authorization

Table 13-1. RADIUS Attributes for the attribute. and has_attribute. Conditions (Continued)
RADIUS Attribute Name

CPL Gesture Name

Type (Possible Value)

Filter-ID

attribute.Filter-ID

String

Framed-IP-Address

attribute.Framed-IP-Address

IP Address

Framed-IP-Netmask

attribute.Framed-IP-Netmask

IP Address

Framed-MTU

attribute.Framed-MTU

Integer

Framed-Pool

attribute.Framed-Pool

Strong

Framed-Protocol

attribute.Framed-Protocol

Integer (1-6)

Framed-Route

attribute.Framed-Route

String

Idle-Timeout

attribute.Idle-Timeout

Integer

Login-LAT-Group

attribute.Login-LAT-Group

String

Login-LAT-Node

attribute.Login-LAT-Node

String

Login-LAT-Port

attribute.Login-LAT-Port

Integer

Login-LAT-Service

attribute.Login-LAT-Service

String

Login-IP-Host

attribute.Login-IP-Host

IP Address

Login-Service

attribute.Login-Service

Integer (0-7)

Login-TCP-Port

attribute.Login-TCP-Port

Integer (0-65535)

Port-Limit

attribute.Port-Limit

Integer

Service-Type

attribute.Service-Type

Integer (1-11)

Session-Timeout

attribute.Session-Timeout

Integer

Tunnel-Assignment-ID

attribute.Tunnel-Assignment-ID

String

Tunnel-Medium-Type

attribute.Tunnel-Medium-Type

Integer (1-15)

Tunnel-Private-Group-ID

attribute.Tunnel-Private-Group-ID

String

Tunnel-Type

attribute.Tunnel-Type

Integer (1-12)

Blue-Coat-Group

attribute.Blue-Coat-Group

String

Creating RADIUS Groups
You can create a RADIUS realm group by using the custom Blue Coat attribute, which can
appear multiple times within a RADIUS response. It can be used to assign a user to one or
more groups. Values that are found in this attribute can be used for comparison with the
group condition in CPL and the group object in VPM. The group name is a string with a
length from 1-247 characters. The Blue Coat Vendor ID is 14501, and the Blue-Coat-Group
attribute has a Vendor Type of 1.
If you are already using the Filter-ID attribute for classifying users, you can use that
attribute instead of the custom Blue-Coat-Group attribute. While the Filter-ID attribute
does not work with the CPL group condition or the group object in VPM, the
attribute.Filter-ID condition can be used to manage users in a similar manner.

161

Volume 4: Securing the Blue Coat SG Appliance

CPL Example
Be aware that the examples below are just part of a comprehensive authentication policy.
By themselves, they are not adequate.
Note: Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details

about CPL and how transactions trigger the evaluation of policy file layers.


Every RADIUS-authenticated user is allowed access the SG appliance if the RADIUS
attribute service-type is set.

authenticate(RADIUSRealm)

allow has_attribute.Service-Type=yes
deny



A group called RegisteredUsersGroup is allowed to access the SG appliance if the
allow group gesture is defined.

authenticate(RADIUSRealm)

allow group=RegisteredUsersGroup
deny

Troubleshooting
One of five conditions can cause the following error message:
Your request could not be processed because of a configuration error: "The request
timed out while trying to authenticate. The authentication server may be busy or offline."


The secret is wrong.



The network is so busy that all packets were lost to the RADIUS server.



The RADIUS server was slow enough that the SG appliance gave up before the server
responded.



The RADIUS servers are up, but the RADIUS server is not running. In this case, you
might also receive ICMP messages that there is no listener.



RADIUS servers machines are not running/unreachable. Depending on the network
configuration, you might also receive ICMP messages.



If you use guest authentication, remember that RADIUS realms retrieve authorization
data at the same time as the user is authenticated. In some cases, the system can
distinguish between an authentication and authorization failure. Where the system
cannot determine if the error was due to authentication or authorization, both the
authentication and authorization are considered to be failed.

Notes

162

Chapter 14: Novell Single Sign-on Authentication and
Authorization

The Novell® Single Sign-on (SSO) realm is an authentication mechanism that provides
single sign-on authentication for users that authenticate against a Novell eDirectory
server. The mechanism uses the Novell eDirectory Network Address attribute to map
the user's IP address to an LDAP FQDN. Since the mechanism is based on the user's IP
address, it only works in environments where an IP address can be mapped to a unique
user.
A Novell SSO realm consists of the following:


BCAAA service information



Novell eDirectory information



Authorization realm information



General realm information.

The Novell eDirectory information consists of a SG appliance LDAP realm that points
to the master Novell eDirectory server that it is to be searched and monitored for user
logins (see "Chapter 9: "LDAP Realm Authentication and Authorization" on page 109
for information on configuring LDAP realms) and a list of eDirectory server and port
combinations that specify additional servers to monitor for logins. Additional monitor
servers must be specified if they contain user information that is not replicated to the
master Novell eDirectory server being searched.
After a Novell SSO realm has been configured, you can write policy that authenticates
and authorizes users against the Novell SSO realm.
To ensure that users who do not successfully authenticate against the Novell SSO realm
are not challenged, administrators can use a realm sequence that contains the Novell
SSO realm and then a policy substitution realm to use when Novell SSO authentication
fails.
Note: The Novell 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, may need to use a different
realm for authentication.

This section discusses the following topics:


“How Novell SSO Realms Work” on page 164



“Creating a Novell SSO Realm” on page 165



“Novell SSO Agents” on page 165



“Adding LDAP Servers to Search and Monitor” on page 167



“Querying the LDAP Search Realm” on page 168



“Configuring Authorization” on page 169



“Defining Novell SSO Realm General Properties” on page 169

163

Volume 4: Securing the Blue Coat SG Appliance



“Modifying the sso.ini File for Novell SSO Realms” on page 171



“Creating the CPL” on page 172



“Notes” on page 173

How Novell SSO Realms Work
When a user logs into the Novell network, the user entry in Novell eDirectory is updated
with the login time and the IP address that the user logged in from and the login time. The
SG appliance uses BCAAA to do LDAP searches and monitoring of the configured
Novell eDirectory servers to obtain the user login information and maintain a user IP
address to user FQDN map.
To create the initial IP/FQDN map, the BCAAA service searches the configured master
eDirectory server for all user objects within the configured base DNs that have a Network
Address attribute. For each user entry returned, BCAAA parses the Network Address
attribute and adds the IP/FQDN entry to the map. If an existing entry exists for that IP
address, it is overwritten.
A user entry can have more than one Network Address entry in which case an entry for
each IP address is added to the map. Since service accounts can login using the same IP
address and subsequently overwrite entries for actual users, the BCAAA service has a
configurable list of the Service names to ignore. Users can be added or removed from the
list in the sso.ini file. (see “Modifying the sso.ini File for Novell SSO Realms” on page 171.)
Once the initial map has been created it is kept current by monitoring all of the eDirectory
servers that contain unique partition data for the eDirectory tree. By default, the search
server defined by the LDAP realm is monitored. If other servers contain data that is not
replicated to the search server, they must be individually monitored. When a server is
being monitored, each time a user logs in or logs out, an event message is sent to BCAAA
to update its mapping of FQDNs to IP addresses.
Multiple SG devices can talk to the same BCAAA service and can reference the same
eDirectory servers. To avoid multiple queries to the same server, the LDAP hostname and
port combination uniquely identifies an eDirectory configuration and should be shared
across devices.
To ensure that BCAAA has complete map of FQDNs to IP addresses, the realm can be
configured to do a full search of the configured master eDirectory server up to once per
day.
The BCAAA service must be version 120 or higher and must be installed on a Windows
2000+ machine that can access the eDirectory server. The BCAAA machine does not need
to have a Windows trust relationship with the eDirectory server.
Note:

For information on configuring the BCAAA service, see Appendix B: "Using
the Authentication/Authorization Agent" on page 215.

How Novell SSO Authorization Works
A Novell SSO realm can be configured to do no authorization, authorize against itself (the
default), or authorize against another valid authorization realm.
When a Novell SSO realm is configured to authorize against itself, authorization is done
through the LDAP search realm specified by the Novell SSO realm. The behavior is
similar to the Novell SSO realm explicitly selecting the LDAP realm as the authorization
realm.

164

Volume 4: Securing the Blue Coat SG Appliance

Note: You must have defined at least one Novell SSO realm (using the Novell SSO
Realms tab) before attempting to configure the BCAAA agent. If the message Realms
must be added in the Novell SSO Realms tab before editing this tab is displayed in red at
the bottom of this page, you do not currently have any Novell SSO realms defined.

3.

In the Primary agent section, enter the hostname or IP address where the BCAAA
agent resides.

4.

Change the port from the default of 16101 if necessary.

5.

(Optional) You can change the encrypted passwords for the private key and public
certificate on the BCAAA machine that are to be used for SSL communication
between the BCAAA service and the Novell eDirectory server by clicking Change
Private Key Password or Change Public Certificate Password. The location of the
private key and public certificate are specified in the sso.ini file on the BCAAA
machine. (For information on changing the location of the private key and public
certificate, see “Modifying the sso.ini File for Novell SSO Realms” on page 171.)

6.

(Optional) Enter an alternate agent host and agent name in the Alternate agent section.
Note that you can also change the passwords for the private key and public certificate
for the alternate agent, as well.
The primary and alternate BCAAA server must work together to support fail-over. If
the primary BCAAA server fails, the alternate server should be able to search and
monitor the same set of eDirectory servers.

7.

(Optional) Click Enable SSL to enable SSL between the SG appliance and the
BCAAA.

8.

(Optional) By default, if SSL is enabled, the BCAAA service’s certificate is verified. To
not verify the agent certificate, disable this setting.
Note: The Enable SSL setting only enables SSL between the SG appliance and
BCAAA. To enable SSL between BCAAA and the eDirectory server, the Enable SSL
setting must be set in the LDAP search realm.

9.

In the Timeout Request field, type the number of seconds the SG appliance allows for
each request attempt before timing out. (The default request timeout is 60 seconds.)

10. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Create and Define a Novell SSO Realm
1.

At the (config) prompt:
SGOS#(config) security novell-sso create-realm realm_name
SGOS#(config) security novell-sso edit-realm realm_name
SGOS#(config novell-sso realm_name) primary-agent {host hostname |
port port_number}
SGOS#(config novell-sso realm_name) alternate-agent {host hostname |
port port_number}
SGOS#(config novell-sso realm_name) ssl enable
SGOS#(config novell-sso realm_name) ssl-verify-agent enable
SGOS#(config novell-sso realm_name) sso-type {query-client | query-dc
| query-dc-client}

166

Chapter 14: Novell Single Sign-on Authentication and Authorization

Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will determine which user is using the
current IP address, and update the surrogate to authenticate with that user.
5.

Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.

6.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

7.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

8.

Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.

9.

You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.

10. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure General Settings
SGOS#(config novell-sso realm_name) inactivity-timeout seconds
SGOS#(config novell-sso realm_name) refresh-time surrogate-refresh
seconds
SGOS#(config novell-sso realm_name) refresh-time authorization-refresh
seconds
SGOS#(config novell-sso realm_name) cookie {persistent {enable |
disable} | verify-ip {enable | disable}}
SGOS#(config novell-sso realm_name) virtual-url url

Modifying the sso.ini File for Novell SSO Realms
The Novell SSO realm uses the sso.ini file for configuration parameters required by the
BCAAA service to manage communication with the Novell eDirectory server. Three
sections in the sso.ini file are related to the Novell SSO realm: NovellSetup,
NovellTrustedRoot Certificates, and SSOServiceUsers. You only need to modify settings in
the NovellTrustedRoot Certificates section if the LDAP realm used by the Novell SSO
realm requires that the identity of the server be verified.
The sso.ini file is located in the BCAAA installation directory.
Note:

The changes to the sso.ini file have no effect until the BCAAA service is
restarted.
To modify Novell SSO realms parameters:
1.

Open the file in a text editor.

2.

In the Novell Setup section, modify the parameters as needed (the default values are
as follows):


MonitorRetryTime=30

171

Volume 4: Securing the Blue Coat SG Appliance



SearchRetryTime=30



TrustedRootCertificateEncoding=der



PublicCertificateEncoding=der



PrivateKeyFile=



PrivateKeyEncoding=der

3.

If the LDAP realm used by the Novell SSO realm requires that the identity of the
server be verified, add the paths to the Trusted root certificate files in the
NovellTrustedRootCertificates section.

4.

In the section SSOServiceUsers, list the names of users who can log in with eDirectory
credentials 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.

5.

Save the sso.ini file.

Creating the CPL
You can create CPL policies now that you have completed Novell SSO realm
configuration. Be aware that the examples below are just part of a comprehensive
authentication policy. By themselves, they are not adequate for your purposes.
Note:

The examples below assume the default policy condition is allow.

Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for details about
CPL and how transactions trigger the evaluation of policy file layers.


Every Novell SSO-authenticated user is allowed access the SG appliance.

authenticate(NSSORealm)



Group membership is the determining factor in granting access to the SG appliance.

authenticate(NSSORealm)

group=”cn=proxyusers, ou=groups, o=myco” ALLOW
deny

Using Single Sign-On Realms and Proxy Chains
Some Application Delivery Network (ADN) configurations mask the source IP address of
the request. For example, if the path for a request is:
client workstation > branch proxy > data center proxy > gateway proxy

policy running on the gateway might see the IP address of the data center proxy rather
than the IP address of the client workstation.
Note:

The source IP address is not masked if you use the reflect client ip attribute.

In this ADN configuration, policy needs to be configured so that Windows SSO,
Novell SSO, and policy substitution realms can authenticate users correctly.

172

Chapter 14: Novell Single Sign-on Authentication and Authorization

Use the user.login.address and authenticate.credentials.address policy
gestures to override the IP address of the credentials used for authentication and match
the IP address of the authenticated user.
Note: The user.login.address condition only works correctly if you use the
authenticate.credentials.address property to set the address.

You can also use the x-cs-user-login-address substitution to log this event.
Examples
In the following example, the address to use for authenticating with myrealm is set to the
address received from the HTTP Client-IP header.

authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))

In the following example, the user is authenticated if logged in from the 1.2.3.0/24 subnet.

user.login.address=1.2.3.0/24 allow

Notes


The Novell SSO realm works reliably only in environments where one IP address
maps to one user. NAT environments are not supported.



Novell SSO realms are not supported in IPX environments.



Event monitoring of eDirectory is only compatible with eDirectory 8.7+.



Upgrade to Novell client 4.91 SP1 or later if you experience issues with the Network
Address attribute not being updated during login.



Novell SSO realms do not use user credentials so they cannot spoof authentication
information to an upstream server.



If an upstream proxy is doing Novell SSO authentication, all downstream proxies must
send the client IP address.



There can be response time issues between the BCAAA service and the eDirectory
servers during searches; configure the timeout for LDAP searches to allow the
eDirectory server adequate time to reply.

173

Volume 4: Securing the Blue Coat SG Appliance

174

Chapter 15: Sequence Realm Authentication

Once a realm is configured, you can associate it with other realms to allow Blue Coat to
search for the proper authentication credentials for a specific user. That is, if the
credentials are not acceptable to the first realm, they are sent to the second, and so on
until a match is found or all the realms are exhausted. This is called sequencing.
For example, if a company has one set of end-users authenticating against an LDAP
server and another using NTLM, a sequence realm can specify to attempt NTLM
authentication first; if that fails due to a user-correctable error (such as credentials
mismatch or a user not in database) then LDAP authentication can be specified to try
next. You can also use sequences to fall through to a policy substitution realm if the
user did not successfully authenticate against one of the earlier realms in the sequence.
Note: Errors such as server down do not fall through to the next realm in the
sequence. Those errors result in an exception returned to the user. Only errors that
are end-user correctable result in the next realm in the sequence being attempted.

This section discusses the following topics:


“Adding Realms to a Sequence Realm”



“Creating a Sequence Realm” on page 176

Adding Realms to a Sequence Realm
Keep in mind the following rules for using realm sequences:


Ensure the realms to be added to the sequence are customized to your needs.
Check each realm to be sure that the current values are correct. For IWA, verify that
the Allow Basic Credentials checkbox is set correctly.



All realms in the realm sequence must exist and cannot be deleted or renamed
while the realm sequence references them.



Only one IWA realm is allowed in a realm sequence.



If an IWA realm is in a realm sequence, it must be either the first or last realm in the
list.



If an IWA realm is in a realm sequence and the IWA realm does not support Basic
credentials, the realm must be the first realm in the sequence and try IWA
authentication once must be enabled.



Multiple Basic realms are allowed.



Multiple Windows SSO realms are allowed.



Connection-based realms, such as Certificate, are not allowed in the realm
sequence.



A realm can only exist once in a particular realm sequence.



A realm sequence cannot have another realm sequence as a member.

175

Chapter 15: Sequence Realm Authentication

Tips


Explicit Proxy involving a sequence realm configured with an NTLM/IWA realm and
a substitution realm.
Internet Explorer (IE) automatically sends Windows credentials in the ProxyAuthorization: header when the SG appliance issues a challenge for NTLM/IWA. The
prompt for username/password appears only if NTLM authentication fails. However,
in the case of a sequence realm configured with an NTLM/IWA realm and a
substitution realm, the client is authenticated as a guest in the policy substitution
realm, and the prompt allowing the user to correct the NTLM credentials never
appears.



Transparent Proxy setup involving a sequence realm configured with an NTLM/IWA
realm and a substitution realm.
The only way the SG appliance can differentiate between a domain and non-domain
user is though the NTLM/IWA credentials provided during the authentication
challenge.
IE does not offer Windows credentials in the Proxy-Authorization: header when the
Proxy issues a challenge for NTLM/IWA unless the browser is configured to do so. In
this case, the behavior is the same as for explicit proxy.
If IE is not configured to offer Windows credentials, the browser issues a prompt for
username/password, allowing non-domain users to be authenticated as guests in the
policy substitution realm by entering worthless credentials.

179

Volume 4: Securing the Blue Coat SG Appliance

180

Chapter 16: Windows Single Sign-on Authentication

The Windows Single Sign-on (SSO) realm is an authentication mechanism available on
Windows networks.
This section discusses the following topics:


“How Windows SSO Realms Work” on page 181



“Creating a Windows SSO Realm” on page 183



“Windows SSO Agents” on page 184



“Configuring Authorization” on page 185



“Defining Windows SSO Realm General Properties” on page 186



“Creating the CPL” on page 190

How Windows SSO Realms Work
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 machine. 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. For more
information, see “How Windows SSO Authorization Works” on page 183.
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.

To authenticate a user, the Windows SSO realm uses two methods, either separately or
together:


Domain Controller Querying: The domain controller is queried to identify which
users are connecting to, or authenticating with, the domain controller. This can be
used to infer the identity of the user at a particular workstation.



Client Querying: The client workstation is queried to determine who the client
workstation thinks is logged in.



When Domain Controller Querying and Client Querying are both used, the
Domain Controller Query result is used if it exists and is still within the valid timeto-live as configured in the sso.ini file. If the Domain Controller Query result is
older than the configured time-to-live, the client workstation is queried.
Note: Before Domain Controller Querying or Client Querying can be used, the
sso.ini file, located in the same directory as the BCAAA service, must be
modified. For information on modifying this file, see “Modifying the sso.ini File for
Windows SSO Realms” on page 188.

181

Volume 4: Securing the Blue Coat SG Appliance

For the most complete solution, an IWA realm could be configured at the same time as the
Windows SSO realm and both realms added to a realm sequence. Then, if the Windows
SSO realm failed to authenticate the user, the IWA realm could be used. For information
on using a sequence realm, see Chapter 15: "Sequence Realm Authentication" on
page 175.

How Windows SSO Works with BCAAA
The server side of the authentication exchange is handled by the Blue Coat Authentication
and Authorization Agent (BCAAA). Windows SSO uses a single BCAAA process for all
realms and proxies that use SSO.
BCAAA must be installed on a domain controller or member server. By default, the
BCAAA service authenticates users in all domains trusted by the computer on which it is
running. When using Domain Controller Querying, the BCAAA service can be configured
to only query certain domain controllers in those trusted domains.
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.
When the Windows SSO realm is configured to do Client Querying, the user that BCAAA
runs under must be an authenticated user of the domain. For failover purposes, a second
BCAAA can be installed and configured to act as an alternate BCAAA in the Windows
SSO realm. The alternate BCAAA service is used in the event of a failure with the primary
BCAAA service configured in the realm.

BCAAA 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 will contact its synchronization server and update its 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. To change the
synchronization settings, see “To configure the sso.ini file for synchronization:” on page
189.

182

Volume 4: Securing the Blue Coat SG Appliance

Note:

You must have defined at least one Windows SSO realm (using the Windows
SSO Realms tab) before attempting to set Windows SSO realm properties. If the
message Realms must be added in the Windows SSO Realms tab before editing this tab
is displayed in red at the bottom of this page, you do not currently have any Windows
SSO realms defined.
3.

(Optional) From the Authorization realm name drop-down list, select the realm you
want to use to authorize users.

4.

To construct usernames, keep in mind that the authorization username attributes is a
string. that contains policy substitutions. When authorization is required for the
transaction, the character string is processed by the policy substitution mechanism,
using the current transaction as input. The resulting string becomes the user's
authorization name for the current transaction.

5.

The LDAP FQDN is selected as the Authorization user name, by default. You might
want to change this if the user's authorization information resides in a different root
DN. To choose a different authorization name, de-select the Use FQDN checkbox and
enter a different name, for example:
cn=$(user.name),ou=partition,o=company

6.

Click Apply to commit the changes to the SG appliance.

Table 16-1. Common Substitutions Used in the Authorization username Field
ELFF Substitution

CPL Equivalent

Description

x-cs-auth-domain

$(user.domain)

The Windows domain of the authenticated
user.

cs-username

$(user.name)

The relative username of the authenticated
user.

Related CLI Syntax to Configure Authorization Settings
SGOS#(config windows-sso realm_name) authorization realm-name
authorization-realm-name
SGOS#(config windows-sso realm_name) authorization username
authorization-username

Defining Windows SSO Realm General Properties
The Windows SSO General tab allows you to specify the display name, the refresh times,
an inactivity timeout value, cookies, and a virtual URL.

186

Volume 4: Securing the Blue Coat SG Appliance

5.

Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.

6.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

7.

Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.

8.

Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.

9.

You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.

10. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure General Settings I
SGOS#(config windows-sso realm_name) inactivity-timeout seconds
SGOS#(config windows-sso realm_name) refresh-time surrogate-refresh
seconds
SGOS#(config windows-sso realm_name) refresh-time authorizationrefresh seconds
SGOS#(config windows-sso realm_name) cookie {persistent {enable |
disable} | verify-ip {enable | disable}}
SGOS#(config windows-sso realm_name) virtual-url url

Modifying the sso.ini File for Windows SSO Realms
To enable the method of authentication querying you choose, you must modify the
sso.ini file by adding domain controllers you want to query and user accounts you
want to ignore.
The sso.ini file is located in the BCAAA installation directory.
If you are only using one method of querying, you only need configure the specific
settings for that method. If you plan to use both methods to query, you must configure all
the settings.
Note:

The changes to the sso.ini file have no effect until the BCAAA service is
restarted.
To configure the sso.ini file for Domain Controller Querying
1.

Open the file in a text editor.

2.

In the section DCQSetup, uncomment the line: DCQEnabled=1.

3.

In the section DCQDomainControllers, list the domain controllers you want to query
or the IP address ranges of interest.

188

Chapter 16: Windows Single Sign-on Authentication

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 SG appliance
installation might be queried. The sso.ini file can be used to list the domain
controllers of interest or IP address ranges of interest.
4.

In the section SSOServiceUsers, 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.

5.

Save the sso.ini file.

To configure the sso.ini file for client querying:
Note: Before you use the Windows SSO realm, you must change the BCAAA service to
run as a domain user, and, if using XP clients, update the domain policy to allow the client
query to pass through the firewall.

For information on installing and configuring the BCAAA service, see Appendix B:
"Using the Authentication/Authorization Agent" on page 215.
1.

Open the file in a text editor.

2.

Review the TTL times in the section ClientQuerySetup to be sure they are appropriate
for your network environment.

3.

Update the section SSOServiceUsers to ignore domain users used for services.

4.

Save the sso.ini file.

To configure the sso.ini file for synchronization:
1.

Open the file in a text editor.

2.

Update the section SSOSyncSetup (the defaults are listed below). Note that
explanations of each setting are provided in the sso.ini file.


ServerPriority=100



EnableSyncServer=1



SyncPortNumber=16102



UseSSL=0



VerifyCertificate=0



QueryDelta=10



RetrySyncTime=60

3.

Update the section SSOSyncServer with the IP address or hostname of the BCAAA
service to use a synchronization server.

4.

In the section SSOSyncClients, list the IP addresses or hostnames of the BCAAA
services that will use this BCAAA service as their synchronization service.

5.

Save the sso.ini file.

189

Volume 4: Securing the Blue Coat SG Appliance

Creating the CPL
You can create CPL policies now that you have completed Windows SSO realm
configuration. Be aware that the examples below are just part of a comprehensive
authentication policy. By themselves, they are not adequate for your purposes.
The examples below assume the default policy condition is allow. On new systems, the
default policy condition is deny.
Note:

Refer to Volume 10: Blue Coat SG Appliance Content Policy Language Guide for
details about CPL and how transactions trigger the evaluation of policy file layers.


Every Windows SSO-authenticated user is allowed access the SG appliance.

authenticate(WSSORealm)



Group membership is the determining factor in granting access to the SG appliance.

authenticate(WSSORealm)

group=”cn=proxyusers, ou=groups, o=myco” ALLOW
deny

Using Single Sign-On Realms and Proxy Chains
Some Application Delivery Network (ADN) configurations mask the source IP address of
the request. For example, if the path for a request is:
client workstation > branch proxy > data center proxy > gateway proxy

policy running on the gateway might see the IP address of the data center proxy rather
than the IP address of the client workstation.
Note:

The source IP address is not masked if you use the reflect client ip attribute.

In this ADN configuration, policy needs to be configured so that Windows SSO,
Novell SSO, and policy substitution realms can authenticate users correctly.
Use the user.login.address and authenticate.credentials.address policy
gestures to override the IP address of the credentials used for authentication and match
the IP address of the authenticated user.
Note: The user.login.address condition only works correctly if you use the
authenticate.credentials.address property to set the address.

You can also use the x-cs-user-login-address substitution to log this event.
Examples
In the following example, the address to use for authenticating with myrealm is set to the
address received from the HTTP Client-IP header.

authenticate(myrealm)\
authenticate.credentials.address($(request.header.Client-IP))

190

Chapter 16: Windows Single Sign-on Authentication

In the following example, the user is authenticated if logged in from the 1.2.3.0/24 subnet.

user.login.address=1.2.3.0/24 allow

Notes


The Windows SSO realm works reliably only in environments where one IP address
maps to one user.



This realm never uses a password.



When doing domain controller querying, the Windows SSO realm can lose the logon
if the NetBIOS computer name cannot by determined through a DNS query or a
NetBIOS query. The DNS query can fail if the NetBIOS name is different than the DNS
host name or if the computer is in a different DNS domain than the BCAAA computer
and the BCAAA computer is not set up to impute different DNS domains.
The NetBIOS query can fail because the NetBIOS broadcast does not reach the target
computer. This can happen if the computer is behind a firewall that is not forwarding
NetBIOS requests or if the computer is on a subnet that is not considered to be local to
the BCAAA server.
To prevent this issue, the BCAAA machine must be configured to be able to query the
NetBIOS name of any computer of interest and get the correct IP address.
One workaround is to use a WINS server. This works like a DNS server but handles
NetBIOS lookups.

191

Volume 4: Securing the Blue Coat SG Appliance

192

Chapter 17: Using XML Realms

If you use an authentication or authorization protocol that is not natively supported by
Blue Coat, you can use the XML realm to integrate SGOS with the authentication/
authorization protocol.
This section includes the following topics:


“About XML Realms”



“Before Creating an XML Realm” on page 194



“Creating an XML Realm” on page 194



“Configuring XML Servers” on page 195



“Configuring XML Options” on page 196



“Configuring XML Realm Authorization” on page 196



“Configuring XML General Realm Properties” on page 198



“Creating the CPL” on page 200



“Viewing Statistics” on page 200

About XML Realms
An XML realm uses XML messages to request authentication and authorization
information from an HTTP XML service (the XML responder that runs on an external
server). The XML realm (the XML requestor) supports both HTTP GET and HTTP POST
methods to request an XML response. The XML messages are based on SOAP 1.2.
The XML responder service accepts XML requests from the SG, communicates with an
authentication or authorization server, and responds with the result. When the realm is
used to authenticate users, it challenges for Basic credentials. The username and
password are then sent to the XML responder to authenticate and authorize the user.
The XML realm can place the username and password in the HTTP headers of the
request or in the body of the XML POST request. If the credentials are placed in the
HTTP headers, the Web server must do the authentication and the XML service just
handles authorization. If credentials are placed in the XML request body, the XML
service handles both authentication and authorization.
XML messages must conform to the Blue Coat XML realm schema. This is an XML
schema based on SOAP 1.2. The schema can be found at http://www.bluecoat.com/
xmlns/xml-realm/1.0.
An authenticate request sends the credentials to the XML responder and optionally
sends the groups and attributes referenced in policy. The XML responder can then
authenticate the credentials. The response indicates if the user was successfully
authenticated and also includes the user’s groups and attributes if the XML responder
is doing authorization.
An authorize request sends the authenticated username to the XML responder and
optionally sends the groups and attributes referenced in policy. The response includes
the user’s groups and attributes.

193

Chapter 17: Using XML Realms

6.

Enter the number of seconds in the Surrogate refresh time field. The Surrogate Refresh
Time allows you to set a realm default for how often a user’s surrogate credentials are
refreshed. Surrogate credentials are credentials accepted in place of a user’s actual
credentials. The default setting is 900 seconds (15 minutes). You can configure this in
policy for better control over the resources as policy overrides any settings made here.
Before the refresh time expires, if a surrogate (IP address or cookie) is available and it
matches the expected surrogate, the SG appliance authenticates the transaction. After
the refresh time expires, the SG appliance will verify the user’s credentials.
Depending upon the authentication mode and the user-agent, this may result in
challenging the end user for credentials.
The main goal of this feature is to verify that the user-agent still has the appropriate
credentials.

7.

Enter the number of seconds in the Authorization refresh time field. The Authorization
Refresh Time allows you to manage how often the authorization data is verified with
the authentication realm. It has a default setting of 900 seconds (15 minutes). You can
configure this in policy for better control over the resources as policy overrides any
settings made here.

8.

Type the number of seconds in the Inactivity timeout field to specify the amount of
time a session can be inactive before being logged out.

9.

If you use Basic credentials and want to cache failed authentication attempts (to
reduce the load on the authentication service), enter the number of seconds in the
Rejected Credentials time field. This setting, enabled by default and set to one second,
allows failed authentication attempts to be automatically rejected for up to 10
seconds. Any Basic credentials that match a failed result before its cache time expires
are rejected without consulting the back-end authentication service. The original
failed authentication result is returned for the new request.
All failed authentication attempts can be cached: Bad password, expired account,
disabled account, old password, server down.
To disable caching for failed authentication attempts, set the Rejected Credentials time
field to 0.

10. Select the Use persistent cookies check box to use persistent browser cookies instead
of session browser cookies.
11. Select the Verify the IP address in the cookie check box if you would like the cookies
surrogates to only be accepted for the IP address that the cookie was authenticated.
Disabling this will allow cookies to be accepted from other IP addresses.
12. You can specify a virtual URL. For more information on the virtual URL, see
“Understanding Origin-Style Redirection” on page 34.
13. Click Apply to commit the changes to the SG appliance.
Related CLI Syntax to Configure an XML Realm


To enter configuration mode for the service:
SGOS#(config) security create xml realm_name
SGOS#(config) security edit xml realm_name

The following subcommands are available:
SGOS#(config realm_name)?

199

Volume 4: Securing the Blue Coat SG Appliance

SGOS#(config realm_name) alternate-responder {host host | path
{authenticate authenticate-path | authorize authorize-path}| port
port}
SGOS#(config realm_name) authorization {default-group-name group_name
| realm {none | realm-name realm_name | self} | username {use-fullusername | username}}
SGOS#(config realm_name) cache-duration seconds
SGOS#(config realm_name) connections number
SGOS#(config realm_name) display-name display_name
SGOS#(config realm_name) exit
SGOS#(config realm_name) no {alternate-responder | default-group-name}
SGOS#(config realm_name) one-time-passwords {enable | disable}
SGOS#(config realm_name) primary-responder {host host | path
{authenticate authenticate-path | authorize authorize-path}| port
port}
SGOS#(config realm_name) rename new_realm_name
SGOS#(config realm_name) timeout seconds
SGOS#(config realm_name) retry number
SGOS#(config realm_name) view
SGOS#(config
SGOS#(config
seconds
SGOS#(config
SGOS#(config
SGOS#(config

realm_name) refresh-time credential-refresh seconds
realm_name) refresh-time rejected-credentials-refresh
realm_name) refresh-time surrogate-refresh seconds
realm_name) refresh-time authorization-refresh seconds
realm_name) inactivity-timeout seconds

SGOS#(config realm_name) cookie {persistent {enable | disable} |
verify-ip {enable | disable}}
SGOS#(config realm_name) virtual-url virtual_url

Creating the CPL
This CPL example gives access to users who are authenticated in the XML realm called
eng_users and who are in the group waterloo. You also can create policy for XML realms
through VPM.
Note:

For information on using policy, refer to Volume 6: VPM and Advanced Policy or
Volume 10: Blue Coat SG Appliance Content Policy Language Guide.

authenticate(eng_users)

realm=eng_users group=waterloo allow

Viewing Statistics
To view statistics for XML realms, click Statistics > Advanced. Select one of the advanced
links.

200

Appendix A: Glossary

A
access control list

Allows or denies specific IP addresses access to a server.

access log

A list of all the requests sent to an appliance. You can read an access log using any of
the popular log-reporting programs. When a client uses HTTP streaming, the
streaming entry goes to the same access log.

account

A named entity that has purchased the appliance or the Entitlements from Blue Coat.

activation code

A string of approximately 10 characters that is generated and mailed to customers
when they purchase the appliance.

active content stripping

Provides a way to identify potentially dangerous mobile or active content and
scripts, and strip them out of a response.

active content types

Used in the Visual Policy Manager. Referring to Web Access policies, you can create
and name lists of active content types to be stripped from Web pages. You have the
additional option of specifying a customized message to be displayed to the user

administration access policy

A policy layer that determines who can access the SG appliance to perform
administrative tasks.

administration
authentication policy

A policy layer that determines how administrators accessing the SG appliance must
authenticate.

Application Delivery
Network (ADN)

A WAN that has been optimized for acceleration and compression by Blue Coat. This
network can also be secured through the use of appliance certificates. An ADN
network is composed of an ADN manager and backup ADN manager, ADN nodes,
and a network configuration that matches the environment.

ADN backup manager

Takes over for the ADN manager in the event it becomes unavailable. See ADN
manager.

ADN manager

Responsible for publishing the routing table to SG Clients (and to other SG
appliances).

ADN optimize attribute

Controls whether to optimize bandwidth usage when connecting upstream using an
ADN tunnel.

asx rewrite

Allows you to rewrite URLs and then direct a client's subsequent request to the new
URL. One of the main applications of ASX file rewrites is to provide explicit proxylike support for Windows Media Player 6.4, which cannot set explicit proxy mode for
protocols other than HTTP.

audit

A log that provides a record of who accessed what and how.

201

Volume 4: Securing the Blue Coat SG Appliance

authenticate-401 attribute

All transparent and explicit requests received on the port always use transparent
authentication (cookie or IP, depending on the configuration). This is especially
useful to force transparent proxy authentication in some proxy-chaining scenarios

authenticated content

Cached content that requires authentication at the origin content server (OCS).
Supported authentication types for cached data include basic authentication and
IWA (or NTLM).

authentication

Allows you to verify the identity of a user. In its simplest form, this is done through
usernames and passwords. Much more stringent authentication can be employed
using digital certificates that have been issued and verified by a Certificate Authority.
See also basic authentication, proxy authentication, and SSL authentication.

authentication realm

Authenticates and authorizes users to access SG services using either explicit proxy
or transparent proxy mode. These realms integrate third-party vendors, such as
LDAP, Windows, and Novell, with the Blue Coat operating system.

authorization

The permissions given to an authenticated user.

B
bandwidth class

A defined unit of bandwidth allocation.

bandwidth class hierarchy

Bandwidth classes can be grouped together in a class hierarchy, which is a tree
structure that specifies the relationship among different classes. You create a
hierarchy by creating at least one parent class and assigning other classes to be its
children.

bandwidth management

Classify, control, and, if needed, limit the amount of bandwidth used by network
traffic flowing in or out of an SG appliance.

basic authentication

The standard authentication for communicating with the target as identified in the
URL.

BCAAA

Blue Coat Authentication and Authorization Agent. Allows SGOS 5.x to manage
authentication and authorization for IWA, CA eTrust SiteMinder realms, Oracle
COREid, Novell, and Windows realms. The agent is installed and configured
separately from SGOS 5.x and is available from the Blue Coat Web site.

BCLP

Blue Coat Licensing Portal.

byte-range support

The ability of the SG appliance to respond to byte-range requests (requests with a
Range: HTTP header).

C
cache

An "object store," either hardware or software, that stores information (objects) for
later retrieval. The first time the object is requested, it is stored, making subsequent
requests for the same information much faster.
A cache helps reduce the response time and network bandwidth consumption on
future, equivalent requests. The SG appliance serves as a cache by storing content
from many users to minimize response time and prevent extraneous network traffic.

cache control

Allows you to configure which content the SG appliance stores.

202

Appendix A: Glossary

cache efficiency

A tab found on the Statistics pages of the Management Console that shows the
percent of objects served from cache, the percent loaded from the network, and the
percent that were non-cacheable.

cache hit

Occurs when the SG appliance receives a request for an object and can serve the
request from the cache without a trip to the origin server.

cache miss

Occurs when the appliance receives a request for an object that is not in the cache.
The appliance must then fetch the requested object from the origin server. .

cache object

Cache contents includes all objects currently stored by the SG appliance. Cache
objects are not cleared when the SG appliance is powered off.

Certificate Authority (CA)

A trusted, third-party organization or company that issues digital certificates used to
create digital signatures and public key/private key pairs. The role of the CA is to
guarantee that the individuals or company representatives who are granted a unique
certificate are who they claim to be.

child class (bandwidth gain)

The child of a parent class is dependent upon that parent class for available
bandwidth (they share the bandwidth in proportion to their minimum/maximum
bandwidth values and priority levels). A child class with siblings (classes with the
same parent class) shares bandwidth with those siblings in the same manner.

client consent certificates

A certificate that indicates acceptance or denial of consent to decrypt an end user's
HTTPS request.

client-side transparency

A way of replacing the appliance IP address with the Web server IP address for all
port 80 traffic destined to go to the client. This effectively conceals the SG appliance
address from the client and conceals the identity of the client from the Web server.

concentrator

An SG appliance, usually located in a data center, that provides access to data center
resources, such as file servers.

content filtering

A way of controlling which content is delivered to certain users. SG appliances can
filter content based on content categories (such as gambling, games, and so on), type
(such as http, ftp, streaming, and mime type), identity (user, group, network), or
network conditions. You can filter content using vendor-based filtering or by
allowing or denying access to URLs.

D
default boot system

The system that was successfully started last time. If a system fails to boot, the next
most recent system that booted successfully becomes the default boot system.

default proxy listener

See proxy service (d efault).

denial of service (DoS)

A method that hackers use to prevent or deny legitimate users access to a computer,
such as a Web server. DoS attacks typically send many request packets to a targeted
Internet server, flooding the server's resources and making the system unusable. Any
system connected to the Internet and equipped with TCP-based network services is
vulnerable to a DoS attack.
The SG appliance resists DoS attacks launched by many common DoS tools. With a
hardened TCP/IP stack, SG appliance resists common network attacks, including
traffic flooding.

203

Volume 4: Securing the Blue Coat SG Appliance

destination objects

Used in Visual Policy Manager. These are the objects that define the target location of
an entry type.

detect protocol attribute

Detects the protocol being used. Protocols that can be detected include: HTTP, P2P
(eDonkey, BitTorrent, FastTrack, Gnutella), SSL, and Endpoint Mapper.

diagnostic reporting

Found in the Statistics pane, the Diagnostics tab allows you to control whether Daily
Heartbeats and/or Blue Coat Monitoring are enabled or disabled.

directives

Commands used in installable lists to configure forwarding and SOCKS gateway.

DNS access

A policy layer that determines how the SG appliance processes DNS requests.

domain name system (DNS)

An Internet service that translates domain names into IP addresses. See also private
DNS or public DNS.

dynamic bypass

Provides a maintenance-free method for improving performance of the SG appliance
by automatically compiling a list of requested URLs that return various kinds of
errors.

dynamic real-time rating
(DRTR)

Used in conjunction with the Blue Coat Web Filter (BCWF), DRTR (also known as
dynamic categorization) provides real-time analysis and content categorization of
requested Web pages to solve the problem of new and previously unknown
uncategorized URLs—those not in the database. When a user requests a URL that has
not already been categorized by the BCWF database (for example, a brand new Web
site), the SG appliance dynamic categorization service analyzes elements of the
requested content and assigns a category or categories. The dynamic service is
consulted only when the installed BCWF database does not contain category
information for an object.

E
early intercept attribute

Controls whether the proxy responds to client TCP connection requests before
connecting to the upstream server. When early intercept is disabled, the proxy delays
responding to the client until after it has attempted to contact the server.

ELFF-compatible format

A log type defined by the W3C that is general enough to be used with any protocol.

emulated certificates

Certificates that are presented to the user by SG appliance when intercepting HTTPS
requests. Blue Coat emulates the certificate from the server and signs it, copying the
subjectName and expiration. The original certificate is used between the SG
appliance and the server.

encrypted log

A log is encrypted using an external certificate associated with a private key.
Encrypted logs can only be decrypted by someone with access to the private key. The
private key is not accessible to the SG appliance.

EULA

End user license agreement.

event logging

Allows you to specify the types of system events logged, the size of the event log, and
to configure Syslog monitoring. The appliance can also notify you by email if an
event is logged. See also access logging.

204

Appendix A: Glossary

explicit proxy

A configuration in which the browser is explicitly configured to communicate with
the proxy server for access to content.
This is the default for the SG appliance, and requires configuration for both browser
and the interface card.

extended log file format
(ELFF)

A variant of the common log file format, which has two additional fields at the end of
the line—the referer and the user agent fields.

F
fail open/closed

Failing open or closed applies to forwarding hosts and groups and SOCKS gateways.
Fail open or closed applies when health checks are showing sick for each forwarding
or SOCKS gateway target in the applicable fail-over sequence. If no systems are
healthy, the SG appliance fails open or closed, depending on the configuration. If
closed, the connection attempt simply fails.
If open, an attempt is made to connect without using any forwarding target (or
SOCKS gateway). Fail open is usually a security risk; fail closed is the default if no
setting is specified.

filtering

See content filtering.

forward proxy

A proxy server deployed close to the clients and used to access many servers. A
forward proxy can be explicit or transparent.

FTP

See Native FTP; Web FTP.

G
gateway

A device that serves as entrance and exit into a communications network.

H
hardware serial number

A string that uniquely identifies the appliance; it is assigned to each unit in
manufacturing.

health check tests

The method of determining network connectivity, target responsiveness, and basic
functionality. The following tests are supported:
• ICMP
• TCP
• SSL
• HTTP
• HTTPS
• Group
• Composite and reference to a composite result
• ICAP
• Websense
• DRTR rating service

205

Volume 4: Securing the Blue Coat SG Appliance

health check type

The kind of device or service the specific health check tests. The following types are
supported:
• Forwarding host and forwarding group
• SOCKS gateway and SOCKS gateway group
• CAP service and ICAP service group
• Websense off-box service and Websense off-box service group
• DRTR rating service
• User-defined host and a user-defined composite

heartbeat

Messages sent once every 24 hours that contain the statistical and configuration data
for the SG appliance, indicating its health. Heartbeats are commonly sent to system
administrators and to Blue Coat. Heartbeats contain no private information, only
aggregate statistics useful for pre-emptively diagnosing support issues.
The SG appliance sends emergency heartbeats whenever it is rebooted. Emergency
heartbeats contain core dump and restart flags in addition to daily heartbeat
information.

host affinity

The attempt to direct multiple connections by a single user to the same group
member. Host affinity is closely tied to load balancing behavior; both should be
configured if load balancing is important.

host affinity timeout

The host affinity timeout determines how long a user remains idle before the
connection is closed. The timeout value checks the user's IP address, SSL ID, or
cookie in the host affinity table.

I
inbound traffic (bandwidth
gain)

Network packets flowing into the SG appliance. Inbound traffic mainly consists of
the following:
• Server inbound: Packets originating at the origin content server (OCS) and sent to
the SG appliance to load a Web object.
• Client inbound: Packets originating at the client and sent to the SG appliance for
Web requests.

installable lists

Installable lists, comprised of directives, can be placed onto the SG appliance in one
of the following ways:
• Creating the list using the SG text editor
• Placing the list at an accessible URL
• Downloading the directives file from the local system

integrated host timeout

An integrated host is an origin content server (OCS) that has been added to the health
check list. The host, added through the integrate_new_hosts property, ages out
of the integrated host table after being idle for the specified time. The default is 60
minutes.

intervals

Time period from the completion of one health check to the start of the next health
check.

IP reflection

Determines how the client IP address is presented to the origin server for explicitly
proxied requests. All proxy services contain a reflect-ip attribute, which enables or
disables sending of client's IP address instead of the SG's IP address.

206

Appendix A: Glossary

issuer keyring

The keyring used by the SG appliance to sign emulated certificates. The keyring is
configured on the appliance and managed through policy.

L
licensable component (LC)

(Software) A subcomponent of a license; it is an option that enables or disables a
specific feature.

license

Provides both the right and the ability to use certain software functions within an AV
(or SG) appliance. The license key defines and controls the license, which is owned
by an account.

listener

The service that is listening on a specific port. A listener can be identified by any
destination IP/subnet and port range. Multiple listeners can be added to each
service.

live content

Also called live broadcast. Used in streaming, it indicates that the content is being
delivered fresh.

LKF

License key file.

load balancing

A way to share traffic requests among multiple upstream systems or multiple IP
addresses on a single host.

local bypass list

A list you create and maintain on your network. You can use a local bypass list alone
or in conjunction with a central bypass list. See bypass list.

local policy file

Written by enterprises (as opposed to the central policy file written by Blue Coat);
used to create company- and department-specific advanced policies written in the
Blue Coat Policy Language (CPL).

log facility

A separate log that contains a single logical file and supports a single log format. It
also contains the file’s configuration and upload schedule information as well as
other configurable information such as how often to rotate (switch to a new log) the
logs at the destination, any passwords needed, and the point at which the facility can
be uploaded.

log format

The type of log that is used: NCSA/Common, SQUID, ELFF, SurfControl, or
Websense.
The proprietary log types each have a corresponding pre-defined log format that has
been set up to produce exactly that type of log (these logs cannot be edited). In
addition, a number of other ELFF type log formats are also pre-defined (im, main,
p2p, ssl, streaming). These can be edited, but they start out with a useful set of log
fields for logging particular protocols understood by the SG appliance. It is also
possible to create new log formats of type ELFF or Custom which can contain any
desired combination of log fields.

log tail

The access log tail shows the log entries as they get logged. With high traffic on the
SG appliance, not all access log entries are necessarily displayed. However, you can
view all access log information after uploading the log.

M
MACH5

SGOS 5 MACH5 Edition.

207

Volume 4: Securing the Blue Coat SG Appliance

Management Console

A graphical Web interface that lets you to manage, configure, monitor, and upgrade
the SG appliance from any location. The Management Console consists of a set of
Web pages and Java applets stored on the SG appliance. The appliance acts as a Web
server on the management port to serve these pages and applets.

management information
base (MIB)

Defines the statistics that management systems can collect. A managed device
(gateway) has one or more MIBs as well as one or more SNMP agents, which
implements the information and management functionality defined by a specific
MIB.

maximum object size

The maximum object size stored in the SG appliance. All objects retrieved that are
greater than the maximum size are delivered to the client but are not stored in the SG
appliance.

MIME/FILE type filtering

Allows organizations to implement Internet policies for both uploaded and
downloaded content by MIME or FILE type.

multi-bit rate

The capability of a single stream to deliver multiple bit rates to clients requesting
content from appliances from within varying levels of network conditions (such as
different connecting bandwidths and traffic).

multicast

Used in streaming; the ability for hundreds or thousands of users to play a single
stream.

multicast aliases

Used in streaming; a streaming command that specifies an alias for a multicast URL
to receive an .nsc file. The .nsc files allows the multicast session to obtain the
information in the control channel

multicast station

Used in streaming; a defined location on the proxy where the Windows Media player
can retrieve streams. A multicast station enables multicast transmission of Windows
Media content from the cache. The source of the multicast-delivered content can be a
unicast-live source, a multicast (live) source, and simulated live (video-on-demand
content converted to scheduled live content).

multimedia content services

Used in streaming; multimedia support includes Real Networks, Microsoft Windows
Media, Apple QuickTime, MP3, and Flash.

N
name inputing

Allows an SG appliance to resolve host names based on a partial name specification.
When a host name is submitted to the DNS server, the DNS server resolves the name
to an IP address. If the host name cannot be resolved, Blue Coat adds the first entry in
the name-inputing list to the end of the host name and resubmits it to the DNS server

native FTP

Native FTP involves the client connecting (either explicitly or transparently) using
the FTP protocol; the SG appliance then connects upstream through FTP (if
necessary).

NCSA common log format

Blue Coat products are compatible with this log type, which contains only basic
HTTP access information.

network address translation
(NAT)

The process of translating private network (such as intranet) IP addresses to Internet
IP addresses and vice versa. This methodology makes it possible to match private IP
addresses to Internet IP addresses even when the number of private addresses
outnumbers the pool of available Internet addresses.

208

Appendix A: Glossary

non-cacheable objects

A number of objects are not cached by the Blue Coat appliance because they are
considered non-cacheable. You can add or delete the kinds of objects that the
appliance considers non-cacheable. Some of the non-cacheable request types are:
• Pragma no-cache, requests that specify non-cached objects, such as when you click
refresh in the Web browser.
• Password provided, requests that include a client password.
• Data in request that include additional client data.
• Not a GET request.

.nsc file

Created from the multicast station definition and saved through the browser as a text
file encoded in a Microsoft proprietary format. Without an .nsc file, the multicast
station definition does not work.

NTP

To manage objects in an appliance, an SG appliance must know the current Universal
Time Coordinates (UTC) time. By default, the SG appliance attempts to connect to a
Network Time Protocol (NTP) server to acquire the UTC time. SG appliance includes
a list of NTP servers available on the Internet, and attempts to connect to them in the
order they appear in the NTP server list on the NTP tab.

O
object (used in caching)

An object is the item that is stored in an appliance. These objects can be frequently
accessed content, content that has been placed there by content publishers, or Web
pages, among other things.

object (used in Visual Policy
Manager)

An object (sometimes referred to as a condition) is any collection or combination of
entry types you can create individually (user, group, IP address/subnet, and
attribute). To be included in an object, an item must already be created as an
individual entry.

object pipelining

This patented algorithm opens as many simultaneous TCP connections as the origin
server will allow and retrieves objects in parallel. The objects are then delivered from
the appliance straight to the user's desktop as fast as the browser can request them.

origin content server (OCS)

Also called origin server. This is the original source of the content that is being
requested. An appliance needs the OCS to acquire data the first time, to check that
the content being served is still fresh, and to authenticate users.

outbound traffic (bandwidth
gain)

Network packets flowing out of the SG appliance. Outbound traffic mainly consists
of the following:
• Client outbound: Packets sent to the client in response to a Web request.
• Server outbound: Packets sent to an OCS or upstream proxy to request a service.

P
PAC (Proxy
AutoConfiguration) scripts

Originally created by Netscape, PACs are a way to avoid requiring proxy hosts and
port numbers to be entered for every protocol. You need only enter the URL. A PAC
can be created with the needed information and the local browser can be directed to
the PAC for information about proxy hosts and port numbers.

packet capture (PCAP)

Allows filtering on various attributes of the Ethernet frame to limit the amount of
data collected. You can capture packets of Ethernet frames going into or leaving an
SG appliance.

209

Volume 4: Securing the Blue Coat SG Appliance

parent class (bandwidth
gain)

A class with at least one child. The parent class must share its bandwidth with its
child classes in proportion to the minimum/maximum bandwidth values or priority
levels.

passive mode data
connections (PASV)

Data connections initiated by an FTP client to an FTP server.

pipelining

See object pipelining.

policies

Groups of rules that let you manage Web access specific to the needs of an enterprise.
Policies enhance SG appliance feature areas such as authentication and virus
scanning, and let you control end-user Web access in your existing infrastructure.
See also refresh policies.

policy-based bypass list

Used in policy. Allows a bypass based on the properties of the client, unlike static and
dynamic bypass lists, which allow traffic to bypass the appliance based on
destination IP address. See also bypass lists and dynamic bypass.

policy layer

A collection of rules created using Blue Coat CPL or with the VPM.

pragma: no cache (PNC)

A metatag in the header of a request that requires the appliance to forward a request
to the origin server. This allows clients to always obtain a fresh copy (of the request?).

proxy

Caches content, filters traffic, monitors Internet and intranet resource usage, blocks
specific Internet and intranet resources for individuals or groups, and enhances the
quality of Internet or intranet user experiences.
A proxy can also serve as an intermediary between a Web client and a Web server
and can require authentication to allow identity based policy and logging for the
client.
The rules used to authenticate a client are based on the policies you create on the SG
appliance, which can reference an existing security infrastructure—LDAP, RADIUS,
IWA, and the like.

Proxy Edition

SGOS 5 Proxy Edition.

proxy service

The proxy service defines the ports, as well as other attributes. that are used by the
proxies associated with the service.

proxy service (default)

The default proxy service is a service that intercepts all traffic not otherwise
intercepted by other listeners. It only has one listener whose action can be set to
bypass or intercept. No new listeners can be added to the default proxy service, and
the default listener and service cannot be deleted. Service attributes can be changed.

public key certificate

An electronic document that encapsulates the public key of the certificate sender,
identifies this sender, and aids the certificate receiver to verify the identity of the
certificate sender. A certificate is often considered valid if it has been digitally signed
by a well-known entity, which is called a Certificate Authority (such as VeriSign).

public virtual IP (VIP)

Maps multiple servers to one IP address and then propagates that information to the
public DNS servers. Typically, there is a public VIP known to the public Internet that
routes the packets internally to the private VIP. This enables you to “hide” your
servers from the Internet.

210

Appendix A: Glossary

R
real-time streaming protocol
(RTSP)

A standard method of transferring audio and video and other time-based media over
Internet-technology based networks. The protocol is used to stream clips to any RTPbased client.

reflect client IP attribute

Enables the sending of the client's IP address instead of the SG's IP address to the
upstream server. If you are using an application delivery network (ADN), this setting
is enforced on the concentrator proxy through the Configuration > App. Delivery
Network > Tunneling tab.

registration

An event that binds the appliance to an account, that is, it creates the Serial#, Account
association.

remote authentication dialin user service (RADIUS)

Authenticates user identity via passwords for network access.

reverse proxy

A proxy that acts as a front-end to a small number of pre-defined servers, typically to
improve performance. Many clients can use it to access the small number of
predefined servers.

routing information protocol
(RIP)

Designed to select the fastest route to a destination. RIP support is built into Blue
Coat appliances.

router hops

The number of jumps a packet takes when traversing the Internet.

S
secure shell (SSH)

Also known as Secure Socket Shell. SSH is an interface and protocol that provides
strong authentication and enables you to securely access a remote computer. Three
utilities—login, ssh, and scp—comprise SSH. Security via SSH is accomplished using
a digital certificate and password encryption. Remember that the Blue Coat SG
appliance requires SSH1. An SG appliance supports a combined maximum of 16
Telnet and SSH sessions.

serial console

A third-party device that can be connected to one or more Blue Coat appliances.
Once connected, you can access and configure the appliance through the serial
console, even when you cannot access the appliance directly.

server certificate categories

The hostname in a server certificate can be categorized by BCWF or another content
filtering vendor to fit into categories such as banking, finance, sports.

server portals

Doorways that provide controlled access to a Web server or a collection of Web
servers. You can configure Blue Coat SG appliances to be server portals by mapping a
set of external URLs onto a set of internal URLs.

server-side transparency

The ability for the server to see client IP addresses, which enables accurate clientaccess records to be kept. When server-side transparency is enabled, the appliance
retains client IP addresses for all port 80 traffic to and from the SG appliance. In this
scheme, the client IP address is always revealed to the server.

service attributes

Define the parameters, such as explicit or transparent, cipher suite, and certificate
verification, that the SG appliance uses for a particular service. .

211

Volume 4: Securing the Blue Coat SG Appliance

SG appliance

A Blue Coat security and cache box that can help manage security and content on a
network.

sibling class (bandwidth
gain)

A bandwidth class with the same parent class as another class.

simple network
management protocol
(SNMP)

The standard operations and maintenance protocol for the Internet. It uses MIBs,
created or customized by Blue Coat, to handle (needs completion).

simulated live

Used in streaming. Defines playback of one or more video-on-demand files as a
scheduled live event, which begins at a specified time. The content can be looped
multiple times, or scheduled to start at multiple start times throughout the day.

SmartReporter log type

A proprietary ELFF log type that is compatible with the SmartFilter SmartReporter
tool.

SOCKS

A proxy protocol for TCP/IP-based networking applications that allows users
transparent access across the firewall. If you are using a SOCKS server for the
primary or alternate forwarding gateway, you must specify the appliance’s ID for the
identification protocol used by the SOCKS gateway. The machine ID should be
configured to be the same as the appliance’s name.

SOCKS proxy

A generic way to proxy TCP and UDP protocols. The SG appliance supports both
SOCKSv4/4a and SOCKSv5; however, because of increased username and password
authentication capabilities and compression support, Blue Coat recommends that
you use SOCKS v5.

splash page

Custom message page that displays the first time you start the client browser.

split proxy

Employs co-operative processing at the branch and the core to implement
functionality that is not possible in a standalone proxy. Examples of split proxies
include:
• Mapi Proxy
• SSL Proxy

SQUID-compatible format

A log type that was designed for cache statistics and is compatible with Blue Coat
products.

squid-native log format

The Squid-compatible format contains one line for each request.

SSL authentication

Ensures that communication is with “trusted” sites only. Requires a certificate issued
by a trusted third party (Certificate Authority).

SSL interception

Decrypting SSL connections.

SSL proxy

A proxy that can be used for any SSL traffic (HTTPS or not), in either forward or
reverse proxy mode.

static route

A manually-configured route that specifies the transmission path a packet must
follow, based on the packet’s destination address. A static route specifies a
transmission path to another network.

212

Appendix A: Glossary

statistics

Every Blue Coat appliance keeps statistics of the appliance hardware and the objects
it stores. You can review the general summary, the volume, resources allocated, cache
efficiency, cached contents, and custom URLs generated by the appliance for various
kinds of logs. You can also check the event viewer for every event that occurred since
the appliance booted.

stream

A flow of a single type of data, measured in kilobits per second (Kbps). A stream
could be the sound track to a music video, for example.

SurfControl log type

A proprietary log type that is compatible with the SurfControl reporter tool. The
SurfControl log format includes fully-qualified usernames when an NTLM realm
provides authentication. The simple name is used for all other realm types.

syslog

An event-monitoring scheme that is especially popular in Unix environments. Most
clients using Syslog have multiple devices sending messages to a single Syslog
daemon. This allows viewing a single chronological event log of all of the devices
assigned to the Syslog daemon. The Syslog format is: “Date Time Hostname Event.”

system cache

The software cache on the appliance. When you clear the cache, all objects in the
cache are set to expired. The objects are not immediately removed from memory or
disk, but a subsequent request for any object requested is retrieved from the origin
content server before it is served.

T
time-to-live (TTL) value

Used in any situation where an expiration time is needed. For example, you do not
want authentication to last beyond the current session and also want a failed
command to time out instead of hanging the box forever.

traffic flow
(bandwidth gain)

Also referred to as flow. A set of packets belonging to the same TCP/UDP connection
that terminate at, originate at, or flow through the SG appliance. A single request
from a client involves two separate connections. One of them is from the client to the
SG appliance, and the other is from the SG appliance to the OCS. Within each of
these connections, traffic flows in two directions—in one direction, packets flow out
of the SG appliance (outbound traffic), and in the other direction, packets flow into
the SG (inbound traffic). Connections can come from the client or the server. Thus,
traffic can be classified into one of four types:
• Server inbound
• Server outbound
• Client inbound
• Client outbound
These four traffic flows represent each of the four combinations described above.
Each flow represents a single direction from a single connection.

transmission control
protocol (TCP)

TCP, when used in conjunction with IP (Internet Protocol) enables users to send data,
in the form of message units called packets, between computers over the Internet.
TCP is responsible for tracking and handling, and reassembly of the packets; IP is
responsible for packet delivery.

transparent proxy

A configuration in which traffic is redirected to the SG appliance without the
knowledge of the client browser. No configuration is required on the browser, but
network configuration, such as an L4 switch or a WCCP-compliant router, is
required.

213

Volume 4: Securing the Blue Coat SG Appliance

trial period

Starting with the first boot, the trial period provides 60 days of free operation. All
features are enabled during this time.

U
unicast alias

Defines an name on the appliance for a streaming URL. When a client requests the
alias content on the appliance, the appliance uses the URL specified in the unicastalias command to request the content from the origin streaming server.

universal time coordinates
(UTC)

An SG appliance must know the current UTC time. By default, the appliance
attempts to connect to a Network Time Protocol (NTP) server to acquire the UTC
time. If the SG appliance cannot access any NTP servers, you must manually set the
UTC time.

URL filtering

See content filtering.

URL rewrite rules

Rewrite the URLs of client requests to acquire the streaming content using the new
URL. For example, when a client tries to access content on www.mycompany.com,
the appliance is actually receiving the content from the server on 10.253.123.123. The
client is unaware that mycompany.com is not serving the content; however, the
appliance access logs indicate the actual server that provides the content.

W
WCCP

Web Cache Communication Protocol. Allows you to establish redirection of the
traffic that flows through routers.

Web FTP

Web FTP is used when a client connects in explicit mode using HTTP and accesses an
ftp:// URL. The SG appliance translates the HTTP request into an FTP request for the
OCS (if the content is not already cached), and then translates the FTP response with
the file contents into an HTTP response for the client.

Websense log type

A Blue Coat proprietary log type that is compatible with the Websense reporter tool.

X

XML responder

HTTP XML service that runs on an external server.

XML requestor

XML realm.

214

Appendix B: Using the Authentication/Authorization Agent

The Blue Coat Systems Authentication and Authorization Agent (BCAAA) allows
SGOS 5.x to manage authentication and authorization for several different realms. The
agent is installed and configured separately from SGOS 5.x and is available at the Blue
Coat Website.
The BCAAA service must be installed on a domain controller or member server,
allowing the SG to access domain controllers. The BCAAA service authenticates users
in all domains trusted by the computer on which it is running. A single installation of
the BCAAA service can support multiple appliances.
Multiple versions of BCAAA can run on the same machine. This allows you to use the
same machine to support versions of the SG that have different BCAAA version
requirements.
The BCAAA install directory can include multiple executable programs.


The program bcaaa.exe (bcaaa on Solaris) handles connections from SG
appliances and hands them off to the correct version of the processor.



The program bcaaa-99.exe (bcaaa-99 on Solaris) handles communication with
versions of the SG prior to SGOS 4.2.



The program bcaaa-100.exe (bcaaa-100 on Solaris) handles communication
with SGOS 4.2.1, SGOS 5.1.1, and SGOS 5.1.2.



The program bcaaa-110.exe (bcaaa-110 on Solaris) handles communication
with SGOS 4.2.2 , SGOS 5.1.3, and SGOS 5.1.4.



The program bcaaa-120.exe (bcaaa-120 on Solaris) handles communication
with SGOS 4.2.3, SGOS 4.2.4, and SGOS 5.2.1 and later.

When a new version of BCAAA is installed in the same installation directory as earlier
versions, the earlier versions are not removed.
This allows SG appliances that were communicating with the old version to continue to
operate.

Using the BCAAA Service
Several realms use the BCAAA service:


IWA: The BCAAA service uses an Integrated Windows Authentication (IWA) to
authenticate a user with Active Directory. When using IWA, the network typically
chooses automatically whether to use NTLM or Kerberos (IWA).


NTLM: NTLM is a subset of IWA, meant to be used with Windows NT
systems.



Kerberos: If using Kerberos, the BCAAA service must share a secret with a
Kerberos server (called a KDC) and register an appropriate Service Principal
Name (SPN). For information on sharing a secret and registering an SPN, see
“Creating Service Principal Names for IWA Realms” on page 223.

215

Volume 4: Securing the Blue Coat SG Appliance



SiteMinder and COREid: When a SiteMinder or COREid realm is referenced in policy,
a BCAAA process is created. The SG appliance then sends a configuration request that
describes the servers to use. The BCAAA service logs in to the appropriate servers
and determines configuration information to be passed back to the SG appliance
(such as the kind of credentials required). Responses from the SiteMinder and
COREid policy servers are translated into appropriate BCAAA protocol responses
and returned to the SG appliance .
Before you can use the BCAAA service with SiteMinder or COREid, you must
configure the appropriate SG realm to work with the SiteMinder or COREid servers.
The realm can be configured from the SiteMinder or COREid configuration tabs in the
Management Console or from the CLI.
Note:

Each (active) SiteMinder realm on the SG should reference a different
agent on the Policy Server.
For specific information about configuring the SiteMinder realm to work with the CA
eTrust policy servers, see Chapter 12: "CA eTrust SiteMinder Authentication" on
page 143. For specific information about configuring the COREid realm to work with
Oracle COREid Access Servers, see Chapter 6: "Oracle COREid Authentication" on
page 79.


Windows Single Sign-on (SSO): The BCAAA service is used to supply mappings for
IP addresses to logged on users. The Windows SSO realm can use domain controller
querying, or client querying, or both domain controller and client querying to
determine the logged-on user.
To use domain controller querying, you must configure the sso.ini file to enable it
and to add the domain controllers you want to query. For information on configuring
the sso.ini file, see “Modifying the sso.ini File for Windows SSO Realms” on page
188.



Novell SSO: The BCAAA service manages communication with the Novell eDirectory
server. This realm also requires that the sso.ini file be configured. For information on
configuring the sso.ini file, see “Modifying the sso.ini File for Novell SSO Realms” on
page 171.

Performance Notes
Blue Coat recommends that the Windows BCAAA service be installed on a dedicated
Windows machine. Installation of any other non-essential software might degrade the
BCAAA service performance, which in turn degrades the user experience.
This is because the BCAAA server is in the client data path for accessing protected
resources. Users make client requests to the SG appliance, which in turn proxies
authentication requests to the BCAAA service. The user must wait for the authentication
request to complete before the SG appliance responds to the user with a protected
resource.
Operating system requirements are:


IWA and COREid: Windows® 2000 or later.



SiteMinder: Windows 2000 or later or Solaris™ 5.8 or 5.9.



Novell SSO: Windows 2000 or later



Windows SSO: Windows 2000 or later

216

Appendix B: Using the Authentication/Authorization Agent

To view the application event log
The BCAAA service logs all errors to the Windows 2000 Application Event Log under the
name BCAAA.
1.

Launch the Event Log.

2.

Doubleclick the information message BCAAA service to see that the BCAAA service
has been automatically started.

To view the BCAAA service
The BCAAA service logs all errors to the Windows 2000 Application Event Log under the
name BCAAA.
1.

Launch the Event Viewer.

2.

Right-click on BCAAA and select Properties to manage the service. For example, to
make the BCAAA service start only manually, set the Startup Type to Manual.
(Automatic is the default setting.)

Completing Setup for the BCAAA Service
Once the BCAAA service is installed, you must complete BCAAA setup by configuring
the service to work with Windows.
To configure the BCAAA service:
1.

2.

Open the properties panel for the BCAAA service.
a.

Select the Log-on tab.

b.

Change the account to the one you created for the BCAAA service, and enter
the password.

c.

Click OK. You might be warned that the account has been given logon as
service privileges.

Verify in Local Security Policy's User Rights Assignment folder that the BCAAA
Service user account has been added to the list of the Log on as a service policy.
Note:

3.

You must have modify/write privileges in the BCAAA folder.

(Optional) If group-based authorization is being done, then:


Ensure that the user impersonation privilege is set for the SERVICE group. For
more information setting the user impersonation privilege, see: http://
support.microsoft.com/default.aspx?scid=kb;en-us;831218.



Ensure that the Active Directory computer account running the BCAAA service
has the Trust computer for delegation configuration property enabled.

4.

(Optional) For all users authenticating to the SG using IWA realms, user accounts in
the Active Directory must have permission to log onto the machine where the
BCAAA server is running.

5.

Go to the user’s account properties user account tab.

6.

Click the Log On To… button to specify the domain that computers can log onto. If the
network environment restricts users to specific computers, then each user must have
the name of the host running the BCAAA service added to their list.

221

Volume 4: Securing the Blue Coat SG Appliance

Notes on SSL and Systems Running pre-Windows 2003
The BCAAA service fails to negotiate an SSL connection under certain conditions when
the BCAAA user is changed.
If the BCAAA was originally running as LocalSystem and a self-signed certificate was
created and saved (that is, you chose to save the automatically generated certificate
option) SSL fails if the BCAAA service is changed to run as a different user.
To solve this:
1.

Stop the BCAAA service.

2.

From the Run prompt, type mmc, which is the Microsoft Management Console.

3.

Click File > Add/Remove Snap-in > Add > Certificates > Add Service Account > Local
Computer > BCAAA

4.

Delete any certificate shown in the BCAAA/Personal category.

Now when the BCAAA is run, it can create a new certificate and successfully handle an
SSL connection.

Notes on SSL and Systems Running Windows 2003 and Later
The BCAAA service fails to negotiate an SSL connection under certain conditions when
the BCAAA user is changed.
The certificate store can only be accessed by a Domain Administrator or LocalSystem. If
the BCAAA service is running as a Domain User who does not have Domain
Administrator privileges, it cannot negotiate an SSL connection.
Solutions:


Make the BCAAA user a Domain Administrator or an Administrator of the computer
where the BCAAA service is running.



Give the BCAAA user access the certificate store:


Stop the BCAAA service.



From the Run prompt, launch the regedit program to give the BCAAA user full
access to the following key and its children:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Services

Installing the BCAAA Service on a Solaris System
To install the BCAAA service on Solaris, complete the following instructions. You must be
root to complete installation.
Note: For successful installation of the BCAAA service on a Solaris system, you need
libstdc++.so.5", usually installed with package
SFWgcc32 gcc-3.2 - GNU Compiler Collection Version 3.2

1.

Download the shell script to your system.

2.

Execute the shell script:
# sh bcaaa-version_number-SOLARIS-install.sh

222

Appendix B: Using the Authentication/Authorization Agent

3.

Answer the questions to install the service on your Solaris system. A sample session is
shown below:
Enter a path to a scratch directory [/tmp]:
Install Blue Coat Systems Authentication and Authorization Agent
(BCAAA)? (y/n)y
Enter user that should own the installed files [root]
Enter group for the installed files [root]
/usr/local/bin/bcaaa installed
/usr/local/bin/bcaaa-100 installed
Libraries installed in /usr/local/lib/BlueCoatSystems/
/usr/local/etc/bcaaa.ini installed
If you use inetd, append the following line to /etc/services
bcaaa
16101/tcp
Authentication Agent

#Blue Coat Systems

If you use inetd, append the following line to /etc/inetd.conf, then
signal inetd to re-read the configuration file
If you use something else, make the equivalent changes
bcaaa stream tcp nowait root /usr/local/bin/bcaaa bcaaa -c /usr/local/
etc/bcaaa.ini
Installation complete

Creating Service Principal Names for IWA Realms
For the BCAAA service to participate in an IWA Kerberos authentication exchange, it
must share a secret with the Kerberos server (called a KDC) and have registered an
appropriate Service Principal Name (SPN).
You can share the secret two ways:


LocalSystem
In this approach the SPN is registered with the NetBIOS name of the machine on
which BCAAA is running. BCAAA runs under LocalSystem (the default for services),
and uses the machine's shared secret.
The primary advantage of this approach is convenience: it works with the default
settings for service installation. The disadvantage is that only one BCAAA server is
allowed for the realm, so you cannot have a backup server.
Note: Handling of the shared secret is done by Windows when the machine joins the

domain; there is no explicit knowledge of the shared secret by SGOS or by BCAAA.


Service Account
You can also create a service account for the BCAAA service and register the SPN on
the service account. This allows multiple servers to run BCAAA all using the same
account.
The advantage is the ability to have a backup BCAAA server. The disadvantage is
that it requires additional configuration on the Active Directory server, the domain
controller, and on each BCAAA machine. It is also less secure, since the BCAAA
account password is shared among multiple machines.

223

Volume 4: Securing the Blue Coat SG Appliance
To share a secret by creating a service account:
Note: All steps require administrator privileges.

1.

Go to the Active Directory server.

2.

Create an account for use by the BCAAA service.

3.

Create a password.

4.

On the domain controller, open the domain policy console and modify the Local
Policy’s user rights assignment and allow the account you created in on the Active
Directory to have the right to "act as the operating system."

5.

Run the following command:
setspn -A HTTP/FQDN-of-host name

where name is the name of the account created in step 1 and the FQDN is the virtual
URL that was set in the authentication realm. For example:
setspn -A HTTP/krbproxy.authteam.waterloo.bluecoat.com authteam\krbbcaaa
Note:

The setspn application might have to be downloaded from Microsoft. It is
installed by default in program files\resource kit.
(Optional) To create a group account (a BCAAA user account capable of doing
group-based authorization):
If group-based authorization is being done, then:
1.

Ensure that the user impersonation privilege is set for the SERVICE group.
Note:

For information on setting the user impersonation privilege, see

http://support.microsoft.com/default.aspx?scid=kb;en-us;831218

2.

Ensure that the Active Directory computer account running the BCAAA service has
the "Trust computer for delegation" configuration property enabled.

On each machine where you want to run the BCAAA service:
1.

Install the BCAAA service as normal.

2.

Open the Properties panel for the BCAAA service and select the Logon tab. Change
the account to the one you created on the Active Directory server, and enter the
password. When you click OK, it might warn you that the account has been granted
"Log On as A Service right".

3.

Change the security on the BCAAA install directory to give the account created on the
Active Directory server full control.

All these machines now share the same secret with the KDC and can decrypt service
tickets intended for the service described by the SPN.

224

Appendix B: Using the Authentication/Authorization Agent

Troubleshooting Authentication Agent Problems
This section describes some common problems you might encounter when setting up or
using the BCAAA service on a Windows platform.
To troubleshoot the BCAAA service, launch the event viewer.
The Properties pane displays, providing information about the status of the BCAAA
service at that time. Note the Type and the Event ID. The description below the Type/
Event ID lists the problem. You can often find more information about the problem and
suggestions for its solution in “Common BCAAA Event Messages” on page 225.
Common problems:


If an attempt to start the BCAAA service is issued when BCAAA is already started,
the following error message displays:
The requested service has already been started.



If another application is using the same port number as the BCAAA service, the
following messages are displayed:
The BCAAA service could not be started.
A system error has occurred.
System error 10048 has occurred.
Only one usage of each socket address (protocol/network address/port) is normally permitted.

Common BCAAA Event Messages
Following are the most common event messages that can be logged to the Windows 2000
Application Event Log. Most of the event messages not listed here are error status
messages returned by Win32 function calls. When a Win32 call fails, the error code and
error text containing the reason for the error displays in the event log under the name
BCAAA.
To view the BCAAA event log:
1.

Right click on My Computer and select Manage.

2.

Select System Tools > Event Viewer > Application.

For each BCAAA event message, the event message is displayed along with the event
number.
Table B-1. BCAA Event Messages
Message ID

Message

Description

200

Various messages

The associated message provides information about a
condition that is not an error.

300

Various messages

The associated message warns about an unexpected
condition that does not prevent operation.

400

Various messages

The associated message describes an error condition that
prevents normal operation.

1001

Authentication Agent service started:
port=# threads=# socket=0x#
process id=# agent version=#
SG Appliance version=#

This indicates successful startup and provides
information about the agent.

225

Volume 4: Securing the Blue Coat SG Appliance

Table B-1. BCAA Event Messages (Continued)
Message ID

Message

Description

1002

Authentication Agent stopped

This indicates normal shutdown of the service.

1003

SG Appliance (a.b.c.d) connected;
Process # spawned as #

This indicates a SG appliance has connected to the agent
(Windows only).

1004

SG Appliance agent process exited
(normal logout)

This indicates normal logout by a SG appliance.

1005

Process %d has terminated,
ExitCode=0x#, link=0x#

This indicates an unexpected termination of an agent
process (Windows only).

1006

Service dispatcher exited.

This indicates an unexpected termination of the service
dispatcher.

1007

CreateNamedPipe failed, pipe='%s'

The agent dispatcher could not create the named pipe for
the reason given.

1008

ConnectNamedPipe failed, pipe='%s'

The agent process could not obtain the information from
the dispatcher on the named pipe for the reason given.

1009

WriteFile failed, pipe='%s'

The dispatcher could not write information to the named
pipe for the reason given.

1011

CreateThread (ProcessTimerThread)
failed

The dispatcher could not create its timer thread.

1012

Failed to create SG Appliance process
'%s'

1019

Various

The dispatcher was unable to determine the exit status of
an agent process.

1020

Terminating SG Appliance process #,
ProcNum=# Handle=0x#

An agent process was active when the Windows service
was shut down.

1022

Various

The associated message reports the status of a SG
appliance login attempt.

1101

BasicAuth: CloseHandle failed; user
'xx\\xx'

The agent was unable to close the login handle for the
specified user.

1102

Username: '%s\\%s' too long

The SG appliance offered the specified username, which
is too long.

1106

Various

An attempted authentication using BASIC credentials
failed for the reason given.

1107

User Right 'Act as part of the operating
system' required for Basic
Authentication

The agent does not have the necessary privileges to do
BASIC authentication

1108

Various

The agent was unable to determine information about the
user for the reason given.

1202

Unable to create GroupsOfInterest
mutex 'xx' - already exists

The agent could not create the Windows mutex needed
for group authorization checks because it already exists.

1203

Unable to create GroupsOfInterest
mutex 'xx

The agent could not create the Windows mutex needed
for group authorization checks.

The BCAAA server does not have the same version of
BCAAA available as the SG is expecting.

226

Appendix B: Using the Authentication/Authorization Agent

Table B-1. BCAA Event Messages (Continued)
Message ID

Message

Description

1204

OpenMutex failed for AuthGroups
mutex '%s', group='%s'

The agent was unable to open the Windows mutex
needed for group authorization checks.

1205

Various

The agent was unable to close the Windows mutex
named for the reason given.

1207

GetAclInformation failed

The agent was unable to obtain ACL information needed
to do group authorization checks.

1209

GetKernelObjectSecurity failed for
AuthGroup='%s'

The agent was unable to obtain security information
about the specified group.

1210

SetKernelObjectSecurity failed

The agent was unable to set up security information for
the reason specified.

1211

InitializeSecurityDescriptor failed

The agent was unable to initialize the security descriptor
for the reason specified.

1212

GetSecurityDescriptorDacl failed

The agent was unable to get the discretionary access
control list (DACL) for the reason specified.

1213

SetSecurityDescriptorDacl failed

The agent was unable to set the discretionary access
control list (DACL) for the reason specified.

1214

InitializeAcl failed

The agent was unable to initialize the access control list
(ACL) for the reason specified.

1215

GetUserName failed for
AuthGroup='%s'

The agent was unable to determine the username while
processing the specified group.

1217

GetAce failed for AuthGroup='%s'

The agent was unable to get the access control entry
(ACE) for the specified group.

1218

AddAce failed

The agent was unable to add the necessary access control
entry (ACE) for the reason specified.

1219

AddAccessAllowedAce failed

The agent was unable to add the necessary "access
allowed" access control entry (ACE).

1220

Could not establish groups-of-interest:
result=0x##

The agent was unable to initialize groups-of-interest
checking.

1221

AuthGroup '%s' does not exist

The specified group does not exist.

1222

IWA RevertSecurityContext failed,
user='%s'

The agent could not revert the security context for the
specified user.

1223

BASIC: RevertToSelf failed, user='%s'

The agent could not revert the security context for the
specified user.

1224

Error calling OpenProcessToken

The agent's call to OpenProcessToken failed for the
specified reason.

1225

Error calling LookupPrivilegeValue

The agent could not get information about a needed
privilege.

1226

Error calling AdjustTokenPrivileges

The agent could not adjust its privileges as required.

1227

ImpersonateLoggedOnUser failed;
Group access denied for user '%s'

The agent could not impersonate the specified user.

227

Volume 4: Securing the Blue Coat SG Appliance

Table B-1. BCAA Event Messages (Continued)
Message ID

Message

Description

1228

IWA: ImpersonateSecurityContext
failed; Group access denied for user '%s'

The agent could not impersonate the specified user.

1301

NOTE: Pending ContextLink=### timed
out; deleting SecurityContext h=##
TS=## now=##

The SG appliance did not provide a response to a
challenge quickly enough.

1302

Various

An authentication request from a SG appliance
referenced an in-progress request that has timed out or
does not exist.

1304

Various

The agent was unable to delete a security context for the
reason given.

1305

AcceptSecurityContext failure,
SEC_E_INVALID_HANDLE,
ContextLink=### count=#

The agent was provided with an invalid context handle.

1306

Various

The client provided an invalid token to the authentication
system.

1308

AcceptSecurityContext failure,
ContextLink=# count=#, detail=#(xxx)

Windows rejected the authentication attempt for the
reason given.

1310

Various

This records the failure of NTLM authentication or group
authorization.

1311

3:Failed NTLM Authentication for user:
'%s'

This records the failure of NTLM authentication; the user
name was supplied by the client.

1312

Various

The agent could not determine the username from the
NTLM type 3 message supplied by the client.

1313

Invalid Type3 message

The client provided an NTLM type 3 message that was
invalid.

1314

BASE64_Decode: Length of token
exceeds max (%d)

The client provided an NTLM token that was too long.

1316

Unsupported version in request:
%d(0x%x)

The SG appliance sent a request with an unsupported
version number.

1401

Various

The agent lost communication with the SG appliance.

1403

Various

The agent is aborting for the reason given.

1402

Unexpected thread 0 exit

The agent exited unexpectedly.

1404

Unable to get ProcessInfo from parent
process.

The agent could not obtain its information from the
dispatcher.

1405

CreateFile failed, pipe='xx'

The agent could not create a handle for the dispatcher's
named pipe.

1406

WaitNamedPipe failed, pipe='%s'

The agent could not wait for the dispatcher's named pipe.

1407

ReadFile failed, pipe='%s'

The agent could not read information from the
dispatcher's named pipe.

228

Appendix B: Using the Authentication/Authorization Agent

Table B-1. BCAA Event Messages (Continued)
Message ID

Message

Description

1409

Various

The agent could not create the specified thread for the
reason given.

1412

Various

The agent could not create a required Windows event
object.

1413

AuthMethod 'xxs' not supported:
returning _AuthResult=0x##

The SG appliance requested an unsupported
authentication mechanism.

1414

Various

The specified request is unsupported.

1500

Various

The agent has a problem with memory allocation;
typically this means there is not enough memory.

1501

Unable to allocate memory for ProcLink
buffer.

The agent could not allocate some needed memory.

1502

Unable to allocate memory for
ContextLink buffer.

The agent could not allocate some needed memory.

1503

Various

The agent was unable to allocate needed memory.

1604

Service dispatch failed

The Windows service dispatcher failed to start.

1605

RegisterServiceCtrlHandler failed

The agent dispatcher was unable to register the service
control handler.

1608

SetServiceStatus failed,
g_StatusHandle=%d

The agent was unable to set the service's status.

1610

Unsupported service control code: #

Windows sent a service control code that the agent does
not support.

1701

WSASocket failed

The agent could not create a Windows socket for the
reason given.

1702

WSAStartup failed.

The agent could not start the Windows socket for the
reason given.

1703

Various

The agent could not send data to the SG appliance for the
reason given.

1704

Various

The agent could not receive data from the SG appliance
for the reason given.

1705

accept failed

The agent dispatcher could not initialize to accept new
connections.

1706

bind failed, PortNumber=#

The agent dispatcher could not bind to the specified port.

1707

listen failed.

The agent dispatcher could not listen for new
connections.

1708

Various

Windows reported an event wait failure to the agent
while doing I/O on the socket.

1709

The agent is already running or the
agent's port # is in use by another
process

Some other process is already using the port needed by
the agent.

229

Volume 4: Securing the Blue Coat SG Appliance

Table B-1. BCAA Event Messages (Continued)
Message ID

Message

Description

1710

WSARecv failed reading bytes from
socket

Windows reported an error when the agent tried to
receive bytes from the SG appliance.

1711

WSASend failed sending bytes to socket. Windows reported an error when the agent tried to send
bytes to the SG appliance.

1712

Various

A socket I/O operation did not complete successfully.

1801

Error calling AcquireCredentialsHandle

The agent could not acquire its credentials from
Windows.

1803

Various

The agent could not load a needed library (DLL).

1804

Various

The agent could not locate the needed services in a library
(DLL).

1805

Unsupported SSPI Windows platform;
PlatformId=#

The reported Windows platform is not supported for
NTLM authentication.

1806

Error calling QueryContextAttributes

The agent could not determine the authenticated user's
security attributes.

1807

QuerySecurityPackageInfo failed

The agent could not get needed security information from
Windows.

1808

Max Token size too long (#); max size is
#

The client supplied an NTLM token that is too long.

1809

FreeContextBuffer failed

An attempt to free the NTLM context buffer failed.

1811

Username 'x\\y' too long

The reported user name is too long.

1901

Admin Services Error: Access denied to
domain/user/group information

The agent was unable to access necessary information.

1902

Admin Services Error: Invalid computer
from which to fetch information

The computer to be used to get security information is
invalid.

1903

Admin Services Error: Group not found

The requested group could not be found.

1904

Various

The reported error was encountered while browsing.

1905

Admin services error: could not
translate context to Unicode

The requested object for browsing could not be translated
to Unicode

1906

Admin service out of memory

The browsing service ran out of memory.

1907

Search request object too long: # > #

The requested object for browsing is too long.

2000

AcquireCredentialsHandle failed: 0x#

The agent could not acquire the credentials needed for an
SSL session.

2001

Various

The agent was unable to negotiate an SSL session for the
reason given.

2002

Various

An I/O error occurred during an SSL session.

2003

Various

The specified cryptographic error occurred during an SSL
session.

230

Appendix B: Using the Authentication/Authorization Agent

Table B-1. BCAA Event Messages (Continued)
Message ID

Message

Description

2004

Various

The specified problem occurred with a certificate during
SSL negotiation.

231

Volume 4: Securing the Blue Coat SG Appliance

232

Appendix C: Managing the SSL Client

Understanding the SSL Client
The SSL client is used to determine various SSL parameters for outgoing HTTPS
connections. Specifically, its role is to:


Identify the SSL protocol version the SG uses in negotiations with origin servers.



Identify the cipher suites used.



Determine which certificate can be presented to origin servers by associating a
keyring with the SSL client.

Creating an SSL Client
The SG is configured with a default SSL client.
Creation of the SSL client means that for every HTTPS connection to the destination
server, the SG picks the parameters needed for negotiating the SSL connection from the
SSL-client configuration. Thus, multiple SSL connections to different HTTPS
destination servers can be supported with a single SSL-client configuration. This is
similar to a browser where one configuration is used to negotiate multiple connections
with different hosts.
When the SG is acting as an SSL client (SSL origination), SSL sessions are re-used until
the server forces a fresh handshake or until the same session ID has been used 255
times.
If you just need to change the protocol, the cipher suites, or the keyring associated with
the SSL client, you do not need to recreate the client. Continue with “Associating a
Keyring and Protocol with the SSL Client” on page 233 or “Changing the Cipher Suites
of the SSL Client” on page 234.
To create the SSL client:
SGOS#(config ssl) create ssl-client default
defaulting protocol to SSLv2v3TLSv1
defaulting associated keyring-id to default
ok

To delete the SSL client:
SGOS#(config ssl) delete ssl-client default
ok

Associating a Keyring and Protocol with the SSL Client
The SSL client, called default, already exists on the SG. Keyrings that are not used to
authenticate encrypted connections do not need to be associated with the SSL client.
Important: Only one keyring can be associated with the SSL client at a time.

To associate a keyring with the SSL client and change the protocol version:
1.

Select Configuration>SSL>SSL Client.

2.

Verify Use SSL Client is selected.

233

Volume 4: Securing the Blue Coat SG Appliance

3.

Only keyrings with certificates can be associated with the SSL client, displayed in the
Keyring drop-down list. Select the keyring used to negotiate with origin content
servers through an encrypted connection.

4.

You can change the SSL Versions default from SSLv2v3TLSv1 to any other protocol
listed in the drop-down list.

5.

Click OK; click Apply

Related CLI Syntax to Associate a Keyring and Protocol with the SSL Client
SGOS#(config) ssl
SGOS#(config ssl) edit ssl-client default
SGOS#(config ssl ssl-client default) keyring-id keyring_id
SGOS#(config ssl ssl-client default) protocol {sslv2 | sslv3 | tlsv1 |
sslv2v3 | sslv2tlsv1 | sslv3tlsv1 | sslv2v3tlsv1}

Changing the Cipher Suites of the SSL Client
The cipher suite sets the encryption method used by the SG. As the encryption key
strength is determined by the signed certificate, configuring a higher cipher suite than
defined by the certificate has no affect. Conversely, the cipher suite configuration must be
high enough to accommodate certification encryption values.
This can only be done through the CLI.
To change the cipher suite of the SSL client:
The default is to use all ciphers.
You have a choice of using the interactive or non-interactive create command.
Note: Director uses non-interactive commands in profiles and overlays to create cipher
suites. For more information on Director, refer to the Blue Coat Director Configuration and
Management Guide.)

To change the cipher suites used through the:


interactive command: continue with the next procedure.



non-interactive command: skip to “To change the cipher suites non-interactively:” on
page 235.

To change the cipher suites using the interactive cipher-suites command:
Note that the Use column in the set cipher-suite output below indicates that the
default is to use all ciphers.
1.

Choose the cipher suites you want to use at the prompt.
SGOS#(config) ssl
SGOS#(config ssl) edit ssl-client default
SGOS#(config ssl ssl-client default) cipher-suite
SSL-Client Name
-------------default

Keyring Name
-----------default

Protocol
-----------SSLv2v3TLSv1

234

Appendix C: Managing the SSL Client

Cipher#
------1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Use
--yes
no
no
no
no
no
no
no
no
no
no
no
no
no
no
no
no

Description
-------------------RC4-MD5
RC4-SHA
DES-CBC3-SHA
DES-CBC3-MD5
RC2-CBC-MD5
RC4-64-MD5
DES-CBC-SHA
DES-CBC-MD5
EXP1024-RC4-MD5
EXP1024-RC4-SHA
EXP1024-RC2-CBC-MD5
EXP1024-DES-CBC-SHA
EXP-RC4-MD5
EXP-RC2-CBC-MD5
EXP-DES-CBC-SHA
AES128-SHA
AES256-SHA

Strength
-------Medium
Medium
High
High
Medium
Low
Low
Low
Export
Export
Export
Export
Export
Export
Export
Medium
High

Select cipher numbers to use, separated by commas: 1,3,4
ok

2.

(Optional) View the results. Notice the change in the Use column.
SGOS#(config ssl ssl-client default) view
SSL-Client Name
--------------default
Cipher#
------1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Use
--yes
no
yes
yes
no
no
no
no
no
no
no
no
no
no
no
no
no

Keyring Name
-----------default
Description
-------------------RC4-MD5
RC4-SHA
DES-CBC3-SHA
DES-CBC3-MD5
RC2-CBC-MD5
RC4-64-MD5
DES-CBC-SHA
DES-CBC-MD5
EXP1024-RC4-MD5
EXP1024-RC4-SHA
EXP1024-RC2-CBC-MD5
EXP1024-DES-CBC-SHA
EXP-RC4-MD5
EXP-RC2-CBC-MD5
EXP-DES-CBC-SHA
AES128-SHA
AES256-SHA

Protocol
-----------SSLv2v3TLSv1
Strength
-------Medium
Medium
High
High
Medium
Low
Low
Low
Export
Export
Export
Export
Export
Export
Export
Medium
High

To change the cipher suites non-interactively:
Enter the following commands:
SGOS#(config) ssl
SGOS#(config ssl) edit ssl-client default
SGOS#(config ssl ssl-client default) cipher-suite cipher-suite ciphersuite

235

Volume 4: Securing the Blue Coat SG Appliance

where [cipher-suite] can be any combination of the following:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

rc4-md5
rc4-sha
des-cbc3-sha
des-cbc3-md5
rc2-cbc-md5
rc4-64-md5
des-cbc-sha
des-cbc-md5
exp1024-rc4-md5
exp1024-rc4-sha
exp1024-rc2-cbc-md5
exp1024-des-cbc-sha
exp-rc4-md5
exp-rc2-cbc-md5
exp-des-cbc-sha
aes128-sha
aes256-sha

Notes:


If you do not specify any attributes, the interactive mode is assumed and the cipher
suites cannot be used by Director in profiles or overlays.



Multiple cipher suites can be specified on the command line.

Example
SGOS#(config ssl ssl-client default) cipher-suite rc4-md5 des-cbc3-md5
exp1024-rc4-md5 exp-des-cbc-sha
ok
SGOS#(config ssl ssl-client default) view
SSL-Client Name
Keyring Name
Protocol
-----------------------------------default
default
SSLv2v3TLSv1
Cipher#
------1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Use
--no
no
no
no
no
no
no
no
no
no
no
no
no
no
yes
no
no

Description
-------------------RC4-MD5
RC4-SHA
DES-CBC3-SHA
DES-CBC3-MD5
RC2-CBC-MD5
RC4-64-MD5
DES-CBC-SHA
DES-CBC-MD5
EXP1024-RC4-MD5
EXP1024-RC4-SHA
EXP1024-RC2-CBC-MD5
EXP1024-DES-CBC-SHA
EXP-RC4-MD5
EXP-RC2-CBC-MD5
EXP-DES-CBC-SHA
AES128-SHA
AES256-SHA

Strength
-------Medium
Medium
High
High
Medium
Low
Low
Low
Export
Export
Export
Export
Export
Export
Export
Medium
High

236

Appendix C: Managing the SSL Client

Troubleshooting Server Certificate Verification
Server certificate verification can be disabled for all upstream hosts or specific upstream
hosts. The SG, by default, verifies the SSL certificate presented by the upstream HTTPS
server. However, it fails to negotiate the SSL connection if SSL certificate verification fails.
The two most common causes of server certificate verification failure are:


The absence of a suitable CA certificate on the SG. Be sure that the SG is configured
with the relevant CA certificates to avoid unwanted verification failures.



If a forwarding host of type HTTPS server is being used, you can override the default
behavior by changing the ssl-verify-server option on a per-host basis.



The server is using a self-signed certificate. In this case, you need to change the
keyring to one that has a CA certificate.

Setting the SSL Negotiation Timeout
The SSL negotiation timeout value dictates the time a SG waits for a new SSL handshake
to complete. This value applies to both the HTTPS Reverse Proxy and SSL origination.
You can change the default SSL negotiation timeout value if the default, 300 seconds, is
not sufficient for your environment. This value can only be changed through the CLI; it
cannot be set from the Management Console.
To change the HTTPS Reverse Proxy timeout period, enter the follow commands from the
command prompt:
SGOS#(config) ssl
SGOS#(config ssl) view ssl-nego-timeout
300
SGOS#(config ssl) ssl-nego-timeout seconds

237

Volume 4: Securing the Blue Coat SG Appliance

238

Appendix D: XML Protocol

The XML realm uses a SOAP 1.2 based protocol for the Blue Coat supported protocol.
A schema has been placed at http://www.bluecoat.com/xmlns/xml-realm/1.0.
This appendix includes the following sections:


Section A: "Authenticate Request" on page 240



Section B: "Authenticate Response" on page 242



Section C: "Authorize Request" on page 244



Section D: "Authorize Response" on page 245

239

Volume 4: Securing the Blue Coat SG Appliance
Section A: Authenticate Request

Section A: Authenticate Request
GET Method (User Credentials in Request)
If the user credentials are not set in the HTTP headers, the username and password are
added to the query. The name of the username parameter is configured in the realm. The
groups and attributes of interest are only included if the realm is configured to include
them.
http://:/?parameter name>=&password=[&group=&group=2>…&attribute=&attribute=]

GET Method (User Credentials in Headers)
If the user credentials are in the HTTP headers, the password is not added to the query.
http://://
authenticate?=[&group=1>&group=…&attribute=&attribute=]

POST Method (User Credentials in Request)
The parameter name of the username is configured in the realm. The groups and
attributes of interest will only be included if the realm is configured to include them.

xmlns:env="http://www.w3.org/2003/05/soap-envelope">
xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
xmlns:m="http://www.bluecoat.com/xmlns/xml-realm/1.0">
Username
password

group1
group2


attribute1
attribute2





POST Method (User Credentials in Headers)
If the user credentials are in the HTTP headers, the password is not added to the request.

xmlns:env="http://www.w3.org/2003/05/soap-envelope">
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
xmlns:m="http://www.bluecoat.com/xmlns/xml-realm/1.0">

240

Appendix D: XML Protocol

Section A: Authenticate Request
Username
challenge state

group1
group2


attribute1
attribute2





241

Volume 4: Securing the Blue Coat SG Appliance
Section B: Authenticate Response

Section B: Authenticate Response
Success
All of the response fields except "full-username" are optional. The intersection of the
groups of interest and the groups that the user is in are returned in the groups element.
The attributes of interest for the user are returned in a flattened two dimensional array of
attribute names and values.

xmlns:env="http://www.w3.org/2003/05/soap-envelope">
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
xmlns:m="http://www.bluecoat.com/xmlns/xml-realm/1.0">
full-username

group2


attribute2
value2a
attribute2
value2b
attribute2
value2c





Failed/Denied
The failed response includes a text description of the failure that becomes the text
description of the error reported to the user. The fault-code is one of a set of SGOS
authentication errors that can be returned from the responder. The codes are returned as
strings, but are part of an enumeration declared in the schema for the protocol. Only codes
in this list are acceptable.
account_disabled
account_restricted
credentials_mismatch
general_authentication_error
expired_credentials
account_locked_out
account_must_change_password
offbox_server_down
general_authorization_error
unknown_error

xmlns:env="http://www.w3.org/2003/05/soap-envelope">



env:Sender

242

Appendix D: XML Protocol

Section B: Authenticate Response


Bad username or password


xmlns:e="http://www.bluecoat.com/xmlns/xml-realm/1.0">
general_authentication_error






243

Volume 4: Securing the Blue Coat SG Appliance
Section C: Authorize Request

Section C: Authorize Request
The groups and attributes of interest for the user are embedded in the request if they are
configured to be included. The XML responder must not require credentials for
authorization requests.

GET Method
http://:/path>?name>=[&group=&group=…&attribute=>&…]

POST Method

xmlns:env="http://www.w3.org/2003/05/soap-envelope">
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
xmlns:m="http://www.bluecoat.com/soap/xmlns/xml-realm/1.0">
Username

group1
group2


attribute1
attribute2





244

Appendix D: XML Protocol

Section D: Authorize Response

Section D: Authorize Response
Success
Only applicable groups and attributes are returned. Multi-valued attributes are returned
by multiple instances of the same attribute name.

xmlns:env="http://www.w3.org/2003/05/soap-envelope">
env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
xmlns:m="http://www.bluecoat.com/xmlns/xml-realm/1.0">

group2


attribute2
value2a
attribute2
value2b
attribute2
value2c





Failed

xmlns:env="http://www.w3.org/2003/05/soap-envelope">



env:Receiver


Could not contact LDAP server


xmlns:e="http://www.bluecoat.com/xmlns/xml-realm/1.0">
offbox_server_down






245

Volume 4: Securing the Blue Coat SG Appliance
Section D: Authorize Response

246

Appendix E: Authentication and Authorization Errors

Following is the list of all groups and individual errors that can be permitted during
authentication and authorization. The first table lists the groups and the individual
errors within each group. The second table lists all of the individual errors along with
descriptions of the errors.
Table E-1. Groups and Individual Errors
Error Group

CPL

Members

Description

All

All

account_disabled
account_expired
account_locked_out
account_must_change_password
account_restricted
account_wrong_place
account_wrong_time
agent_config_changed
agent_config_cmd_failed
agent_connection_failed
agent_init_failed
agent_no_groups_provided
agent_resource_not_protected
agent_too_many_retries
agent_unsupported_scheme
authorization_username_too_long

Includes all errors that can be
permitted. Note that this group
includes errors such as
need_credentials which if
permitted will result in the user
never being challenged. As this is
not the desired behavior for most
realms (i.e. the user should be
given the chance to enter
credentials) do not permit this
group when using challenge
realms. Instead, use combinations
of the other error groups as
appropriate.

basic_password_too_long
basic_username_too_long
cannot_decrypt_secret
cannot_determine_authorization_
username
cannot_determine_full_username
cannot_determine_username
cannot_expand_credentials_
substitution
cannot_redirect_connect
cannot_redirect_https_to_http
cannot_setup_working_dir
cert_explicit_unsupported
certificate_missing
credential_decode_failure
credentials_mismatch

247

Volume 4: Securing the Blue Coat SG Appliance

Table E-1. Groups and Individual Errors (Continued)
Error Group

CPL

Members

Description

domain_controller_query_disabled
expired_credentials
form_does_not_support_connect
form_requires_basic_support
general_authentication_error
general_authorization_error
guest_user
invalid_ip
invalid_license
invalid_local_user_list
invalid_realm
invalid_search_credentials
invalid_surrogate
issuer_too_long
ldap_busy
ldap_filter_error
ldap_inappropriate_auth
ldap_insufficient_access
ldap_invalid_credentials
ldap_invalid_dn_syntax
ldap_loop_detect
ldap_no_such_attribute
ldap_no_such_object
ldap_partial_results
ldap_server_down
ldap_timelimit_exceeded
ldap_timeout
ldap_unavailable
ldap_unwilling_to_perform
missing_base_dn
missing_form_configuration
multiple_users_matched
need_credentials
netbios failure
netbios_cannot_send
netbios_multiple_users
netbios_no_computer_name
netbios_no_domain_name
netbios_no_user_name
netbios_recv_failed
netbios_reply_invalid
netbios_reply_timeout
no_offbox_url_specified
no_servers
no_user_in_cert
not_attempted
not_ssl
offbox_abort
offbox_missing_secret
offbox_process_create_failed
offbox_protocol_error
offbox_server_down

248

Appendix E: Authentication and Authorization Errors

Table E-1. Groups and Individual Errors (Continued)
Error Group

CPL

Members

Description

offbox_server_unreachable
offbox_timeout
otp_already_used
password_too_long
radius_socket_interface
rdns_cannot_determine_name
rdns_failed
redirect_from_vh
sspi_context_lost
sspi_context_too_old
sspi_domain_controller_not_found
sspi_invalid_handle
sspi_invalid_mechanism
sspi_invalid_token
sspi_invalid_type3_message
sspi_logon_denied
sspi_logon_type_not_granted
sspi_no_authenticating_authority
sspi_null_lm_password
sspi_process_create_failed
sspi_rpc_error
sspi_service_disabled
sspi_timeout
sspi_unable_to_connect_to_agent
subject_too_long
too_many_users
unable_to_query_client
unknown_user
user_domain_not_trusted
username_too_long
Communication
Error

communication_ agent_connection_failed
error
ldap_busy
ldap_loop_detect
ldap_server_down
ldap_unavailable
ldap_unwilling_to_perform
netbios_cannot_send
netbios_reply_invalid
no_servers
radius_socket_interface
sspi_no_authenticating_authority
sspi_rpc_error
sspi_unable_to_connect_to_agent

Includes communication errors
with BCAAA, LDAP, and
RADIUS servers and during
NetBIOS queries.

Configuration
Changed

configuration_
changed

agent_config_changed
offbox_abort

The SG has been notified that
configuration affecting the realm
has been changed offbox. Used
primarily with SiteMinder and
COREid realms.

general_authentication_error

A general authentication error has
occurred. This is returned when a
specific error does not apply. It
does not include all
authentication errors.

General
general_
Authentication authentication_
Failure
failure

249

Volume 4: Securing the Blue Coat SG Appliance

Table E-1. Groups and Individual Errors (Continued)
Error Group

CPL

Members

Description

General
Authorization
Failure

general_
authorization_
failure

cannot_determine_authorization_
username

A general authorization error has
occurred. This is returned when a
specific error does not apply. It
does not include all authorization
errors. This can be returned as an
authentication error in realms that
do not support specifying a
separate authorization realm.

General Offbox
Error

offbox_error

agent_connection_failed
agent_init_failed
cannot_determine_full_username

general_authorization_error

ldap_busy
ldap_loop_detect
ldap_server_down
ldap_timelimit_exceeded
ldap_timeout
ldap_unavailable
ldap_unwilling_to_perform

Includes all errors that can result
with failures found during any
offbox configuration or
communications. It includes all
errors found in the
Communication Error group.

netbios failure
netbios_cannot_send
netbios_multiple_users
netbios_no_computer_name
netbios_no_domain_name
netbios_no_user_name
netbios_recv_failed
netbios_reply_invalid
netbios_reply_timeout
no_servers
offbox_process_create_failed
offbox_protocol_error
offbox_server_down
offbox_server_unreachable
offbox_timeout
radius_socket_interface
rdns_cannot_determine_name
rdns_failed
sspi_context_lost
sspi_context_too_old
sspi_invalid_mechanism
sspi_no_authenticating_authority
sspi_process_create_failed
sspi_rpc_error
sspi_timeout
sspi_unable_to_connect_to_agent
Ident Error

ident_error

Initialization initialization_
Error
error

Errors found during Ident query
agent_init_failed
offbox_process_create_failed
sspi_process_create_failed

Internal Error internal_error
Invalid BCAAA
Request

invalid_bcaaa_
request

Errors related to initializing the
realm.
Any internal error.

sspi_context_lost
sspi_context_too_old
sspi_invalid_mechanism

Includes errors returned if the
request sent to BCAAA is invalid.
Applies to IWA realms only.

250

Appendix E: Authentication and Authorization Errors

Table E-1. Groups and Individual Errors (Continued)
Error Group

CPL

Members

Description

Invalid
Configuration

invalid_
configuration

agent_config_cmd_failed
agent_no_groups_provided
agent_resource_not_protected
agent_too_many_retries
agent_unsupported_scheme

Includes any errors that resulted
from a possible misconfiguration
of the SG. These errors usually
require administrator action to
address.

cannot_decrypt_secret
cannot_determine_full_username
cannot_determine_username
cannot_setup_working_dir
cert_explicit_unsupported
domain_controller_query_disabled
form_does_not_support_connect
form_requires_basic_support
invalid_local_user_list
invalid_realm
invalid_search_credentials
ldap_filter_error
ldap_inappropriate_auth
ldap_insufficient_access
ldap_invalid_dn_syntax
ldap_no_such_attribute
ldap_no_such_object
ldap_partial_results
missing_base_dn
missing_form_configuration
no_offbox_url_specified
no_servers
not_ssl
offbox_missing_secret
offbox_protocol_error
offbox_server_unreachable
sspi_domain_controller_not_found
sspi_logon_type_not_granted
sspi_null_lm_password
sspi_service_disabled
Invalid
License

invalid_license

invalid_license

An invalid license was found for
an authentication component.

Invalid
NetBIOS Reply

invalid_netbios_
reply

netbios failure
netbios_multiple_users
netbios_no_computer_name
netbios_no_domain_name
netbios_no_user_name
netbios_recv_failed

The NetBIOS reply was invalid.

251

Volume 4: Securing the Blue Coat SG Appliance

Table E-1. Groups and Individual Errors (Continued)
Error Group

CPL

Members

Description

Invalid User
Information

invalid_user_
info

authorization_username_too_long

Includes errors that result from
invalid user information being
entered.

basic_password_too_long
basic_username_too_long
cannot_expand_credentials_
substitution
credential_decode_failure
credentials_mismatch
general_authentication_error
invalid_surrogate
issuer_too_long
ldap_invalid_credentials
otp_already_used
password_too_long
sspi_invalid_handle
sspi_invalid_token
sspi_invalid_type3_message
sspi_logon_denied
subject_too_long
user_domain_not_trusted
username_too_long

RDNS Failure

rdns_failure

Redirect Error redirect_error

Request
Timeout

request_timeout

rdns_cannot_determine_name
rdns_failed

Errors found during Reverse DNS
lookup.

cannot_redirect_connect
cannot_redirect_https_to_http
redirect_from_vh

Errors found while attempting to
redirect the user’s request for
authentication. Only returned
when using a redirect
authentication mode.

ldap_timelimit_exceeded
ldap_timeout

Includes timeout errors with
authentication servers.

netbios_reply_timeout
offbox_timeout
sspi_timeout
Single Sign-on
Failure

sso_failure

invalid_ip
multiple_users_matched
too_many_users
unknown_user
unable_to_query_client

User Account
Error

user_account_
error

account_disabled
account_expired
account_locked_out
account_must_change_password
account_restricted
account_wrong_place
account_wrong_time

Errors returned during Single
Sign-on authentication. These
errors apply to Windows SSO and
Novell SSO realms only.

Errors with the user’s account.

expired_credentials

252

Appendix E: Authentication and Authorization Errors

Table E-1. Groups and Individual Errors (Continued)
Error Group

CPL

Members

Description

User
Credentials
Required

credentials_
required

certificate_missing

User credentials are required. Do
not permit this error if the user
should be challenged for
credentials.

guest_user
need_credentials
no_user_in_cert

Table E-2. Individual Errors
Error Name

Description

Groups

account_disabled

Account is disabled.

All
User Account Error

account_expired

Account has expired.

All
User Account Error

account_locked_out

Account is locked out.

All
User Account Error

account_must_change_password

Account password must be changed.

All
User Account Error

account_restricted

Account is restricted.

All
User Account Error

account_wrong_place

Account cannot be used from this location.

All
User Account Error

account_wrong_time

Account logon time restricted - cannot be used
now.

All
User Account Error

agent_config_changed

Agent reports server configuration has
changed; please try your request again.

All
Configuration Changed

agent_config_cmd_failed

Configuration of the authentication agent failed All
Invalid Configuration

agent_connection_failed

The authentication agent could not
communicate with its authority.

All
Communication Error
General Offbox Error

agent_init_failed

The authentication agent failed to initialize.

All
Initialization Error
General Offbox Error

agent_no_groups_provided

The authentication agent did not receive the
group list from the server.

All
Invalid Configuration

agent_resource_not_protected

The authentication agent reports that the
resource is not protected.

All
Invalid Configuration

agent_too_many_retries

Agent configuration failed.

All
Invalid Configuration

agent_unsupported_scheme

The requested authentication scheme is not
supported.

All
Invalid Configuration

authorization_username_too_long

The resolved authorization username is too
long.

All
Invalid User Information

basic_password_too_long

Basic password is too long.

All
Invalid User Information

basic_username_too_long

Basic username is too long.

All
Invalid User Information

253

Volume 4: Securing the Blue Coat SG Appliance

Table E-2. Individual Errors (Continued)
Error Name

Description

Groups

cannot_decrypt_secret

Cannot decrypt shared secret.

All
Invalid Configuration

cannot_determine_authorization_user
name

Could not determine the authorization
username.

All
General Authorization
Failure

cannot_determine_full_username

Could not determine full user name.

All
Invalid Configuration
General Offbox Error

cannot_determine_username

Agent could not determine simple user name.

All
Invalid Configuration

cannot_expand_credentials_substituti
on

The substitution used to determine the
credentials could not be expanded.

All
Invalid User Information

cannot_redirect_connect

Cannot use origin-redirect or form-redirect for
CONNECT method (explicit proxy of https
URL)

All
Redirect Error

cannot_redirect_https_to_http

Cannot redirect an HTTPS request to an HTTP
virtual URL

All
Redirect Error

cannot_setup_working_dir

Unable to setup working directory for COREid
AccessGate

All
Invalid Configuration

cert_explicit_unsupported

Certificate authentication not supported for
explicit proxy.

All
Invalid Configuration

certificate_missing

No certificate found. Check that verify-client is
set on https service.

All
User Credentials
Required

credential_decode_failure

Unable to decode base64 credentials.

All
Invalid User Information

credentials_mismatch

Credentials did not match.

All
Invalid User Information

domain_controller_query_disabled

Windows SSO Domain Controller Querying is
not enabled on the Single Sign-on agent.

All
Invalid Configuration

expired_credentials

Credentials on back-end server have expired.

All
User Account Error

form_does_not_support_connect

Cannot use form authentication for CONNECT
method (explicit proxy of https URL)

All
Invalid Configuration

form_requires_basic_support

Form authentication requires the realm to
support Basic credentials.

All
Invalid Configuration

general_authentication_error

General authentication failure due to bad user
ID or authentication token.

All
General Authentication
Failure
Invalid User Information

general_authorization_error

Unable to authorize authenticated user.

All
General Authorization
Failure

guest_user

Credentials required.

All
User Credentials
Required

invalid_ip

The IP address of this computer could not be
determined by the Single Sign-on agent.

All
Single Sign-on Failure

254

Appendix E: Authentication and Authorization Errors

Table E-2. Individual Errors (Continued)
Error Name

Description

Groups

invalid_license

The license for the configured realm does not
exist or is invalid. A valid license must be
installed.

All
Invalid License

invalid_local_user_list

Invalid local user list.

All
Invalid Configuration

invalid_realm

The specified realm is invalid.

All
Invalid Configuration

invalid_search_credentials

The LDAP search credentials are invalid.

All
Invalid Configuration

invalid_surrogate

The surrogate is invalid for the specified realm.

All
Invalid User Information

issuer_too_long

Certificate's issuer string is too long.

All
Invalid User Information

ldap_busy

LDAP: server busy.

All
Communication Error
General Offbox Error

ldap_filter_error

LDAP: filter error.

All
Invalid Configuration

ldap_inappropriate_auth

LDAP: inappropriate authentication.

All
Invalid Configuration

ldap_insufficient_access

LDAP: insufficient access.

All
Invalid Configuration

ldap_invalid_credentials

LDAP: invalid credentials.

All
Invalid User Information

ldap_invalid_dn_syntax

LDAP: invalid DN syntax.

All
Invalid Configuration

ldap_loop_detect

LDAP: loop detected.

All
Communication Error
General Offbox Error

ldap_no_such_attribute

LDAP: No such attribute.

All
Invalid Configuration

ldap_no_such_object

LDAP: no such object.

All
Invalid Configuration

ldap_partial_results

LDAP server returned partial results.

All
Invalid Configuration

ldap_server_down

Could not connect to LDAP server.

All
Communication Error
General Offbox Error

ldap_timelimit_exceeded

LDAP server exceeded time limit.

All
Request Timeout
General Offbox Error

ldap_timeout

The LDAP request timed out.

All
Request Timeout
General Offbox Error

ldap_unavailable

LDAP: service unavailable.

All
Communication Error
General Offbox Error

255

Volume 4: Securing the Blue Coat SG Appliance

Table E-2. Individual Errors (Continued)
Error Name

Description

Groups

ldap_unwilling_to_perform

LDAP: server unwilling to perform requested
action.

All
Communication Error
General Offbox Error

missing_base_dn

No base DNs are configured.

All
Invalid Configuration

missing_form_configuration

Form authentication is not properly configured

All
Invalid Configuration

multiple_users_matched

The user query resulted in multiple users. A
unique user could not be determined.

All
Single Sign-on Failure

need_credentials

Credentials are missing.

All
User Credentials
Required

netbios failure

NetBIOS reply did not contain data needed for
authentication.

All
Invalid NetBIOS Reply
General Offbox Error

netbios_cannot_send

Could not send NetBIOS query.

All
Communication Error
General Offbox Error

netbios_multiple_users

NetBIOS reply contained multiple user names.

All
Invalid NetBIOS Reply
General Offbox Error

netbios_no_computer_name

Could not determine computer name from
NetBIOS reply.

All
Invalid NetBIOS Reply
General Offbox Error

netbios_no_domain_name

Could not determine domain name from
NetBIOS reply.

All
Invalid NetBIOS Reply
General Offbox Error

netbios_no_user_name

NetBIOS reply did not contain the user name.

All
Invalid NetBIOS Reply
General Offbox Error

netbios_recv_failed

Failed to receive reply to NetBIOS query.

All
Invalid NetBIOS Reply
General Offbox Error

netbios_reply_invalid

Reply to NetBIOS query was invalid.

All
Communication Error
General Offbox Error

netbios_reply_timeout

Timed out awaiting reply to NetBIOS query.

All
Request Timeout
General Offbox Error

no_offbox_url_specified

Off-box redirects are configured but no off-box
URL is specified.

All
Invalid Configuration

no_servers

No usable authentication servers found.

All
Communication Error
Invalid Configuration
General Offbox Error

no_user_in_cert

Could not retrieve username from certificate.

All
User Credentials
Required

256

Appendix E: Authentication and Authorization Errors

Table E-2. Individual Errors (Continued)
Error Name

Description

Groups

none

Status successful.

not_attempted

The method has not been attempted.

All

not_ssl

SSL is required but connection is not using it
(check virtual-url).

All
Invalid Configuration

offbox_abort

The request was aborted due to a change in
configuration.

All
Configuration Changed

offbox_missing_secret

Secret is not defined for authentication realm

All
Invalid Configuration

offbox_process_create_failed

Could not create offbox authentication
processes

All
Initialization Error
General Offbox Error

offbox_protocol_error

The authentication server returned an invalid
result.

All
Invalid Configuration
General Offbox Error

offbox_server_down

The authentication server cannot process
requests.

All
General Offbox Error

offbox_server_unreachable

The authentication server could not be
contacted.

All
Invalid Configuration
General Offbox Error

offbox_timeout

The request timed out while trying to
authenticate. The authentication server may be
busy or offline.

All
Request Timeout
General Offbox Error

otp_already_used

The one-time password has already been used

All
Invalid User Information

password_too_long

Password is too long.

All
Invalid User Information

radius_socket_interface

RADIUS received an unexpected socket error.

All
Communication Error
General Offbox Error

rdns_cannot_determine_name

Could not determine user name from client host
name.

All
RDNS Failure
General Offbox Error

rdns_failed

Reverse DNS address resolution failed.

All
RDNS Failure
General Offbox Error

redirect_from_vh

Redirecting from the virtual host.

All
Redirect Error

sspi_context_lost

Authentication agent rejected request (context
lost).

All
Invalid BCAAA Request
General Offbox Error

sspi_context_too_old

Authentication agent rejected request - too old.

All
Invalid BCAAA Request
General Offbox Error

sspi_domain_controller_not_found

Cannot find domain controller.

All
Invalid Configuration

sspi_invalid_handle

SSPI protocol error - invalid context handle.

All
Invalid User Information

257

Volume 4: Securing the Blue Coat SG Appliance

Table E-2. Individual Errors (Continued)
Error Name

Description

Groups

sspi_invalid_mechanism

Authentication agent rejected request - Invalid
mechanism requested.

All
Invalid BCAAA Request
General Offbox Error

sspi_invalid_token

The credentials provided are invalid.

All
Invalid User Information

sspi_invalid_type3_message

Client sent invalid NTLM Type 3 message.

All
Invalid User Information

sspi_logon_denied

The logon failed.

All
Invalid User Information

sspi_logon_type_not_granted

Requested logon type not granted.

All
Invalid Configuration

sspi_no_authenticating_authority

No authority could be contacted for
authentication.

All
Communication Error
General Offbox Error

sspi_null_lm_password

Windows NT password too complex for
LanMan.

All
Invalid Configuration

sspi_process_create_failed

NTLM realm could not create administrator
processes.

All
Initialization Error
General Offbox Error

sspi_rpc_error

Connection to authentication agent lost.

All
Communication Error
General Offbox Error

sspi_service_disabled

SSPI service disabled.

All
Invalid Configuration

sspi_timeout

Authentication agent did not respond to request
in time.

All
Request Timeout
General Offbox Error

sspi_unable_to_connect_to_agent

Unable to connect to authentication agent.

All
Communication Error
General Offbox Error

subject_too_long

Certificate's subject string is too long.

All
Invalid User Information

too_many_users

More than one user is logged onto this
computer. Only one user can be logged on for
Single Sign-on authentication.

All
Single Sign-on Failure

unable_to_query_client

The client workstation could not be queried by
the Single Sign-on agent.

All
Single Sign-on Failure

unknown_user

The user could not be determined by the Single
Sign-on agent.

All
Single Sign-on Failure

user_domain_not_trusted

The specified domain is not trusted.

All
Invalid User Information

username_too_long

Specified username is too long.

All
Invalid User Information

258

Index

A

B

access control list
creating 19, 27
restricting access with 19
access logs
digital signing
overview 66
access restrictions
access control list for 19
configuring 19
Admin layer
example 24
administrator
defining policies 20
security levels 17
ADN
realms, using with 141, 172, 190
Application Delivery Network (ADN)
Novell SSO realms, using with 141, 172, 190
policy substitution realms, using with 141, 172,
190
realm authentication, configuring policy 141, 172,
190
reflect ip address attribute, using 141, 172, 190
Windows SSO realms, using with 141, 172, 190
authenticate.mode, IWA, realm setting for 34
authentication
configuring transparent proxy authentication 35
definition of 11
guest 38
LDAP realm 109
permitted errors, understanding 37
policies 11, 15
setting options for transparent proxy
authentication 35, 36
authentication realm
typical configuration 12
authorization
definition of 11
LDAP realm 109
policies 11, 15, 55
authorization refresh time, discussed 29

BCAAA
COREid realm, using with 82
event log, viewing 221
event messages 225
installation folder, selecting 217
Service Principal Names, creating 223
services, viewing 221
SSL, using with pre-Windows 2003 222
SSL, using with Windows 2003 and higher 222
troubleshooting 225
WIDMS, configuring for 146
Blue Coat SG
read-only and read-write access 17
restricting access to 19

C
CA Certificates
certificate signing request
creating 59, 60
error message 61
lists
creating through CLI 71
creating through Management Console 70
managing 60
troubleshooting 61
CAASNT, see BCAAA
certificate realm
authentication and authorization overview 73
configuring authentication and authorization 73
defining properties 74
defining realm server properties 74
how it works 73
LDAP authorization, adding 74
local authorization, adding 74
overview 73
policies, creating 77
requirements 73
Certificate Revocation Lists (CRLs)
configuring 63
PEM encoded/DER format 63
using 62
certificate signing request
creating 59

259

Volume 4: Securing the Blue Coat SG Appliance

Certificate Signing Request, viewing 60
certificates
chaining, about 69
commands
creating certificate 60
creating 61
CSA
importing 69
explained 52
importing 68
importing existing 67
self-signed
creating 62
troubleshooting 64
challenge type, explained 32
cipher suites
interactive mode, using 234
International Step-Up, working with 54
non-interactive mode, using 235
Server Gated Cryptography, working with 54
SGOS, supported by 53
client map, see SSL client
CONNECT method, using with origin-style
redirection 35
console account
minimum security 17
cookie surrogates, refresh time, discussed 30
COREid realm
Access Server
specifying 83
agents, configuring 82
Blue Coat appliance
challenges, avoiding 81
configuring 80
configuration overview 79
CPL, creating 86
creating 82
forward proxy, using with 81
general settings
configuring 84
general settings, specifying 84
SSO scheme, participating in 81
system, configuring 79
CPL
Admin layer, example 24
certificate realm, policies, creating 77
IWA realm policies, creating 107
LDAP realm examples 119
local realm, creating policies 129

Netegrity SiteMinder policies, creating 153
Novell SSO
policies, creating 172
policy substitution realm, policies, creating 140
RADIUS realm policies, creating 160
Windows SSO
policies, creating 190
credential refresh time
cached usernames, passwords 29
discussed 29
one-time passwords 29

D
database
creating through Blue Coat SG 126
local realm, setting up 123
viewing all users 127
default groups
policy used with 40
understanding 39
DER-format URLs, CRLs, using with 63
digital signing, overview 66
document
conventions 13

E
error message, HTTPS Console 64
event messages, BCAAA 225
explicit proxy
policy substitution realm, troubleshooting 179
external certificates, using with digital signing 66

F
forms-based authentication realm
CPL, using with 99
creating 96
creating, tips 94
creating/editing form 95
credentials sent in cleartext 100
customizing through Blue Coat SG 96
installing from local file 96
installing from remote URL 96
required values 91
storage options, setting 97, 98
substitutions for 93
tips/boundary conditions 100
understanding 90
front panel PIN
clearing 15

260

Index

creating 15

G
guest authentication
policy substitutions used with 39
policy used with 39
understanding 38

H
.htpasswd file
creating password realm database 125
loading 125
uploading 125
hashed passwords, using 16
header
policy substitution realm, using with 140
HTTP server
XML realms, configuring for 194
HTTPS Console
certificate error message 64
troubleshooting certificate problems 64
HTTPS termination
certificates 52
configuring 55
keyring, creating 56

I
Internet Explorer
troubleshooting for explicit policy substitution
realm 179
troubleshooting for transparent proxy 179
IP address surrogates, refresh time, discussed 30
IWA realm
authenticate.mode, setting 34
configuring authentication and authorization 101
defining realm server properties 101
Kerberos, enabling 103
overview 101
policies, creating 107
Service Principal Names, creating 223
single sign-on, configuring 107

K
Kerberos. See IWA
keyring
associating with certificate 68
importing 67
SSL client, associating 233

L
LDAP
policy-substitution realm, adding to 137
v2/v3 support 109
LDAP realm
authentication and authorization overview 109
authorization 114
case-sensitive configuration 111
certificate realm, adding to 74
CPL examples 119
defining Base DNs 113
defining realm authorization properties and
group information 114
defining realm server properties 110
defining server properties 111
group information 115
search boundaries 114
searching multiple base DNs 112
SSL, enabling 111
virtual URL, setting up 118
Lightweight Directory Access Protocol, see LDAP
local realm
authentication and authorization overview 121
certificate realm, adding to 74
changing properties 121
CPL, creating policies 129
creating a realm 121
database group, creating 126
database user, creating 126
database users, viewing 127
database, creating 123
database, creating through Blue Coat SG 126
database, populated 124
database, setting up 123
defining realm server properties 121
deleting groups 128
deleting users 128
groups, defined 124
groups, deleting 128
hashed passwords 124
policy substitution realm, adding to 137
user name, defined 124
users, deleting 128
view all lists 127
virtual URL, setting up 123
local user list
security settings, changing 128

261

Volume 4: Securing the Blue Coat SG Appliance

N
netbios
using with policy substitution realm 139
Netegrity SiteMinder realm
agents, configuring 146
case-sensitive configuration 147
creating 146
display name, changing 150
policies, creating 153
protected resource, entering 149
server mode, configuring 149
servers, configuring 147
servers, editing 148
SSO-only mode, enabling 149
Novell SSO realms
ADN, using with 141, 172, 190
authorization, using 164
BCAAA, configuring 165
creating a realm through CLI 166
defining realm server properties 165
general properties, configuring 169
policies, creating 172
sso.ini file, modifying 171
Novell SSO realms, ADN using with 141, 172, 190
NTLM realm. See IWA realm

O
one-time passwords
XML realms, configuring 195
Oracle, See COREid
origin-style authentication
origin 32
origin-cookie 32
origin-cookie-redirect 32
origin-ip 32
origin-ip-redirect 32

P
passwords
hashed, encrypted 16
security, understanding 16
PEM-encoded URLs, CRLs, using with 63
permitted errors, authentication
authentication failures 37
authorization failures 37
policy used with 37
policy
for maximum security 18
for moderate security 17

policy substitution realm
configuring 131
creating a realm through CLI 134
defining properties through Management
Console 134
defining realm server properties through
Management Console 134
full usernames, constructing 135
general properties, defining through CLI 139
general properties, defining through
Management Console 138
header, using with 140
how it works 131
LDAP authorization, adding 137
local authorization, adding 137
netbios, using with 139
policies, creating 140
troubleshooting 179
user, username fields, explained 132
usernames, constructing 135
policy substitution realms
ADN, using with 141, 172, 190
proxies
setting up 11

R
RADIUS realm
authentication and authorization overview 155
case-sensitive usernames, setting 157
defining realm server properties 156
policies, creating 160
troubleshooting 162
read-only access in Blue Coat SG 17
read-write access in Blue Coat SG 17
realm sequence
creating 176
promote/demote member realms 177
realms
certificate 73
COREid 79
forms-based authentication 90
IWA 101
LDAP 109
local 121
RADIUS 155
sequence 176
understanding 11
requestor. See XML realms
responder See XML realms

262

Index

S
security
console account 17
local user list settings, changing 128
policies for 17
sequence realm
defining realm server properties 176
sequences, troubleshooting 175
serial port
password, creating 16
Service Principal Names, creating for IWA realm 223
set_aut.pl script, using with .htpasswd file 125
setup console
password, creating 16
SiteMinder, see Netegrity SiteMinder realm
SOAP
XML realms, using with 193
SSH
password authentication 17
SSH with RSA authentication, not controlled by
policy 20
SSL
authentication/authorization services, using with
41
caching behavior, SSL client 233
cipher suites interactive mode, using 234
cipher suites non-interactive mode, using 235
LDAP realm, enabling 111
no-show keyring option 57
show keyring option 57
show-director option 57
timeout, configuring 237
SSL certificates, see certificates.
SSL client
keyring, associating 233
managing 233
sso.ini, modifying for Novell SSO realms 171
sso.ini, modifying for Windows SSO realm 188
surrogate credentials
defined 32
refresh time, discussed 30

T
timeout
configuring for SSL termination 237
transparent proxy
CLI commands 36
policy substitution realm, troubleshooting 179
transparent proxy authentication

configuring 35
setting options for 35, 36
troubleshooting
BCAAA service 225
CA Certificates 61
CONNECT method 35
forms-based authentication realm 100
HTTPS Console 64
RADIUS realm 162
TCP_DENIED 33

U
user data
policy, refreshing through 30
refreshing 28
users
administrator logout 28
credential refresh time, discussed 29
logged-in, viewing 26
logging in 26
logging out 27
logout conditions 28
logout properties 28
managing 26
policy logout 28
timeout 27
user data, refreshing 28

V
virtual URL
LDAP realm set up 118

W
Windows
configuring authorization 181
Windows SSO
authorization, configuring 185
authorization, using 183
BCAAA, configuring 184
BCAAA, works with 182
creating a realm through CLI 185
defining general properties through CLI 188
defining realm server properties 183
defining realm server properties through
Management Console 183
general properties, configuring 186
how it works 181
policies, creating 190
sso.ini file, modifying 188

263

Volume 4: Securing the Blue Coat SG Appliance

substitutions, available 186
Windows SSO realms
ADN, using with 141, 172, 190

X
XML realms
authorization, configuring 197
creating 194
HTTP server, configuring 194
one-time passwords, configuring 195
requestor, understanding 193
responder service, configuring 195

responder,
authentication/authorization,configuring 196
responder, creating 194
server, default values, changing 195
SOAP, using with 193
statistics, viewing 200
tasks before creating realm 194
understanding 193
user credential location, configuring 196
username parameters, configuring 196
XML realms, authorization, understanding 197

264

Document Path: ["164-blue-coat-instruction-proxysg.pdf"]

e-Highlighter

Click to send permalink to address bar, or right-click to copy permalink.

Un-highlight all Un-highlight selectionu Highlight selectionh