zas.cfg

Description

The zas.cfg file controls the operation of Zorp Authentication Server.

Structure

The file uses an XML-like format to describe various configuration settings. It uses a configuration/section/<setting> structure where the "name" attribute of the configuration block identifies the ZAS subsystem described by the nested tags. The example below sets the global options used by ZAS, broken down to three different sections: "log" for log related settings, "router" to set the path to the router.cfg file and "ssl" for SSL related settings.

        <configuration name="zas">

          <section name="log">

            <loglevel>3</loglevel>

            <use_syslog>1</use_syslog>

            <logtags>1</logtags>

          </section>

          <section name="router">

            <router>/etc/zas/router.cfg</router>

          </section>

          <section name="ssl">

            <use_ssl>0</use_ssl>

            <key>/etc/zas/zas.key</key>

            <cert>/etc/zas/zas.crt</cert>

            <verify_mode>0</verify_mode>

          </section>

         </configuration>

The ZAS plugins (backends) have a slightly different structure. The name attribute in the configuration tag of the ZAS plugin and the section name identifies an instance of that plugin. Each instance can be run with a different parameter set. The example below shows a complete configuration block for the PAM backend with two instances: intra and internet:

        <configuration name="pam">

           <section name="intra">

            <service>zas_intra</service>

            <sleep_time>0</sleep_time>

            <fake_user>0</fake_user>

          </section>

          <section name="internet">

            <service>zas_internet</service>

            <sleep_time>10</sleep_time>

            <fake_user>1</fake_user>

          </section>

        </configuration>

The router.cfg file

The router.cfg file controls the backend instance selection in ZAS. When a new authentication request is initiated by zorp(8), ZAS selects an authentication backend and an instance based on the meta-information that Zorp supplies. Each line in router.cfg comprises from a condition and an action, separated by whitespace. When an incoming request matches a condition, the corresponding the action identifies the authentication backend and its instance to be used.

The condition is a comma separated list of constraints, each constraint identifying an authentication header and an expected value in the header=match,header=match,... format. Wildcard characters like '*' and '?' can be included in the matches.The following headers are currently defined:

Client-Zone: The name of the zone the client belongs to.
Client-IP: The original IP address of the client initiating the connection to be authenticated.
Service: The name of the service the client is authenticating for.

The action identifies the ZAS backend to use (e.g.: zas_db, pam, etc.) and the specific instance of that backend. The backend and instance names are separeated by colon (:). Instances are identified by simple names and are used distinguish between various setups of the same backend.

The example below selects the intra instance of the zas_db backend. If the configuration block for this backend is not found, or the condition does not match, the zas_db:default instance is used.

            Client-Zone=intra      zas_db:intra

            zas_db:default

Global ZAS options

The global configuration options of ZAS are described in the zas configuration block. The related options are grouped into sections. The following options are available:

Section log

use_syslog: Use syslog for logging.
logtags: Enable the logging of message tags.
loglevel: Level of verbosity for logging messages. Default value: 3.

Section bind

ip: IP address to which ZAS binds. Default value: 0.0.0.0.
port: Port to which ZAS binds. Default value: 1317.

Section ssl

use_ssl

Enable SSL encryption.

cert

The certificate file used to authenticate ZAS.

key

The private key file of the certificate used to authenticate ZAS.

ca_dir

Path to the directory where the certificates of the trusted CAs are stored.

crl_dir

Path to the directory where the certificate revocation lists are stored.

verify_depth

The maximum length of the verification chain. Default value: 3.

verify_mode

Method how the certificates of the connections incoming to ZAS are verified.

0: No certificate is needed.
1: Certificate is optional, but has to be valid if present.
2: A valid certificate is required, untrusted (but valid) certificates are also accepted.
3: A valid, trusted certificate is required.

Section router

router: Path to the router.cfg file.

Section misc

trust_connection: Permit password-based authentication methods even for unencrypted connections. Default value: 0 (false).

Backends

ZAS operates using several authentication backends, each with its own set of parameters. Currently the following backends are available:

