CUWebAuth for Apache and IIS
The following is a list of all of the directives supported by CUWebAuth. This reference covers the syntax details for each directive. For an introduction to configuring your server for CUWebAuth see either Configuring Apache or Configuring IIS . For examples of configuration files that support CUWebAuth, see this IIS sample configuration or this Apache sample configuration.
| Description: | Name of a security context |
|---|---|
| Syntax: | Authname
security-context
|
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
Required. Typically a CUWebAuth configuration uses a single security context called CORNELL. In some rare cases you may want to define a different context for a specific directory block. The reason to do this is to have CUWebAuth create a separate site cookie for the directory. The separate cookie will have different properties such as cookie timeout values and force options.
This directive is typically defined as follows:
<Directory "students">
AuthName CORNELL
AuthType all
Require valid-user
</Directory>
| Description: | Type of authentication to use. |
|---|---|
| Syntax: | AuthType all | all-force | all-forceonce | cuweblogin |
cuweblogin-force | cuweblogin-forceonce | inline |
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
Required. The AuthType directive is used to control the method or methods of authentication will be used to protect a resource.
For example, assume the location /test/ points to a directory that
contains only the single file here.html. Then requests for /test/here.html/more
and /test/nothere.html/more both collect /more as PATH_INFO.
The following table explains the different authentication methods supported by CUWebAuth...
|
Method
|
Description
|
|
all
|
Try SideCar authentication first, then CUWebLogin. |
|
all-force
|
Look for inline credentials first. If none are available, try SideCar authentication next. If SideCar isn't present then CUWebLogin is used. If credentials are established at the time of the request, destroy them first and force the user to re-enter their NetID and password. Note that the "force" doesn't apply to inline. |
|
all-forceonce
|
Same as all-force, except user is only forced to log in the first time they access the restricted page. As long as a session is established with your web site, the user can access the restricted page without logging in again. Note that the "forceonce" doesn't apply to inline. |
|
cuweblogin
|
Authenticate via CUWebLogin only |
|
cuweblogin-force
|
Authenticate via CUWebLogin only. If credentials are established at the time of the CUWebLogin request, destroy them first and force the user to re-enter their NetID and password. |
|
cuweblogin-forceonce
|
Same as cuweblogin-force, except user is only forced to log in the first time they access the restricted page. As long as a session is established with your web site, the user can access the restricted page without logging in again. |
|
inline
|
Authenticate inline only. CUWebAuth will only authenticate using the inline and inline proxy mechanism. This might be used in a situation where only mid-tier servers would have access to the resource. |
|
sidecar
|
Deprecated - Do Not Use! |
|
sidecar-force
|
Deprecated - Do Not Use! |
|
sidecar-forceonce
|
Deprecated - Do Not Use! |
The following example shows the most common use of the AuthType directive with CUWebAuth:
<Directory "students">
AuthName CORNELL
AuthType all
Require valid-user
</Directory>
| Description: | Set the location associated with the CUWebLogin cancel button. |
|---|---|
| Syntax: | CUWAaltUrl
uri
|
| Context: | directory, location, .htaccess |
| Platform: | Apache, IIS |
CUWAaltUrl http://welcome.cit.cornell.edu/
| Description: | Set the error code associated with an authentication failure. |
|---|---|
| Syntax: | CUWAautheFailHTTPCode
error-code
|
| Context: | server, virtual host, directory, location, .htaccess |
| Platform: | Apache only !! |
CUWAautheFailHTTPCode 401
| Description: | Set the error code associated with an authorization failure. |
|---|---|
| Syntax: | CUWAauthzFailHTTPCode
error-code
|
| Context: | server, virtual host, directory, location, .htaccess |
| Platform: | Apache only !! |
CUWAauthzFailHTTPCode 401
| Description: | Obsolete |
|---|
| Description: | Obsolete |
|---|
| Description: | Set the root domain shared by your web site and CUWebLogin. |
|---|---|
| Syntax: | CUWAcookieDomain
domain
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
Required for IIS, Optional for Apache. This directive is used to tell CUWebAuth what domain to assign in the outbound cookies that are used to communicate with the users’ web browsers. This must match the root domain of the DNS identity for your server, otherwise the cookie will usually be rejected by web browsers.
NOTE: CUWebLogin does not support authentication domains other than cornell.edu.
NOTE: in Apache by default, the domain value is "cornell.edu", which is the only correct value for the Cornell campus. IIS users should include the following line in their configuration file:
CUWAcookieDomain cornell.edu
| Description: | Set the lifetime for a session on your site |
|---|---|
| Syntax: | CUWAcookieTimeout
minutes
|
| Context: | directory, location, .htaccess |
| Platform: | Apache, IIS |
CUWAcookieTimeout 480
| Description: | Obsolete |
|---|
| Description: | Control the amount of debugging output produced |
|---|---|
| Syntax: | CUWAcusspDebug
level
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
CUWAcusspDebug 1
| Description: | Set location for CUSSP debug log |
|---|---|
| Syntax: | CUWAcusspDebugDir
path
|
| Context: | server, virtual host |
| Platform: | Apache Only !! For IIS see CUWAcussplogFile |
CUWAcusspDebugDir /tmp/cussp
| Description: | Set location and name for CUSSP debug log |
|---|---|
| Syntax: | CUWAcussplogFile
path-and-file-name
|
| Context: | server, virtual host |
| Platform: | IIS Only !! For Apache see CUWAcusspDebugDir |
CUWAcussplogFile C:\WINNT\CUWebAuth\CUSSPLog.txt
| Description: | Set the timeout for back-end communications |
|---|---|
| Syntax: | CUWAcusspTimeout
seconds
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
CUWAcusspTimeout 5
| Description: | Display a custom message on the login page |
|---|---|
| Syntax: | CUWAcustMsg
message
|
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
CUWAcustMsg "In order to view your course schedule you must first login
with your NetID and Password."
| Description: | Specify location of CUWebLogin servers |
|---|---|
| Syntax: | CUWAcuwlServerSRL
service-resource-location
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
# Apache version
CUWAcuwlServerSRL "ipHost=cuweblogin.cit.cornell.edu
ipPort=1010 a.netid=erpcd.webster a.protocol=k4"
CUWAcuwlServerSRL "ipHost=cuweblogin2.cit.cornell.edu ipPort=1010
a.netid=erpcd.webster2 a.protocol=k4"
# IIS version
CUWAcuwlServerSRL ipHost=cuweblogin.cit.cornell.edu
ipPort=1010 netid=erpcd.webster authent=k4
CUWAcuwlServerSRL ipHost=cuweblogin2.cit.cornell.edu
ipPort=1010 netid=erpcd.webster2 authent=k4
| Description: | Set the directory to store the debug log |
|---|---|
| Syntax: | CUWAdebugDir
directory-path
|
| Context: | server, virtual host |
| Platform: | Apache Only !! |
CUWAdebugDir /tmp/logs
| Description: | Control the amount of diagnostic output |
|---|---|
| Syntax: | CUWAdebugLevel off | normal | debug | prolific | cussp |
| Context: | server, virtual host |
| Platform: | IIS Only !! For Apache see LogLevel |
CUWAdebugLevel cussp
| Description: | Obsolete, see CUWAcookieDomain |
|---|
| Description: | Specify an error page |
|---|---|
| Syntax: | CUWAErrorDoc NoSideCar | SideCarError | CUWebLoginError | NoAuth
error-document-path
|
| Context: | location, directory, .htaccess |
| Platform: | IIS Only !! |
CUWAErrorDoc NoSideCar C:\WINNT\CUWebAuth\nosidecar.html
| Description: | Set the correct port number for redirects |
|---|---|
| Syntax: | CUWAforcePort
port_number
|
| Context: | location, directory, .htaccess |
| Platform: | Apache Only !! |
CUWAforcePort 443
| Description: | Insure that redirects use https instead of http |
|---|---|
| Syntax: | CUWAforceSSL on | off |
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
CUWAforceSSL on
| Description: | Set maximum idle time for site cookie |
|---|---|
| Syntax: | CUWAinactivityTimeout
minutes
|
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
CUWAinactivityTimeout 5
| Description: | Set the name of your ServiceID |
|---|---|
| Syntax: | CUWAkerberosPrincipal
name
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
CUWAkerberosPrincipal mandarin-agent.test
| Description: | Set the name and path of the log file |
|---|---|
| Syntax: | CUWAlogFile
log-file-path
|
| Context: | server, virtual host |
| Platform: | IIS Only !! |
CUWAlogFile c:\logs\cuwa.log
| Description: | Set the error code for SideCar unavailable condition |
|---|---|
| Syntax: | CUWAnoSideCarHTTPCode
error-code
|
| Context: | server, virtual host, location, directory, .htaccess |
| Platform: | Apache Only !! |
CUWAnoSideCarHTTPCode 401
| Description: | Specify location of permit server |
|---|---|
| Syntax: | CUWApermitServerSRL
service-resource-location
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
# Apache version
# IIS version
CUWApermitServerSRL ipHost=permit1.cit.cornell.edu
ipPort=756 netid=permitd.permit1 authent=k4
| Description: | Control the amount of POST data that can be sent. |
|---|---|
| Syntax: | CUWAPostDataLimit
number-of-bytes
|
| Context: | server |
| Platform: | IIS, POST data aware version only !! |
CUWAPostDataLimit 10000
| Description: | Name of a security context |
|---|---|
| Syntax: | CUWApriorityLevel high | medium | low |
| Context: | server |
| Platform: | IIS Only !! |
CUWApriorityLevel high
| Description: | Enable proxy and inline authentication |
|---|---|
| Syntax: | CUWAproxyAllow [direct]
[ServiceID ...]
|
| Context: | location, directory, .htaccess |
| Override: | AuthConfig |
| Platform: | Apache, IIS |
CUWAproxyAllow web-agent.trusted
CUWAproxyAllow web-agent.trusted web-agent.trusted2
CUWAproxyAllow direct
| Description: | Set the error code associated with a SideCar error |
|---|---|
| Syntax: | CUWAsideCarErrHTTPCode
error-code
|
| Context: | server, virtual host, location, directory, .htaccess |
| Platform: | Apache Only !! |
CUWAnoSideCarHTTPCode 401
| Description: | Set the number of time to try to connect to SideCar |
|---|---|
| Syntax: | CUWAsideCarRetryCount
count
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
CUWAsideCarRetryCount 2
| Description: | Set the path and filename for the srvtab file |
|---|---|
| Syntax: | CUWAsrvtabPath
file-path
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
CUWAsrvtabPath /etc/mandarin-agent.srvtab
| Description: | Set the session lifetime |
|---|---|
| Syntax: | CUWAsslCookieTimeout
minutes
|
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
CUWAsslCookieTimeout 30
| Description: | Name of a security context |
|---|---|
| Syntax: | CUWAstatSize solaris_sparc | solaris_intel | aix |
size
|
| Context: | server |
| Platform: | Apache Only !! |
CUWAstatSize solaris_sparc
CUWAstatSize aix
CUWAstatSize solaris_intel
| Description: | Show CUWebAuth error page |
|---|---|
| Syntax: | CUWAshowError on |
| Context: | location, directory, .htaccess |
| Platform: | Apache only !! |
CUWAshowError on
| Description: | Set the retry count for connecting to CUWebLogin |
|---|---|
| Syntax: | CUWAwebloginRetryCount
count
|
| Context: | server, virtual host |
| Platform: | Apache, IIS |
CUWAwebloginRetryCount 4
| Description: | List the ports that are SSL enabled |
|---|---|
| Syntax: | CUWAwebSSLPorts
port-number [port-number port-number...]
|
| Context: | server, virtual host |
| Platform: | Apache Only !! |
CUWAwebSSLPorts 443 444
| Description: | Set the amount of error logging that occurs |
|---|---|
| Syntax: | LogLevel
logging-level
|
| Context: | server, virtual host |
| Platform: | Apache Only !! |
This directive is used by Apache to set overall logging level for the entire server or virtual host. For CUWebAuth, the only value that will produce meaningful diagnostic output is the following...
LogLevel debug
Under normal operation you won't want to set LogLevel to debug because it produces a large error_log file. When diagnosing a CUWebAuth related problem though, set LogLevel to debug. If you are requesting assistance from aadssupport@cornell.edu, you will need to collect a diagnostic log and send it to us.
For a more detailed description of LogLevel see the official Apache description here.
| Description: | Define the authorization rules for the resource |
|---|---|
| Syntax: | Require valid-user
|
Permit
permit-name
[...] | Netid
NetID
[...] |
| Context: | location, directory, .htaccess |
| Platform: | Apache, IIS |
Required. Specifies what authorization rule applies to the current Directory, File or Location block. Valid authorization specifications appear below:
|
Specification
|
Description
|
|
valid-user
|
Access is granted when the user authenticates. You should avoid using this because it grants access to everyone who has a NetID. This includes students, staff, faculty, alumni, contractors, and others with loose affiliation to the university. |
|
Permit
|
Followed by a space-separated list of permit names, access is granted if the user holds any one of the specified permits. |
|
Netid
|
Followed by a space-separated list of NetIDs, access is granted if the user’s NetID matches one of the NetIDs on the list. |
Require valid-user
Require Permit cu.staff cu.student
Require Netid pb10 se10 hy93 ss488