This is used to define parameters for the various authentication
schemes supported by Squid.
- format: auth_param scheme parameter [setting]
+ format: auth_param scheme parameter [setting]
The order in which authentication schemes are presented to the client is
dependent on the order the scheme first appears in config file. IE
=== Parameters common to all schemes. ===
"program" cmdline
- Specifies the command for the external authenticator. Such a program
- runs a loop that, on every iteration, reads a request line from
- the standard and responds with a scheme-specific answer. The loop
- stops when all input is exchausted (EOF). See scheme-specific
- "program" descriptions below for details.
+ Specifies the command for the external authenticator.
- "key_extras" format
- Specifies a string to be append to request line format for the
- authentication helper. "Quoted" format values may contain spaces and
- logformat %macros. In theory, any logformat %macro can be used.
- In practice, a %macro expands as a dash (-) if the helper request is
- sent before the required macro information is available to Squid.
- By default, Squid uses request formats provided in scheme-specific
- examples below (search for %credentials).
- The expanded key_extras value is added to the Squid credentials
- cache and, hence, will affect authentication. It can be used to
- autenticate different users with identical user names (e.g., when user
- authentication depends on http_port).
- Avoid adding frequently changing information to key_extras. For
- example, if you add user source IP, and it changes frequently
- in your environment, then max_user_ip ACL is going to treat every
- user+IP combination as a unique "user", breaking the ACL and
- wasting a lot of memory on those user records. It will also force
- users to authenticate from scratch whenever their IP changes.
-
- === Parameters for the basic scheme follow. ===
+ By default, each authentication scheme is not used unless a
+ program is specified.
- "program" cmdline
- Specify the command for the external authenticator. Such a program
- reads a request line ("username password" by default) and replies
- with one of three results:
+ See http://wiki.squid-cache.org/Features/AddonHelpers for
+ more details on helper operations and creating your own.
- OK
- the user exists.
+ "key_extras" format
+ Specifies a string to be append to request line format for
+ the authentication helper. "Quoted" format values may contain
+ spaces and logformat %macros. In theory, any logformat %macro
+ can be used. In practice, a %macro expands as a dash (-) if
+ the helper request is sent before the required macro
+ information is available to Squid.
+
+ By default, Squid uses request formats provided in
+ scheme-specific examples below (search for %credentials).
+
+ The expanded key_extras value is added to the Squid credentials
+ cache and, hence, will affect authentication. It can be used to
+ autenticate different users with identical user names (e.g.,
+ when user authentication depends on http_port).
+
+ Avoid adding frequently changing information to key_extras. For
+ example, if you add user source IP, and it changes frequently
+ in your environment, then max_user_ip ACL is going to treat
+ every user+IP combination as a unique "user", breaking the ACL
+ and wasting a lot of memory on those user records. It will also
+ force users to authenticate from scratch whenever their IP
+ changes.
+
+ "realm" string
+ Specifies the protection scope (aka realm name) which is to be
+ reported to the client for the authentication scheme. It is
+ commonly part of the text the user will see when prompted for
+ their username and password.
+
+ For Basic the default is "Squid proxy-caching web server".
+ For Digest there is no default, this parameter is mandatory.
+ For NTLM and Negotiate this parameter is ignored.
- ERR
- the user does not exist.
+ "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
- BH
- An internal error occurred in the helper, preventing
- a result being identified.
+ The maximum number of authenticator processes to spawn. If
+ you start too few Squid will have to wait for them to process
+ a backlog of credential verifications, slowing it down. When
+ password verifications are done via a (slow) network you are
+ likely to need lots of authenticator processes.
- "ERR" and "BH" results may optionally be followed by message="..."
- containing a description available as %m in the returned error page.
+ The startup= and idle= options permit some skew in the exact
+ amount run. A minimum of startup=N will begin during startup
+ and reconfigure. Squid will start more in groups of up to
+ idle=N in an attempt to meet traffic needs and to keep idle=N
+ free above those traffic needs up to the maximum.
- If you use an authenticator, make sure you have 1 acl of type
- proxy_auth.
+ The concurrency= option sets the number of concurrent requests
+ the helper can process. The default of 0 is used for helpers
+ who only supports one request at a time. Setting this to a
+ number greater than 0 changes the protocol used to include a
+ channel ID field first on the request/response line, allowing
+ multiple requests to be sent to the same helper in parallel
+ without waiting for the response.
- By default, the basic authentication scheme is not used unless a
- program is specified.
+ Concurrency must not be set unless it's known the helper
+ supports the input format with channel-ID fields.
- If you want to use the traditional NCSA proxy authentication, set
- this line to something like
+ NOTE: NTLM and Negotiate schemes do not support concurrency
+ in the Squid code module even though some helpers can.
- auth_param basic program @DEFAULT_PREFIX@/libexec/basic_ncsa_auth @DEFAULT_PREFIX@/etc/passwd
- "utf8" on|off
- HTTP uses iso-latin-1 as character set, while some authentication
- backends such as LDAP expects UTF-8. If this is set to on Squid will
- translate the HTTP iso-latin-1 charset to UTF-8 before sending the
- username & password to the helper.
+IF HAVE_AUTH_MODULE_BASIC
+ === Basic authentication parameters ===
- "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
- The maximum number of authenticator processes to spawn. If you start too few
- Squid will have to wait for them to process a backlog of credential
- verifications, slowing it down. When password verifications are
- done via a (slow) network you are likely to need lots of
- authenticator processes.
-
- The startup= and idle= options permit some skew in the exact amount
- run. A minimum of startup=N will begin during startup and reconfigure.
- Squid will start more in groups of up to idle=N in an attempt to meet
- traffic needs and to keep idle=N free above those traffic needs up to
- the maximum.
-
- The concurrency= option sets the number of concurrent requests the
- helper can process. The default of 0 is used for helpers who only
- supports one request at a time. Setting this to a number greater than
- 0 changes the protocol used to include a channel number first on the
- request/response line, allowing multiple requests to be sent to the
- same helper in parallel without waiting for the response.
- Must not be set unless it's known the helper supports this.
-
- auth_param basic children 20 startup=0 idle=1
-
- "realm" realmstring
- Specifies the realm name which is to be reported to the
- client for the basic proxy authentication scheme (part of
- the text the user will see when prompted their username and
- password). There is no default.
- auth_param basic realm Squid proxy-caching web server
+ "utf8" on|off
+ HTTP uses iso-latin-1 as character set, while some
+ authentication backends such as LDAP expects UTF-8. If this is
+ set to on Squid will translate the HTTP iso-latin-1 charset to
+ UTF-8 before sending the username and password to the helper.
"credentialsttl" timetolive
- Specifies how long squid assumes an externally validated
- username:password pair is valid for - in other words how
- often the helper program is called for that user. Set this
- low to force revalidation with short lived passwords. Note
- setting this high does not impact your susceptibility
- to replay attacks unless you are using an one-time password
- system (such as SecureID). If you are using such a system,
- you will be vulnerable to replay attacks unless you also
- use the max_user_ip ACL in an http_access rule.
-
- "casesensitive" on|off
- Specifies if usernames are case sensitive. Most user databases are
- case insensitive allowing the same username to be spelled using both
- lower and upper case letters, but some are case sensitive. This
- makes a big difference for user_max_ip ACL processing and similar.
- auth_param basic casesensitive off
-
- === Parameters for the digest scheme follow ===
-
- "program" cmdline
- Specify the command for the external authenticator. Such a program
- reads a request_format line ("username":"realm" by default) and
- replies with one of three results:
+ Specifies how long squid assumes an externally validated
+ username:password pair is valid for - in other words how
+ often the helper program is called for that user. Set this
+ low to force revalidation with short lived passwords.
- OK ha1="..."
- the user exists. The ha1= key is mandatory and
- contains the appropriate H(A1) value, hex encoded.
- See rfc 2616 for the definition of H(A1).
-
- ERR
- the user does not exist.
-
- BH
- An internal error occurred in the helper, preventing
- a result being identified.
+ NOTE: setting this high does not impact your susceptibility
+ to replay attacks unless you are using an one-time password
+ system (such as SecureID). If you are using such a system,
+ you will be vulnerable to replay attacks unless you also
+ use the max_user_ip ACL in an http_access rule.
- "ERR" and "BH" results may optionally be followed by message="..."
- containing a description available as %m in the returned error page.
-
- By default, the digest authentication scheme is not used unless a
- program is specified.
-
- If you want to use a digest authenticator, set this line to
- something like
+ "casesensitive" on|off
+ Specifies if usernames are case sensitive. Most user databases
+ are case insensitive allowing the same username to be spelled
+ using both lower and upper case letters, but some are case
+ sensitive. This makes a big difference for user_max_ip ACL
+ processing and similar.
- auth_param digest program @DEFAULT_PREFIX@/bin/digest_pw_auth @DEFAULT_PREFIX@/etc/digpass
+ENDIF
+IF HAVE_AUTH_MODULE_DIGEST
+ === Digest authentication parameters ===
"utf8" on|off
- HTTP uses iso-latin-1 as character set, while some authentication
- backends such as LDAP expects UTF-8. If this is set to on Squid will
- translate the HTTP iso-latin-1 charset to UTF-8 before sending the
- username & password to the helper.
-
- "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
- The maximum number of authenticator processes to spawn (default 5).
- If you start too few Squid will have to wait for them to
- process a backlog of H(A1) calculations, slowing it down.
- When the H(A1) calculations are done via a (slow) network
- you are likely to need lots of authenticator processes.
-
- The startup= and idle= options permit some skew in the exact amount
- run. A minimum of startup=N will begin during startup and reconfigure.
- Squid will start more in groups of up to idle=N in an attempt to meet
- traffic needs and to keep idle=N free above those traffic needs up to
- the maximum.
-
- The concurrency= option sets the number of concurrent requests the
- helper can process. The default of 0 is used for helpers who only
- supports one request at a time. Setting this to a number greater than
- 0 changes the protocol used to include a channel number first on the
- request/response line, allowing multiple requests to be sent to the
- same helper in parallel without waiting for the response.
- Must not be set unless it's known the helper supports this.
-
- auth_param digest children 20 startup=0 idle=1
-
- "realm" realmstring
- Specifies the realm name which is to be reported to the
- client for the digest proxy authentication scheme (part of
- the text the user will see when prompted their username and
- password). There is no default.
- auth_param digest realm Squid proxy-caching web server
+ HTTP uses iso-latin-1 as character set, while some
+ authentication backends such as LDAP expects UTF-8. If this is
+ set to on Squid will translate the HTTP iso-latin-1 charset to
+ UTF-8 before sending the username and password to the helper.
"nonce_garbage_interval" timeinterval
- Specifies the interval that nonces that have been issued
- to client_agent's are checked for validity.
+ Specifies the interval that nonces that have been issued
+ to client_agent's are checked for validity.
"nonce_max_duration" timeinterval
- Specifies the maximum length of time a given nonce will be
- valid for.
+ Specifies the maximum length of time a given nonce will be
+ valid for.
"nonce_max_count" number
- Specifies the maximum number of times a given nonce can be
- used.
+ Specifies the maximum number of times a given nonce can be
+ used.
"nonce_strictness" on|off
- Determines if squid requires strict increment-by-1 behavior
- for nonce counts, or just incrementing (off - for use when
- user agents generate nonce counts that occasionally miss 1
- (ie, 1,2,4,6)). Default off.
+ Determines if squid requires strict increment-by-1 behavior
+ for nonce counts, or just incrementing (off - for use when
+ user agents generate nonce counts that occasionally miss 1
+ (ie, 1,2,4,6)). Default off.
"check_nonce_count" on|off
- This directive if set to off can disable the nonce count check
- completely to work around buggy digest qop implementations in
- certain mainstream browser versions. Default on to check the
- nonce count to protect from authentication replay attacks.
+ This directive if set to off can disable the nonce count check
+ completely to work around buggy digest qop implementations in
+ certain mainstream browser versions. Default on to check the
+ nonce count to protect from authentication replay attacks.
"post_workaround" on|off
- This is a workaround to certain buggy browsers who sends
- an incorrect request digest in POST requests when reusing
- the same nonce as acquired earlier on a GET request.
+ This is a workaround to certain buggy browsers who send an
+ incorrect request digest in POST requests when reusing the
+ same nonce as acquired earlier on a GET request.
- === NTLM scheme options follow ===
-
- "program" cmdline
- Specify the command for the external NTLM authenticator.
- Such a program reads exchanged NTLMSSP packets with
- the browser via Squid until authentication is completed.
- If you use an NTLM authenticator, make sure you have 1 acl
- of type proxy_auth. By default, the NTLM authenticator program
- is not used.
-
- auth_param ntlm program /usr/bin/ntlm_auth
-
- "children" numberofchildren [startup=N] [idle=N]
- The maximum number of authenticator processes to spawn (default 5).
- If you start too few Squid will have to wait for them to
- process a backlog of credential verifications, slowing it
- down. When credential verifications are done via a (slow)
- network you are likely to need lots of authenticator
- processes.
-
- The startup= and idle= options permit some skew in the exact amount
- run. A minimum of startup=N will begin during startup and reconfigure.
- Squid will start more in groups of up to idle=N in an attempt to meet
- traffic needs and to keep idle=N free above those traffic needs up to
- the maximum.
-
- auth_param ntlm children 20 startup=0 idle=1
+ENDIF
+IF HAVE_AUTH_MODULE_NEGOTIATE
+ === Negotiate authentication parameters ===
"keep_alive" on|off
- If you experience problems with PUT/POST requests when using the
- Negotiate authentication scheme then you can try setting this to
- off. This will cause Squid to forcibly close the connection on
- the initial requests where the browser asks which schemes are
- supported by the proxy.
+ If you experience problems with PUT/POST requests when using
+ the this authentication scheme then you can try setting this
+ to off. This will cause Squid to forcibly close the connection
+ on the initial request where the browser asks which schemes
+ are supported by the proxy.
- auth_param ntlm keep_alive on
-
- === Options for configuring the NEGOTIATE auth-scheme follow ===
-
- "program" cmdline
- Specify the command for the external Negotiate authenticator.
- This protocol is used in Microsoft Active-Directory enabled setups with
- the Microsoft Internet Explorer or Mozilla Firefox browsers.
- Its main purpose is to exchange credentials with the Squid proxy
- using the Kerberos mechanisms.
- If you use a Negotiate authenticator, make sure you have at least
- one acl of type proxy_auth active. By default, the negotiate
- authenticator program is not used.
- The only supported program for this role is the ntlm_auth
- program distributed as part of Samba, version 4 or later.
-
- auth_param negotiate program /usr/bin/ntlm_auth --helper-protocol=gss-spnego
-
- "children" numberofchildren [startup=N] [idle=N]
- The maximum number of authenticator processes to spawn (default 5).
- If you start too few Squid will have to wait for them to
- process a backlog of credential verifications, slowing it
- down. When credential verifications are done via a (slow)
- network you are likely to need lots of authenticator
- processes.
-
- The startup= and idle= options permit some skew in the exact amount
- run. A minimum of startup=N will begin during startup and reconfigure.
- Squid will start more in groups of up to idle=N in an attempt to meet
- traffic needs and to keep idle=N free above those traffic needs up to
- the maximum.
-
- auth_param negotiate children 20 startup=0 idle=1
+ENDIF
+IF HAVE_AUTH_MODULE_NTLM
+ === NTLM authentication parameters ===
"keep_alive" on|off
- If you experience problems with PUT/POST requests when using the
- Negotiate authentication scheme then you can try setting this to
- off. This will cause Squid to forcibly close the connection on
- the initial requests where the browser asks which schemes are
- supported by the proxy.
+ If you experience problems with PUT/POST requests when using
+ the this authentication scheme then you can try setting this
+ to off. This will cause Squid to forcibly close the connection
+ on the initial request where the browser asks which schemes
+ are supported by the proxy.
+ENDIF
- auth_param negotiate keep_alive on
-
- Examples:
+ === Example Configuration ===
+
+ This configuration displays the recommended authentication scheme
+ order from most to least secure with recommended minimum configuration
+ settings for each scheme:
-#Recommended minimum configuration per scheme:
#auth_param negotiate program <uncomment and complete this line to activate>
#auth_param negotiate children 20 startup=0 idle=1
#auth_param negotiate keep_alive on
#
-#auth_param ntlm program <uncomment and complete this line to activate>
-#auth_param ntlm children 20 startup=0 idle=1
-#auth_param ntlm keep_alive on
-#
-#auth_param digest program <uncomment and complete this line>
+#auth_param digest program <uncomment and complete this line to activate>
#auth_param digest children 20 startup=0 idle=1
#auth_param digest realm Squid proxy-caching web server
#auth_param digest nonce_garbage_interval 5 minutes
#auth_param digest nonce_max_duration 30 minutes
#auth_param digest nonce_max_count 50
#
+#auth_param ntlm program <uncomment and complete this line to activate>
+#auth_param ntlm children 20 startup=0 idle=1
+#auth_param ntlm keep_alive on
+#
#auth_param basic program <uncomment and complete this line>
#auth_param basic children 5 startup=5 idle=1
#auth_param basic realm Squid proxy-caching web server
projects / thirdparty / squid.git / commitdiff