zas_db: Database based backend which currently provides the most features. It has a backing database (called "storage") and a set of authentication methods (called "methods"). The name of the configuration block is zas_db
pam: Authenticates users against the local PAM libraries on the host running ZAS itself. The name of the configuration block is pam.
htpass: Authenticates users against an Apache htpasswd style password file. The name of the configuration block is htpass.
radius: Authenticates users against a RADIUS server. The name of the configuration block is radius.
tacacs: Authenticates users against a TACACS+ server. The name of the configuration block is tacacs.

All backends are capable of authentication faking. This is a method to hide the valid usernames, so that they cannot be guessed (for example using brute-force methods). If somebody tries to authenticate with a non-existing username, the attempt is not immediately rejected: the full authentication process is simulated (e.g.: password is requested, etc.), and rejected only at the end of the process. That way it is not possible to determine if the username itself was valid or not.

The Zas_db backend

The zas_db backend interprets the following parameters in its configuration block.

storage: Specifies the database plugin to use. Currently only the ldap database is supported.
methods: Specifies a space separated list of enabled authentication methods. The following authentication plugins are available: passwd, skey, rb1, x509, ldapbind, and none.
fake_user: Enables authentication faking.
fake_user_name: Specifies a user name which is used for faking authentication. This has to be an existing user name, used exclusively for this purpose.
sleep_time: Wait at least that many seconds after a failed authentication attempt.

Storage plugins

The zas_db backend authenticates against an abstract database, the actual implementation is specified using the storage parameter. The only storage plugin currently supported is ldap.

ldap: The ldap storage plugin uses the Lightweight Directory Access Protocol (LDAP) to access a directory based database. It has a separate configuration block identified by the name zas_db_storage_ldap.

The LDAP storage plugin

The LDAP storage plugin connects to an LDAP server, authenticates using a user-independent, service account and runs queries against the database to provide a zas_db dependent view on the directory. It uses a ZAS specific LDAP scheme available in the zas package.

use_ssl: Enables SSL/TLS when connecting to the LDAP server.
hostname: Specifies the LDAP host to use.
port: Specifies port of the LDAP server to use.
bind_dn: Bind to this DN before accessing the database.
bind_pw: Use this password when binding to LDAP.
base_dn: Perform queries using this base DN.
filter: Search for an account using this filter expression. Defaults to '(uid=%u)'; %u is expanded to the username being searched for.
scope: Specifies the scope of the search. base, sub, and one are acceptable values, specifying LDAP_SCOPE_BASE, LDAP_SCOPE_SUB, and LDAP_SCOPE_ONE, respectively.
user_is_dn: Specify that the incoming username is a fully qualified DN.
scheme: Specify LDAP scheme to use: posix for POSIX, ad for ActiveDirectory, or nds for Novell eDirectory/NDS style directory layout.
ldapbind_description: When the ldapbind authentication method is used for authentication, the value of this string is returned as method description to the user. NOTE: This parameter is OBSOLETE, it must be set in the ldapbind authentication method.
usercert_description: When the directory contains user keys in the userCertificate attribute and it is used for X.509 based authentication, the value of this string will be returned as method description to the user. OBSOLETE. Set it in x509 authentication method.
follow_referral: If this option is set, ZAS will respect the referral response from the LDAP server when looking up a user.

Authentication method plugins

The zas_db backend is general enough to allow the use of several different authentication methods. The set of permitted authentication methods is defined using the methods configuration option as described in the previous section. All pligins have a priority attribute. This attribute is used by the Satyr authentication client: the authentication methods available to the user are displayed in the order of the priority (starting with the highest value).

The following method plugins are available:

passwd

Implements password authentication. Password authentication is available only if the connection between Zorp and ZAS is secure. The name of the configuration block is zas_db_method_passwd.

The password authentication method has the following parameters:

priority: Priority of the authentication type.

skey

Implements S/Key authentication. The name of the configuration block is zas_db_method_skey.

The S/Key authentication method has the following parameters:

priority: Priority of the authentication type.

rb1

Implements CryptoCard RB1 hardware token based authentication. The name of the configuration block is zas_db_method_rb1.

The RB1 authentication method has the following parameters:

priority: Priority of the authentication type.

x509

Implements X.509 certificate based authentication. The name of the configuration block is zas_db_method_x509.

The X.509 authentication method has the following parameters:

