authenticate

NAME
SYNOPSIS
DESCRIPTION
GENERAL NOTES
KERBEROS NOTES
KERBEROS, AD™ AND FIREWALL
LIMITATIONS
SEE ALSO
AUTHOR
COPYRIGHT

NAME

authenticate - Manage the authentication module

SYNOPSIS

authenticate [(web | web) [on | off]]

authenticate [mode [(ldap | kerberos) [on | off]]]

authenticate [ldap [request [’<user-base-dn>’ ’<login-attr>’ [’<passwd-attr>’ [’<ldap-filter>’ [’<group-base-dn>’ ’<group-name>’]]]]]]

authenticate [ldap server [(raz | (add | del) (ldap | ldaps | sldap) <name> <ip> [<port>])]]

authenticate [ldap [binddn [(set | raz) ’<base-dn>’ [<password>]]]]

authenticate [ldap [certificate [(show | raz | load (ftp | sftp | tftp) <file-server> <cert-file-name>)]]]

authenticate [ldap [test [<login-name> [<password>]]]]

authenticate [kerberos [(encrypt [(des | aes)]) | (web <canonical-name>) | (hapassword <shared-password>)]]

authenticate [kerberos [server [(raz | (add | del) <kerberos-server>)]]]

authenticate [kerberos [rweb [add <canonical-name> <site-name> | del <canonical-name> | raz]]]

authenticate [kerberos [(create <admin-user>) | report]]

authenticate [ad [rdn [<host-relative-dn>]]]

DESCRIPTION

This command is used to configure the authentication module. The authentication module allows restricting the Web (or rWeb) usage to authenticated users only.

The first usage form allows you to define target authenticated users. The keyword rweb specifies users accessing reverse websites (see the command rweb) and the keyword web specifies forwarding users accessing all other websites (on the Internet). Forwarding users are located behind the appliance while end-uses of reverse websites can be located in front of the appliance (coming form the Internet) as well as behind the appliance. Keywords on and off allows respectively to activate or deactivate the authentication for a target.

The second usage form allows setting the authentication mode. The current system version supports the LDAP and Kerberos authentication modes.

Usage forms from the third to sixth allow you to configure LDAP authentication. To configure LDAP authentication, use the keyword ldap followed by the appropriate argument.

The third usage form allows you to set the LDAP request. To set LDAP request use the keyword request. The first argument is the base DN (Distinguished Name) under which the users are located. The second and third arguments are respectively the attribute names that contain the user login and password. The fourth argument is the LDAP search filter to locate a user in the hierarchy below the base DN. The fifth and sixth arguments are optional. If given, the authentication module verifies that the identified user is a member of the given group. In this case the fifth argument specifies the group base DN (Distinguished Name) under which the group is located and the sixth argument is the group canonical name (stored in the cn attribute). Note that the LDAP group should be an object of the normalized class groupOfNames in which all members are distinguished names stored in the attribute member.

Please note that as LDAP distinguished names and filters contains the character ’=’ they must be enclosed in quotation marks to avoid being interpreted by the shell.

For instance consider the following command:

authenticate ldap request ’ou=people,dc=example,dc=com’ ’uid’ ’userPassword’ ’objectClass=inetOrgPerson’ ’ou=groups,dc=example,dc=com’ ’webUsers’.

This command allows authenticating users of class inetOrgPerson, registered under the object ou=people,dc=example,dc=com, identified by the LDAP attributes uid and for which passwords are stored in the userPassword attribute. In addition only users that belong to the group named webGroup which is registered under the top object ou=groups,dc=example,dc=com are allowed.

