zas.cfg

zas.cfg — zas(8) configuration file.

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 crypt(3)-ed password. 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.

Author

This manual page was written by the BalaSys Documentation Team <documentation@balasys.hu>.

Copyright

Copyright © 2006-2015 BalaBit IT Security, 2015-2017 BalaSys IT Security. All rights reserved.