compare_cert: Compare the stored certificate bit-by-bit to the certificate supplied by the client. The authentication will fail when the certificates do not match, even if the new certificate is trusted by the CA. Default value: 1 (TRUE).
trusted_ca_list: Send a list of trusted certificates to the client to choose from to narrow the list of available certificates. Default value: 1 (TRUE).
verify_cert: Verify the validity of the certificate (i.e. the certificate has to be issued by one of the trusted CAs and not revoked). This is verification is independent from the compare_cert setting, so if both parameters are set, both conditions must be fulfilled to accept the certificate. Default value: 1 (TRUE).
ca_locations: A list of space separated URLs to the trusted CAs. The file:// and ldap:// URLs are supported.
crl_locations: A list of space separated URLs to the CRLs issued by the trusted CAs. The file:// and ldap:// URLs are supported.
verify_depth: The maximum length of the verification chain.
priority: Priority of the authentication type.

ldapbind

Implements authentication against the target LDAP server. Only password authentication is supported by this method, therefore it is only available if the connection between ZAS and Zorp is secured with SSL. The name of the configuration block is zas_db_method_ldapbind.

The LDAP authentication method has the following parameters:

priority: Priority of the authentication type.
description: The value of this string is returned as method description to the user.

none

Implements NO authentication. This method accept every authentication request if the user is exists in the database. The main advantage of this method is when the authentication is done somwhere outside of this program but the groups information is needed. The name of the configuration block is zas_db_method_none.

The None authentication method has the following parameters:

priority: Priority of the authentication type.
description: The value of this string is returned as method description to the user.

gssapi

Implements GSSAPI based authentication. NOTE: The Kerberos5 keytab file to be used can be specified via the standard KRB5_KTNAME environment variable. The name of the configuration block is zas_db_method_gssapi.

The gssapi authentication method has the following parameters:

priority: Priority of the authentication type.
description: The value of this string is returned as method description to the user.
principal_name: Specifies the GSSAPI principal name which this authentication service represents. Make sure that the keys associated with this principal are present in /etc/krb5.keytab. Changing the keytab location is currently not possible.

The PAM backend

The PAM backend implements authentication based on the local authentication settings of the host running ZAS. It basically authenticates the users against the local PAM installation and/or using GSSAPI/krb5. The PAM backend has the following parameters:

use_local_accounts: Use the local passwd/group database to query group membership of a given account. The Name Service Switch can also be used, so integrating other naming services is possible. Defaults value: 0 (FALSE).
enable_pam_auth: Enable PAM authentication. Default value: 1 (TRUE).
pam_service: Specifies the PAM service to use for authentication. This option is an alias for the now deprecated service option. Defaults value: zas.
enable_gssapi_auth: Enable GSSAPI/krb5 authentication in this backend. Defaults value: 0 (FALSE). NOTE: The Kerberos5 keytab file to be used can be specified via the standard KRB5_KTNAME environment variable.
gssapi_princ_name: Specifies the GSSAPI principal name which this authentication service represents. Make sure that the keys associated with this principal are present in /etc/krb5.keytab. Changing the keytab location is currently not possible.
description: The value of this string is returned as method description to the user.
fake_user: Enables authentication faking.
sleep_time: Wait at least that many seconds after a failed authentication attempt.

The Htpass backend

The htpass backend has the following parameters:

filename: The file to be read as password file. The file should contain two columns separated by colon (':'), with the first column containing the username, the second the password encrypted by crypt(3) function. This file can be created/maintained by the Apache htpasswd(1) utility.
fake_user: Enables authentication faking.
sleep_time: Wait at least that many seconds after a failed authentication attempt.

The Radius backend

The Radius backend has the following parameters:

hostname: The hostname of the RADIUS server.
hostport: The port of the RADIUS server.
secret: The shared secret between the authentication server and ZAS.
description: The value of this string is returned as method description to the user.
fake_user: Enables authentication faking.
sleep_time: Wait at least that many seconds after a failed authentication attempt.

The TACACS+ backend

The TACACS backend has the following parameters:

hostname: The hostname of the TACACS+ server.
hostport: The port of the TACACS+ server, defaults to 49.
secret: The shared secret between the authentication server and ZAS.
description: The value of this string is returned as method description to the user.
fake_user: Enables authentication faking.
sleep_time: Wait at least that many seconds after a failed authentication attempt.

Previous	Up	Next
	Home

Zorp Professional 7 Reference Guide

Appendix C. Zorp manual pages