An empty value (’’) may be used for <passwd-attr> and <ldap-filter>. If an empty value (’’) is specified for <passwd-attr> the LDAP binding is used during the basic authentication phase instead of comparing the entered password to <passwd-attr> (this is the preferred method used by Microsoft AD (Active Directory)™. Please note that the login attribute in AD™ is sAMAccountName.

Note that there is a limitation in specifying a password attribute: When the waf mode is activated or the antivirus and compress modes are both activated, the given password attribute is ignored and the LDAP binding is used instead.

The fourth usage form allows managing LDAP servers. To add an LDAP server, use the keyword add followed by the LDAP protocol type, the LDAP server network name, its IP address and the port number.

Allowed LDAP protocol types are: ldap, ldaps and sldap. The protocol type ldap stands for the clear (without encryption) LDAP protocol while ldaps and sldap are used for SSL/TLS encrypted LDAP protocols. To specify LDAP over SSL/TLS use the type ldaps. To specify SSL/TLS encryption within LDAP, use the type sldap. Note that the sldap type cannot be mixed with other types. That means if the LDAP servers list contains an sldap server, all other LDAP servers must be sldap servers.

If no port number is specified, standard port numbers are used (389 for ldap/sldap and 636 for ldaps).

To delete an LDAP server replace the keyword add by the keyword del in the latter syntax. To erase all LDAP servers use the keyword raz.

When binding to the LDAP server itself requires authentication, the authenticating couple "user/password" should be specified. The fifth usage form allows you to set up the DN (Distinguished Name) of that authenticated user (usually the administrator of the LDAP server). To do so, use the keyword binddn followed by the keyword set and the DN of that user. When a binddn is configured here, the associated password should also be configured here or using the command password. If no authentication is required, just erase the binddn using the keyword raz. Note that the LDAP password is reset when the binddn is erased.

The sixth usage form allows managing the X.509 CA (Certificate Authority) for LDAP servers of type ldaps or sldap. If a CA is set, the LDAP server’s certificate transmitted by the the LDAP server during the SSL/TLS initialisation phase is verified against that CA signature correctness. In case of error LDAP authentication requests are rejected.

To load a Base64 (PEM) encoded CA file, use the keyword certificate followed by the keyword load, the file server protocol name (ftp, sftp, or tftp), the file server name or IP address and the CA file name on that file server. Only trusted file servers are allowed. Trusted file servers are defined with the command access. To show the content of a previously loaded certificate use the keyword show.

The seventh usage form allows you to test the authentication against configured LDAP servers. Please note that as with any other commands the new configuration should be applied using the command apply before being able to test the authentication.

Usage forms from eighth to twelfth allow you to configure the Kerberos authentication against an AD™ server. The keyword encrypt allows you to set the encryption type to use during authentication negotiations. Allowed encryption types are des and aes. The keyword web allows you to set the name by which the appliance system is identified as a Web proxy. This should typically be the name that you use to set Web proxies at client (Web browsers) sides. Please note that a canonical short name should be specified here (proxy for instance). See below the definition of a valid canonical name.

In an HA configuration (with two or more redundant nodes) in order to allow the service continuity (in case of a failure on a node), all nodes should use the same service name and share the same account password on Kerberos servers. In this case the used password should never expire or change (if you modify the account password on an HA node, think about modifying it on all other HA nodes). The keyword hapassword allows you to set the shared account password. Refer to the commands ha and vrrp to get help on how to configure the HA mode.

Please note that in a non HA configuration (with a stand alone node), the hapassword is not used as the system generates a random password and automatically changes it whenever it get older than 21 days.

To enable the Kerberos authentication mode, at least one Kerberos server should be specified (preferably two). Kerberos servers can be specified by giving their DNS names or IP addresses. Please note that Kerberos servers specified here can also act as an AD™ domain controller. In order to allow the AD™ servers to identify the present system, its DN should be specifiend here. The authenticate ad rdn usage form allows you to specify the RDN (Relative Distinguished Name) of the present system in the AD™ LDAP directory tree. The FDN (Full Distinguish Name) is then deduced from the host and domain name of your system. For instance if your host and domain names are respectively proxy and example.com, by specifying ’cn=computers’ as the RDN, the FDN will be cn=proxy,cn=computers,dc=example,dc=com.

The Kerberos authentication can also be activated for users of reverse websites provided that users to authenticate depend on the same Kerberos servers as the reverse proxy (rweb module). The Kerberos authentication is not activated for all reverse websites but only for reverse websites that are associated to a canonical name (short hostname). To associate a canonical name to a reverse website use the keywords authenticate kerberos rweb add followed by a valid canonical name and the name of the reverse website. See below the definition of a valid canonical name. Please note that canonical names should be unique and a reverse website can’t be associated to more than one canonical name. To deactivate the Kerberos authentication for a reverse website use the keywords authenticate kerberos rweb del followed by its canonical name. To deactivate the Kerberos authentication for all reverse websites use the keywords authenticate kerberos rweb raz.

It is important to note that the first time the Kerberos authentication mode is activated (after the apply operation), the Kerberos authentication should be initialized. During the initialization process all LDAP objects associated to services provided by the proxy (HTTP/proxy.example.com in the example above) and the reverse proxy are created in AD™. Also the initialization process allows your system to obtain a Kerberos tickets. To this end, it is necessary to use an AD™ account with administrator permissions (user administrator for instance). The authenticate kerberos create <admin-user> usage form allows you to initialize the Kerberos authentication. This command requires that you interactively enter the password associated to the used administrator account. The given password here is not permanently saved and is removed after having obtained a Kerberos ticket. Please note that the Kerberos initialization is an asynchronous operation and is executed in background. The report keyword allows you to display a report of the last Kerberos initialization operation.

GENERAL NOTES

Because an LDAP filter or a distinguished name contains the equal character, it should be quoted with simple or double quotes. Otherwise the shell interpreter considers that as a variable setting.

KERBEROS NOTES

Since the security of Kerberos authentication is in part based upon the time stamps of tickets, it is critical to have accurately set clocks on Kerberos servers and the present system. For this doing, the usage of NTP servers is highly recommended (see the command ntp).

Regarding the Kerberos encryption type, if your AD is running on a Windows™ server 2003 you should use the DES encryption type. For Windows™ server 2008 and above the AES encryption type should be used (DES is an acronym of Data Encryption Standard while AES stands for Advanced Encryption Standard).

A canonical name is a string beginning with an alphanumeric character with a maximum length of 14 characters and containing a combination of alphanumeric and the dash ("-") characters. A canonical name should contain at least one alphabetic character and can’t begin or end with the dash character.

KERBEROS, AD™ AND FIREWALL

• If your appliance is placed behind a third party firewall, you should allow the following traffic in order to allow the kerberos authentication against AD™ servers:

• Kerberos traffic (TCP 88) form the appliance to the Kerberos servers (AD™).

• Kerberos password traffic (UDP 464) form the appliance to Kerberos servers (AD™).

• LDAP traffic (TCP 389) form the appliance to the AD™ servers.

LIMITATIONS

The authentication is not supported in transparent mode.

SEE ALSO

access (1) clock (1) domainname (1) ha (1) mode (1) ntp (1) password (1) rweb (1) vrrp (1)

AUTHOR

CacheGuard Technologies Ltd <www.cacheguard.com>

Send bug reports or comments to the above author.

COPYRIGHT

Copyright (C) 2009-2018 CacheGuard - All rights reserved