authenticate - Manage the Web access authentication
[1] authenticate [(web | rweb) [on | off]]
[2] authenticate [mode [(ldap | kerberos) [on | off]]]
[3] authenticate [ldap [request [’<user-base-dn>’ ’<login-attr>’ [’<passwd-attr>’ [’<ldap-filter>’ [’<group-dn>’]]]]]]
[4] authenticate [ldap server [(raz | (add | del) (ldap | ldaps | sldap) <name> <ip> [<port>])]]
[5] authenticate [ldaps [ca [raz | set <ca-id>]]]
[6] authenticate [ldap [binddn [’<dn>’ [(off | on) <password>]]]]
[7] authenticate [ldap [test [<login-name> [<password>]]]]
[8] authenticate [kerberos [(encrypt [(des | aes)]) | (web <canonical-name>) | (hapassword <shared-password>)]]
[9] authenticate [kerberos [server [(raz | (add | del) <kerberos-server>)]]]
[10] authenticate [kerberos [rweb [add <site-name> <canonical-name> | del <site-name> | raz]]]
[11] authenticate [kerberos [(create <admin-user>) | report]]
[12] authenticate [ad [rdn [<host-relative-dn>]]]
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 [1] usage form allows you to define target authenticated users. The keyword rweb specifies users accessing reverse websites (see the command rweb) while the keyword web specifies forwarding users accessing all other websites. 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 allow you respectively to activate or deactivate the authentication for a target.
The second [2] usage form allows you to set the authentication mode. Two authentication modes are supported: LDAP and Kerberos. With the LDAP authentication, the browser basic authentication is used. In this authentication mode, the user is asked to enter its login/password in a popup window (the user should have an account on the LDAP server). With the Kerberos authentication, no login/password is requested as the authentication is negotiated with the Kerberos domain controller (and the same credentials used to login to the client machine is then used - This is called SSO: Single Sign On).
While in most cases, only one of these two authentication modes is to be activated you, you have the possibility to activate both modes at. In this case, the authentication behaviour would then be as follows:
• Forwarding users accessing the Web are authenticated using the Kerberos protocol first. If the Kerberos authentication fails, the LDAP authentication is used.
• Reverse users accessing cloaked/protected websites are authenticated the same way as before if the WAF mode is deactivated. With the WAF mode being activated, two behaviours are possible: if the Kerberos mode is explicitly activated for the reverse website (see usage form number ten), only the Kerberos authentication is used. Otherwise the LDAP authentication is used.
Usage forms from the third to sixth [3][4][5][6] allow you to configure the 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 sent to LDAP servers. To set the LDAP request use the keyword request followed by:
• The base DN (Distinguished Name) under which users are located.
• The attribute name that contains the user login.
• The the attribute name that contain the user password (if not specified, the bind method is used).
• The LDAP search filter to locate users under the base DN.
• Optionally an LDAP group identified by its DN to which users should belong.
Empty values (’’) can be used as the <passwd-attr> and the <ldap-filter> arguments. If an empty value is specified as the <passwd-attr>, an LDAP binding is performed during the basic authentication phase instead of a comparison of the entered password against the value stored in the <passwd-attr> LDP attribute (this is the preferred method used by Microsoft AD (Active Directory)™. Please note that the login attribute in AD™ is sAMAccountName (or cn). 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 bind is used instead.
In case where an optional LDAP group is specified, members of that group should be identified by their DN and stored in the member attribute of that group. Please note that as LDAP DNs 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’ ’’ ’objectClass=inetOrgPerson’ ’cn=web,ou=groups,dc=example,dc=com’
This command allows you to authenticate users of the class inetOrgPerson registered under the object ou=people,dc=example,dc=com and identified by the LDAP attributes cn. In addition, this command specifies a group identified by the DN cn=web,cn=groups,dc=example,dc=com to which users should belong to be considered as properly identifed.
As another example to request a Microsoft AD (Active Directory)™ you can use the following command:
authenticate ldap requestt ’cn=users,dc=example,dc=com’ sAMAccountName
The fourth [4] usage form allows you to manage LDAP servers. To add an LDAP server, use the keyword add followed by the LDAP protocol (ldap, ldaps or sldap), the LDAP server network name, IP address and optionally port number. If no port number is specified, standard port numbers are used (389 for ldap/sldap and 636 for ldaps). 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. 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.
For a higher level of security an SSL certificate transmitted by an LDAPS server can be verified against the CA certificate that has been used to sign that SSL certificate. The fifth [5] usage form allows you to activate this feature by specifying the CA certificate ID (<ca-id>) of the CA certificate to use for verification. To add and import a CA certificate see the command tls.
Usually LDAP servers require that a client (here the an appliance) authenticate itself before being able to send LDAP request. This authentication process is called binding. The sixth [6] usage form allows you to activate of deactivate the LDAP binding and configure the DN (Distinguished Name) and password to use for the binding process. To activate the binding, use the keyword binddn followed by the DN of a privileged user (usually the administrator user), the keyword on and the authentication password for that privileged user (on the LDAP server). The password specified here should not be longer that 64 characters. You can also use the command password to set the binding password. If no binding is required, use the keyword off instead of the keyword on (no password is required). Tip: the Bind DN for a Microsoft AD (Active Directory)™ is usually in the form of: cn=administrator,cn=users,dc=example,dc=com.
The seventh [7] 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 eighth to twelfth [8][9][10][11][12] 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 the client side (the Web browser). 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 (preferably two) should be specified. Kerberos servers can be specified by their DNS names or IP addresses. The present system is compatible with AD™ domain controller. To use an AD™ as a Kerberos server, the relative base DN of the present system should be specified in order to allow the AD™ to identify it in its LDAP directory tree. To get the relative base DN of an LDAP object, you should remove the name specification prefix (cn=<name>) and the domain name specification part in an FDN (Full Distinguish Name). For instance if your domain name (see the domainname command) is example.com and if your system is identified by the FDN cn=proxy,cn=computers,dc=example,dc=com in your AD™ LDAP directory tree, your relative base DN will be cn=computers. The authenticate ad rdn usage form allows you to specify that relative base DN.
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 an existing reverse website name and a valid canonical name. See below the definition of a valid canonical name. To deactivate the Kerberos authentication for a reverse website use the keywords authenticate kerberos rweb del followed by the reverse website 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 initialised. During the initialisation 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 initialisation 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 initialise 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 initialisation is an asynchronous operation and is executed in background. The report keyword allows you to display a report of the last Kerberos initialisation operation.
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.
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.
• 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.
The authentication is not supported in transparent mode.
access (1) clock (1) domainname (1) ha (1) mode (1) ntp (1) password (1) rweb (1) tls (1) vrrp (1) waf (1)
CacheGuard Technologies Ltd <www.cacheguard.com>
Send bug reports or comments to the above author.
Copyright (C) 2009-2024 CacheGuard - All rights reserved