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) <ldap-server> [<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 [server [(raz | (add | del) <kerberos-server>)]]]
[9] authenticate [kerberos [web <service-name>]]
[10] authenticate [kerberos [rweb [add <site-name> <service-name> | del <site-name> | raz]]]
[11] authenticate [ad [(on | off) | rdn [<host-relative-dn>] | account [<login-name> [<password>]]]]
[12] authenticate [kerberos [(create <admin-user> [<admin-password> [wait]]) | report [create | keytab]]]
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 from 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 [3] 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®). 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.
If 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. 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 identified.
As another example to request a Microsoft AD (Active Directory) you can use the following command:
authenticate ldap request ’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, 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 (refers to STARTTLS). 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 presented by an LDAPS server can be verified against the CA certificate that was used to sign it. The fifth [5] usage form allows you to activate this feature by specifying the CA certificate ID (<ca-id>) to be used for verification. To add and import a CA certificate, see the tls command.
Usually LDAP servers require that a client (here the 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 or 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 password command 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. 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 eight to thirteenth [8][9][10][11][12] allow you to configure Kerberos authentication against a Kerberos server. The present system is compatible with both MIT and AD[rg] Kerberos servers. To enable Kerberos authentication mode, at least one Kerberos server must be specified. Kerberos servers can be specified by their DNS names or IP addresses. The eighth [8] usage form allows you to manage the Kerberos servers to which the appliance connects.
In the ninth [9] usage form, the keyword web allows you to set the name by which the appliance is identified as an HTTP service on the Kerberos server. This should typically be the name used to configure the web proxy on the client side (in the web browser). Note that a service name should be specified here (proxy, for instance).
The Kerberos authentication can also be activated for users of reverse websites, provided that the users to be authenticated depend on the same Kerberos servers as the reverse proxy (rweb mode). The tenth [10] usage form allows this. Kerberos authentication is not activated for all reverse websites, but only for reverse websites that are associated with an HTTP service name (short hostname). To associate a service name with a reverse website, use the keywords authenticate kerberos rweb add followed by an existing reverse website name and a service name. To deactivate Kerberos authentication for a reverse website, use the keywords authenticate kerberos rweb del followed by the reverse website name. To deactivate Kerberos authentication for all reverse websites, use the keywords authenticate kerberos rweb raz.
Refer to the KERBEROS NOTES section for detailed information about the naming restrictions applied to the service names.
The eleventh [11] usage form allows you to switch between MIT and AD Kerberos server modes and configure AD mode. To activate AD mode, use the ad on keywords. To use MIT mode, use the ad off keywords. An AD server acts not only as a Kerberos server but also as an LDAP server, and an object representing the appliance should exist on it. If it does not, the object is created during Kerberos initialisation (see the twelfth [12] usage form below). By default, cn=computers is used as the appliance’s RDN. If you need to modify it, use the ad rdn keywords followed by the desired RDN. To obtain the relative base DN of an LDAP object, remove the name specification prefix (cn=<name>) and the domain name specification part from its FDN (Fully Distinguished Name). For example, if your domain name (see the domainname command) is example.com and your appliance is identified by the FDN cn=proxy,cn=computers,dc=example,dc=com in your AD LDAP directory tree, the relative base DN is cn=computers.
In AD mode, HTTP services should be associated with an AD account, whereas this is not applicable to MIT mode. By default, the appliance uses the web service name specified with the ninth [9] usage form above as the account name. To use another account name, use the ad account keywords followed by the desired account, specified by a <login-name> and <password>. If no password is specified, the appliance prompts you to enter it securely. If an empty password is specified, a random password is generated for the newly created account, and the system automatically changes it when it becomes more than 31 days old. In contrast, if a non-empty password is specified, it will never be modified by the system. The specified password must comply with your AD server’s password requirements and the following system requirements: it must be between 16 and 32 characters long and contain at least one lowercase character, one uppercase character, one digit, and one special character from !@#%.$&*-.. Specifying a fixed account password can be particularly useful in HA (High Availability) mode. Refer to the KERBEROS NOTES below for further information about the AD authentication account and HA mode. During Kerberos initialisation (see the twelfth [12] usage form below), if the account does not exist, it is created.
You can also use the password command to set the AD account password.
The first time Kerberos authentication mode is activated, after the apply operation terminates, Kerberos authentication must be initialised. The initialisation process obtains Kerberos tickets for your appliance. To do so, you must use a Kerberos account with administrator privileges (the administrator or admin/admin account, for example). The twelfth [12] usage form allows you to initialise Kerberos authentication. To initialise Kerberos authentication, use the kerberos create keywords followed by the Kerberos server administrator credentials (login and password). The initialisation process runs in the background unless <admin-password> is specified on the command line and the wait keyword is used. If the Kerberos server administrator password is not specified on the command line, the system requires you to enter it interactively in secure mode. The password entered here is not stored permanently and is removed after the appliance’s key table has been created. The kerberos report keywords, without any additional keyword or followed by the create keyword in the twelfth [12] usage form, allow you to display a report of the most recent Kerberos initialisation operation. If an end user cannot authenticate, the kerberos report keytab keywords allow you to display the Kerberos key table in order to diagnose the issue. This table includes, among other information, the KVNO (Key Version Number) associated with each entry, which you can compare with the key table on the Kerberos server for the corresponding user.
Because an LDAP filter or a distinguished name contains the equal character, it should be quoted with simple 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).
• With Active Directory, the service name is also used as the computer/account name; therefore it is limited to 1-15 characters and may contain only letters, digits, and hyphens, with no leading/trailing ’-’ or digits-only name. For consistency, the system applies the same constraints when MIT Kerberos is used, even though MIT Kerberos itself does not impose these computer-name restrictions.
• When the system is configured in HA (High Availability) mode, where two or more appliances share the same VRRP IP address, and AD Kerberos mode is used, all HA peer appliances must use the same service names and share the same account login and password on the Kerberos servers to ensure service continuity in the event of an appliance failure. In this case, the account password should never expire or be changed on the AD servers. If you modify the AD account login and/or password, remember to run the Kerberos initialisation process on all HA peer appliances.
If the appliance is placed behind a third-party firewall, you should allow the following traffic to enable authentication against Kerberos servers. The following protocol and ports should be accessible from the system:
• Kerberos traffic (TCP 88) from the appliance to the Kerberos servers.
• Kerberos administration traffic (TCP 749) from the appliance to the Kerberos servers (AD only).
• Kerberos password traffic (UDP 464) from the appliance to the Kerberos servers.
• LDAP traffic (TCP 389) from 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 <www.cacheguard.com>
Send bug reports or comments to the above author.
Copyright (C) 2009-2026 CacheGuard Technologies - All rights reserved