Configuring ZXID

Sampo Kellomäki ( Identity Management toolkit implements standalone SAML 2.0 and Liberty ID-WSF 2.0 stacks. This document explains configuration options of ZXID.

1 Introduction

ZXID, out-of-box, needs very little configuration. Generally you only need to decide the URL and NICE_NAME of your web site.

Compile time configuration, based on Makefile and zxidconf.h is explained in separate document ZXID Compilation and Installation.

In addition to setting runtime configure options, you will need to join a Circle of Trust - or create your own. This part of set-up is explained in Building CoT.

If you are interested in using mod_auth_saml Apache module, you can perform some of the configuration in the Apache httpd.conf file as explained in mod_auth_saml.

You should remember that some of the configuration will happen in the web server level, see your web server's configuration reference, e.g. httpd.conf

1.1 Other documents

2 Configuring and Running

ZXID ships with working demo configuration so you can run it right away and once you are familiar with the concepts, you can return to this chapter.

Tip: You can view current configuration by supplying URL suffix ?o=d, e.g.

2.1 Overview of Configuration

The bare built-in configuration will allow you to test features of ZXID, but should not be used in production because it uses default certificates and private keys. Obviously the demo private key is of public knowledge since it is distributed with the ZXID package, and as such it provides no privacy protection what-so-ever. For production use you MUST obtain or generate your own certificate and private key.

Minimal configuration file /var/zxid/zxid.conf is as follows (see sections "ZXID Configuration File Format", "Configuration Parameters", "Full Configuration Option Reference", and file zxidconf.h for full explanation):

  # Demo /var/zxid/zxid.conf file
  NICE_NAME=My SP's human%0areadable name.
  ORG_NAME=My Company, Inc.
  LOCALITY=City of Industry

Usually configuring a system involves the following tasks

  1. Configure a safe operating environment. In addition to physical security and vetting personnel, this typically involves following sysadmin tasks (be sure to have competent sysadmim understand and implement these):

    1. Install machine (instantiate) from reliable OS media, secure logins and have rigour in issuance of ssh credentials and sudo root rights

    2. Harden system by eliminating unnecessary services, applying patches, and configuring firewalls (decide which ports you use: typical is 443 for https)

    3. Implement encrypted filesystem to protect /var/zxid directory (or other ZXID directories depending on your chosen filesystem layout). In implementing encrypted filesystem, pay attention to narrow key distribution and escrow procedures. These need to cater for reboots (manually supply passphrase for the encfs) and disaster recovery scenarios.

    4. Implement secure log collection, analysis, and storage (encrypt data at rest)

    5. Implement secure backup. Encrypt data at rest, e.g. using pgp(1). Do not forget key escrow.

    6. Register domain names and have certificates issued

  2. Configure web server (see your web server documentation)

    1. HTTPS operation and TLS certificate. In the minimum you need the main site, but you may want to configure the Common Domain Cookie virtual host as well.

    2. Arrange for ZXID to be invoked. This could mean configuring zxidhlo,, or to be recognized as a CGI script, or it could mean setting up your mod_perl or mod_php system to call ZXID at the appropriate place.

  3. Configure ZXID, including signing certificate and CoT with peer metadata

    1. Edit the configuration options (e.g. in /var/zxid/zxid.conf, but see below). You must set at least URL and NICE_NAME.

    2. Generate or acquire certificate

    3. Obtain peer metadata (from their well known location) or enable Auto CoT feature (see below). You can also use zxcot(1) command line tool to import their metadata.

  4. Configure CoT peers with your metadata. They can download your metadata from your well known location (which is the URL that is your entity ID, usually ending in "?o=B"). For this to happen you need to have a web server and ZXID up and running. Other route is to use zxcot(1) command line tool, e.g.

         zxcot -c URL= -c NICE_NAME='Your SP Brand' >your-md.xml

    to generate metadata and then manually transfer it to CoT peers.

  5. If you are setting up an IdP (especially with Discovery), you need to address several other points. Please see zxid-idp.pd for further information.

2.2 Sources of Configuration

The configuration options of ZXID can be set using various methods, with later occurrance of an option overriding the previous value. Thus default configuration can (and should) provide most options, while you can override the ones that interest your particular deployment (you should override at least URL and NICE_NAME). The order, from earliest application to last application, of the sources of configuration options is as follows:

  1. Compile time default configuration, see zxidconf.h

  2. Default configuration file /var/zxid/zxid.conf (n.b. this file need not exist, in which case it does not affect the configuration)

  3. VPATH configuration file /var/zxid/<host:port>/zxid.conf (n.b. this file need not exist, in which case it does not affect the configuration). See (10) for full description.

  4. ZXID_PRE_CONF environment variable, if supplied

  5. Configuration string passed as an argument to one of the API calls, e.g. zxid_new_conf_to_cf() or zxid_simple(). Usually this is a hardwired string that the application programmer provides, but the programmer might provide application dependent mechanism to configure it.

  6. ZXID_CONF environment variable, if supplied

  7. In case of mod_auth_saml, the ZXIDConf options in the httpd.conf file (in some distributions apache2.conf)

  8. In case of command line utilities, like zxcot(1), commandline flags like -c OPT=VAL or -ci (for default IdP config)

  9. If PATH configuration option is changed by any of the above methods (2)-(8), a new configuration file PATH "zxid.conf" (where (dollar) denotes string concatenation) is read and evaluated at the spot where the PATH changed (i.e. such configurations are evaluated in the middle of the other methods).

  10. If VPATH configuration option is changed by any of the above methods, a new configuration file PATH fold(HTTP_HOST) "zxid.conf", where (dollar) denotes string concatenation and fold() denotes function squashing all suspicious characters to underscores, is read and evaluated at the spot where the VPATH is changed (i.e. such configurations are evaluated in the middle of the other methods).

    The VPATH option is meant to implement a virtual hosting feature where the PATH is automatically determined from apparent host name and port number, and consequently different zxid.conf is read for each virtual host. The feature is on by default, but if no corresponding file is found, no configuration change happens. If the file is found, then PATH is also changed. Thus unlike in many other cases, for virtual hosting the virtual host specific zxid.conf files are mandatory. This makes sense as NICE_NAME, et al. should be specified anyway.

Interplay of the respecification of PATH (you can specify even the same path) and other configuration methods allow all sorts of default scenarios to be implemented. For example, specification like


sets the URL configuration option, then rereads the /var/zxid/zxid.conf configuration file which allows URL to be overridden in the configuration file, but finally disables the PEP functionality such that it overrides the configuration file (unless some later configuration source causes the configuration file to be reread anyway).

N.B. Avoid recursive speficications of PATH and/or VPATH. They will be expanded to depth of 5, but are almost always errors.

2.3 Virtual Hosting

As alluded in bullet (10) above, ZXID supports hostname based virtual hosting (multihoming). For this setup you would lay out your /var/zxid directory as follows

   +-- zxid.conf  Main configuration file for generic options
   +-- pem/       Not used
   +-- cot/       Not used
   +-- ses/       Not used
   +-- log/       Some pid files (but see virtual host specific log dir)
   +-- <host1:port>    Virtual host specific subdirectory (VPATH)
   |    |
   |    +-- zxid.conf  VPATH configuration file
   |    +-- pem/       VPATH certificates
   |    +-- cot/       VPATH metadata of CoT partners
   |    +-- ses/       VPATH sessions
   |    `-- log/       VPATH log and pid files
   `-- <host2:port>    Virtual host specific subdirectory (VPATH)
        +-- zxid.conf  VPATH configuration file
        +-- pem/       VPATH certificates
        +-- cot/       VPATH metadata of CoT partners
        +-- ses/       VPATH sessions
        `-- log/       VPATH log and pid files

For virtual hosting to work, the web server layer must also be configured to support virtual hosting. In Apache2 httpd this can be done using VirtualDocumentRoot directive and directory layout where each virtual host has a subdirectory named after its hostname (preferred and philosphically similar to our approach), or using <VirtualHost> directive blocks (more laboursome as you need to explicitly include such blocks to your config file).

N.B. Another way to implement virtual hosting, that only works with mod_auth_saml, is to use Apache2 httpd.conf file where each <VirtualHost> section specifies different PATH using ZXIDConf directive.

For virtual hosting in Tomcat, there are two cases: if Apache2 httpd is a frontend, as it often is to implement https (recommended), then above instructions apply. If, however, you want to run Tomcat itself directly on virtual host basis, you need to consult Tomcat documentation (which the author has not tried, so there is no guarantee).

If you use mini_httpd, then you need to run one server per IP address + port number combination. (If https is not involved, you could use mini_httpd -v with directory layout, but this is not recommended because all identity related services should be https.)

2.4 Important Configuration Options

For full reference of the configuration parameters, see section "Full Configuration Option Reference", below, or the file zxidconf.h.

2.4.1 NICE_NAME: SP Nickname for IdP User Interface

IMPORTANT: You should really configure this option. It is an important part of your branding towards customers.

The nice name may be used by IdP user interface to refer to the SP. It is usually a short human readable name or description. It will also appear in metadata as Organization/OrganizationDisplayName


(default: "ZXID configuration NICE_NAME: Set this to describe your site to humans")

2.4.2 URL: Web Site URL - root of EntityID

MUST: Failure to config this option usually blocks zxid from operating.

URL for most zxid operations. It must end in whatever triggers the ZXID functionality in the web server (which depends on how you have configured the web server, see httpd.conf). The hostname and port number should match the server under which zxid CGI is accessible. N.B. There is no explicit way to configure Entity ID (Provider ID) for the zxid SP. The Entity ID is always of form ZXID_URL?o=B . ((Actually there is: BARE_URL_ENTITYID option,
 but that is an advanced topic and will not be discussed here.)) For example 

(default: "")

2.4.3 zxidroot (PATH configuration parameter)

The root directory of ZXID configuration files and directories. By default this is /var/zxid and has following directories and files in it

   +-- zxid.conf  Main configuration file
   +-- pem/       Our certificates
   +-- cot/       Metadata of CoT partners (metadata cache)
   +-- ses/       Sessions
   `-- log/       Log files, pid files, and the like

See also zxid-log.pd for detailed description of the filesystem layout.

2.4.4 pem

Directory that holds various certificates. The certificates have hardwired names that are not configurable.


Certification Authority certificates. These are used for validating any certificates received from peers (other sites on the CoT). The CA certificates may also be shipped to the peers to facilitate them validating our signatures. This is especially relevant if the certificate is issued by multilayer CA hierarchy where the peer may not have the intermediate CA certificates.


The signing certificate AND private key (concatenated in one file). The private key MUST NOT be encrypted (there will not be any opportunity to supply decryption password).


The encryption certificate AND private key (concatenated in one file). The private key MUST NOT be encrypted (there will not be any opportunity to supply decryption password). The signing certificate can be used as the encryption certificate. If encryption certificate is not specified it will default to signing certificate.

In addition to the above certificates and private keys, you will need to configure your web server to use TLS or SSL certificates for the main site and the Common Domain site. We suggest the following naming


SSL or TLS certificate for main site. In order to avoid browser warnings, the CN field of this certificate should match the domain name of the site. The SSL certificate can be same as signing or encryption certificate.


SSL or TLS certificate for Common Domain Cookie introduction site. In order to avoid browser warnings, the CN field of this certificate should match the domain name of the site. The SSL certificate can be same as signing or encryption certificate.

2.4.5 cot

Directory that holds metadata of the Circle of Trust (CoT) partners. If Auto CoT is enabled, this directory needs to be writable at run time.

Typical metadata file path would be


If the metadata file appears in this directory, then the entity is in the CoT.

The file name component of the path is safe base64 encoded SHA1 hash of the Entity ID, with last character stripped (that character would always be an equals sign).

2.5 ZXID Configuration File Format

Most configuration details are kept as comments in zxidconf.h, which you should see.

Configuration file is line oriented. Comments can be introduced with cardinal ("#") and empty lines are ignored. End of line comments are NOT supported at this time.

Each configuration option is a name=value pair. The name is the same as in zxidconf.h except that ZXID_ prefix does not appear. Only single line values are supported, but you can embed characters using URI encoding, e.g. %0a for newline. In fact, the configuration lines are treated as CGI variables, thus & can also be used as separator instead of newline (and needs to be encoded if not intended as separator).

When option is not specified, the default from zxidconf.h prevails. Thus in the following the PATH specification is redundant.

To give some idea consider following /var/zxid/zxid.conf example:

  # Demo /var/zxid/zxid.conf file
  NICE_NAME=My SP's human%0areadable name.

The configuration is processed in following order, with last instance of an option prevailing:

  1. Built in default configuration

  2. Configuration file /var/zxid/zxid.conf

  3. Configuration string passed as first argument.

    Configuration string is processed in order and overrides values from compiled in defaults as well as from zxid.conf in the compiled in default path.

    While processing options, if PATH is found, the (new) config file is read, effectively overriding any options thus far.

    See section "Sources of Configuration", above, for full description.

Essentially this allows you to provide early in configuration string options that can then be overridden by the config file ready by virtue of PATH apprearing in the config string. The options in the string that come later in the string can then override values in config file.

3 zxid_simple() API Specific Configuration

For full description of the simple API, plese see zxid_simple() Easy API for SAML.

3.5.1 Configuration Options

The zxid_simple() can be configured by conf string as argument as well as by configuration file. In addition a flags argument is accepted, see next subsection "AUTO options", to specify simple API specific automation options.

Turns out that often the default configuration modified by the configurations string is all you need - you do not need to prepare a configuration file.

See section "Configuring and Running" for complete list of configuration options, but generally it is sufficient to specify only a handful:


Where files are kept and configuration file is found.


Human readable namme of the SP


The URL of the SP


The Common Domain URL (optional, if omitted the Common Domain Cookie processing is disabled)

3.5.2 AUTO options (auto flags)

The auto_flags argument allows you to control which operations should be performed automatically and which should be passed to the calling application, see "Gaining More Control" section, below, for full description of this case.

The auto options can be added together.

Table 1:zxid_simple() AUTO options
Dec Hex Symbol Description
1 0x01 ZXID_AUTO_EXIT Call exit(), 0=return "n", even if auto CGI
2 0x02 ZXID_AUTO_REDIR Automatic. handle redirects, assume CGI (calls exit(2))
4 0x04 ZXID_AUTO_SOAPC SOAP response handling, content gen
8 0x08 ZXID_AUTO_SOAPH SOAP response handling, header gen
16 0x10 ZXID_AUTO_METAC Metadata response handling, content gen
32 0x20 ZXID_AUTO_METAH Metadata response handling, header gen
64 0x40 ZXID_AUTO_LOGINC IdP select / Login page handling, content gen
128 0x80 ZXID_AUTO_LOGINH IdP select / Login page handling, header gen
256 0x100 ZXID_AUTO_MGMTC Management page handling, content gen
512 0x200 ZXID_AUTO_MGMTH Management page handling, header gen
1024 0x400 ZXID_AUTO_FORMF In idp list and mgmt screen, generate form fields
2048 0x800 ZXID_AUTO_FORMT In idp list & mgmt screen, wrap in <form> tag.
4095 0xfff ZXID_AUTO_ALL Enable all automatic CGI behaviour.
4096 0x1000 ZXID_AUTO_DEBUG Enable debugging output to stderr.
8192 0x2000 ZXID_AUTO_OFMTQ Output Format Query String
16384 0x4000 ZXID_AUTO_OFMTJ Output Format JSON

If the AUTO_REDIR flag is true, the LOCATION header is sent to stdout and exit(0) may be called, depending on the AUTO_NOEXIT flag.

The SOAP, META, LOGIN, and MGMT flags follow convention:

  00  No automation. Only action letter is returned ("e"=login, "b"=meta, etc.)
  01  Content, not wrapped in headers, is returned as a string
  10  Headers and content is returned as a string
  11  Headers and content are sent to stdout, CGI style and
      exit(0) may be called, depending on AUTO_EXIT. Otherwise "n" is returned.

Whether exit(0) is called in 11 case depends on ZXID_AUTO_NOEXIT flag.

How much HTML is generated for Login page and Mgmt page in 01 (content only) mode depends on AUTO_PAGE and AUTO_FORM flags

  00  reserved / nothing is generated
  01  Only form fields (but not form tag itself) are generated.
  10  Complete form is generated
  11  Whole page is generated (best support)

The output format in the successful SSO case depends on OFMT bits as follows

  00  LDIF (default)
  01  Query String
  10  JSON
  11  empty res, caller is expected to access ses for attributes

3.5.3 Configuration options for customizing HTML

When whole page is generated, some templating information is taken from the configuration.


Path for Template for IdP Selecton Page. Default "idpsel.html". This file, which you can edit for customization, is used as template to render the IdP selection page on the SP side. If the file does not exist, the value of ZXID_IDP_SEL_TEMPL configuration option is used as template. By default idpsel.html uses idpsel.css as stylesheet. You can make many kinds of customization just by editing this stylesheet.


Template for IdP Authentication Page that is used if the path does not work. This is really meant to be the last resort. The default value of this page is the compiled in template "ZXID SP SSO: Choose IdP".


Choose the method for rendeing IdP list. 0 = popup menu, 1 = buttons, 2 = branded image buttons (not implemented as of 20100922)


IdP Selector Page URL

   If the IDP_SEL_TEMPL_FILE or IDP_SEL_TEMPL, above, is not sufficient for
   your customization needs, you can provide URL to page of your own design.
   This page will receive as query string argument the relay state.
   0 (zero) disables.

You can set several rather technical configuration options by editing the IdP selection template and adding (hidden) form fields. You may want to hardwire these or allow user to set them


Create federation (AllowCreate flag)


Name ID format


Persistent (pseudonym)


Transient, temporary pseudonym

Technical parameters that the site administrator should decide and set. Usually hidden form fields in the template:


Affiliation ID (usually empty)


Consent obtained by SP for the federation or SSO


No statement about consent


Has been obtained (unspecified way)


Obtained prior to present transaction, e.g. user signed terms and conditions of service


Consent is implicit in the situation where user came to invoke service


Obtained explicitly


Consent can not be obtained


Obtaining consent is not relevant for the SP or service.


Authentication Context (strength of authentication) needed by the SP


Matching rule for authentication strength (usually empty, IdP decides)


Forbid IdP from interacting with the user (IsPassive flag)


Request reauthentication of user (ForceAuthn flag)

4 ZXID Attribute Broker (ZXAB)

Fig-1: Liberty IGF Compliant Attribute Broker fetches the needed attributes from available providers and populates them to the subprocess environment.

As can be seen in the accompanying figure, the provision of attributes to the applications in the Apache subprocess environment (CGI, mod_perl, mod_php, etc.) is handled as follows:

  1. Configure attribute needs and names (this corresponds to CARML declaration)

  2. Configure attribute sources (this corresponds to AAPML declaration)

  3. Configure source or input mappings (INMAP)

  4. Filter for needs (and optional wants)

  5. Map to application domain (OUTMAP)

  6. Provide attributes in to subprocess environment

  7. Comply with obligations (large part of this responsibility rests with the subprocesses and can not be automatically enforced)

N.B. For an attribute to be available, four conditions must be met: (i) it must actually exist, (ii) it must be specified in NEED (or WANT, if no absolute guarantee of availability is necessary), (iii) it must pass INMAP, and (iv) it must pass OUTMAP or purpose specific map like PEPMAP.

4.1 Attribute Broker Configuration Directives

*** This is provisory specification

The Attribute Broker configuration in Apache set-up is per <Location> directive. Different Locations within same server can have different needs.


  <Location /protected>
  ZXIDConf "NEED=CN$GUI$40000000$none$ext"
  ZXIDConf "NEED=age$adult-content$100000$log-upon-sso,report-to-dashboard-if-avail$ext"
  ZXIDConf "WANT=birthday$horoscope$40000000$log-upon-sso,must-report-to-dashboard$ext"
  ZXIDConf "WANT=street,l,st,zip,c$ship$40000000$log-upon-sso,report-to-dashboard-if-avail$ext"

4.1.1 NEED specification

NEED specification expresses attributes that are required for the application to work. Attribute names are in the Common Namespace (often same as subprocess environment application namespace). Inavailability of the attributes aborts application processing.


Names of attributes (comma separated list) needed by subprocess environment


The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined. Special value "reset" clears previous need configuration.


The data retention policy that will be applied to these attributes if they are received. Specific enumerators or language are still To Be Defined. The example illustrates retention in seconds.


The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still TBD.


Extension fields to describe attribute policies in more detail.

4.1.2 WANT specification

WANT specification expresses attributes that are optional, but useful, for the application. Inavailability of the attributes may cause reduced application functionality or the application querying the missing attributes directly from the user. WANT specification has same syntax as NEED specification. Inavailability of the attribute has no consequence or may cause default to be supplied.


Names of attributes (comma separated list) needed by subprocess environment. If star (*) is specified, all available attributes are requested. ((This
 should not be used light heartedly. Much better to spell out explicitly the
 attribute requirements so that proper CARML description can be made.))


The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined.


The data retention policy that will be applied to these attributes if they are received. Specific enumerators or language are still To Be Defined.


The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still TBD.


Extension fields to describe attribute policies in more detail.


Optional default value to use in case the attribute is not available.

4.1.3 ATTRSRC specification

The Single Sign-On is an implicit Attribute Source and need not be specifically listed. The attribute namespace will be IdP's Entity ID.

N.B. As of Sept 2009, the SSO source is the only one implemented.

Attribute Source (ATTRSRC for short) specification indicates a potential source of attribute data and the mechanics for retreiving them. Each attribute originating from a determined source is in namespace of that source (source namespace). This avoids attribute naming conflicts and provides for clean attribute renaming framework. If an attribute is not renamed, then it is passed to the common namespace by just dropping the namespace prefix.


Namespace string assigned to this attribute source.


List of attributes available from this source


Weighting factor (integer) determining the prioirity of this source. Less indicates higher preference.


Typically URL for contacting the source, or special value "reset" to clear the list and start building anew.


Reference to AAPML declaration about policies applying to this attribute source


Description of additional policies applying to this attribute source



In a Web Service call, on Web Service Provider's side, the implicit attribute sources include

4.1.4 INMAP specification

INMAP specification provides for various input attribute renaming and input attribute value decoding operations. It is a semicolon separated list of stanzas, where stanza components are separated by dollar signs. Multiple INMAP specifications are additive, but the INMAP list can be cleared with special stanza with reset rule.


Source namespace of the attribute


Attribute name in the source namespace


Attribute name in common namespace (if omitted, same as +A+)


transformation rule:


Just renames the attribute. Value is passed intact. Default.


Deletes the attribute.


Decode the attribute value accoring to Feide (Norway) rules. Also rename if +b+ provided.


Encode the attribute value accoring to Feide (Norway) rules. Also rename if +b+ provided.


Decode the attribute value accoring to safebase64-inflate rules ([RFC3548], [RFC1951]). Also rename if +b+ provided.


Encode the attribute value accoring to deflate-safebase64 rules ([RFC1951], [RFC3548]). Also rename if +b+ provided.


Decode the attribute value according to safebase64 [RFC3548] rule (NZ). Also rename if +b+ provided.


Encode the attribute value according to safebase64 [RFC3548] rule (NZ). Also rename if +b+ provided.


Wrap the attribute in a SAML2 assertion


Wrap the attribute in a X509 AC attribute certificate


Obtain the value of the attribute from file specified in the ext field


Combination of a7n and feideenc


Combination of a7n and def-sb64


Combination of a7n and sb64


Combination of x509 and feideenc


Combination of x509 and def-sb64


Combination of x509 and sb64


Combination of file and fedieenc


Combination of file and def-sb64


Combination of file and sb64


Special pseudo rule that clears previous map configuration. (e.g. reset)


Extended argument that may be used by some rules.

The order of evaluation of INMAP stanzas is not defined, therefore it is not avisable to include same attribute in two stanzas as only one would fire.

SSO derived attributes


Concatenation of affid and idpnid like: "affididpnid".

4.1.5 OUTMAP specification

OUTMAP specification provides for various attribute renaming and value encoding operations just before passing attributes to the subprocess environment (i.e. what CGI scripts see). Syntax and available operations are the same as for INMAP.


4.1.6 AAMAP specification

AAMAP specification is used by IdP Attribute Authority feature to decide whinc attributes from the .at files to include in the assertion. Unlike other MAP directives, AAMAP can not be placed in regular configuration. Instead it is looked for in .cf file in following paths (first found will be used):


The first allows per SP tweaking of what attributes are sent. The latter allows global policy to be set. In absence of either .cf file, the default is


which passes all attributes excapt for idpsesid (passing idpsesid would cause privacy loss as it can be used as correlation handle).

5 ZXID XACML PEP (and local PDP)

Terminology: PEP = Policy Enforcement Point, PDP = Policy Decision Point, XACML = XML Access Control Markup Language, an OASIS standard architecture and protocol for making authorization decision.
Important: You need a functioning XACML PDP (Policy Decision Point to use this functionality. zxididp includes a PDP that always returns "Permit", unless role is "deny" - you need to acquire and configure a real PDP, such as commercial (e.g. Axiomatics or Symlabs XACML PDP) or a third party open source PDP (e.g. PERMIS or Sun).

The attributes gathered by the Attribute Broker phase are available for authorization decisions. The local authorization is applied before, and after, the XACML authorization, if any.

5.1 Local PDP Authorization Functionality

The authorization module can authorize access locally based on

Local PDP specifications have format as follows

  LOCALPDP_ROLE_PERMIT=role,role         # Whitelist of roles
  LOCALPDP_ROLE_DENY=role,role           # Blacklist of roles
  LOCALPDP_IDPNID_PERMIT=idpnid,idpnid   # Whitelist of permitted users
  LOCALPDP_IDPNID_DENY=idpnid,idpnid     # Blacklist of denied users

If whitelist exists, anyone not listed is denied. If blacklist exists, anyone listed is denied. If both lists exist, then white is applied first and black then, i.e. blacklist overrides whitelist.

The lists accumulate over default configuration and repeated instances of the configuration directive. The special value "reset" can be used to reset any of the lists.

The local PDP authority is consulted at all PEPs, i.e. at SSO, RQOUT1, RQIN2, RSOUT3, and RSIN4.

N.B. It is expected that local PDP will grow in ritchness to address additional common cases, but if you have complex requirements, you should be using an external PDP.

5.2 Configuring XACML PEP for Single Sign-On

XACML2 PEP (client) functionality allows an external XACML2 PDP (server) to be queried for the authorization decision, permitting Single Sign-On to happen. The attributes gathered by the Attribute Broker phase are available for formulating the XACML request.

Since the XACML PDP may expect attributes names differently from the Common Namespace, an additional mapping directive, PEPMAP, is provided. It works in a manner similar to OUTMAP in that it extracts and filters attributes from the common pool. The source namespace field is used for indicating whether the attribute is

Multiple PEPMAP stanzas can appear as separate PEPMAP declarations, which are cumulative, or they can be put on single PEPMAP separated by semicolon. Within stanzas the fields are separated by semicolons:


The fields, such as rule are discussed in detail in description of INMAP, above.

5.3 Configuring XACML PEPs for Web Service Calls

ZXID implements a four points of control PEP model for web service calls. This is adopted from the TAS3 project.

Fig-2: Four PEP Control Points on the Web Service call path.

Each control point extracts the attributes from the common namespace of the pool using directives similar to PEPMAP as follows:


Request outbound enforement point on Web Service Client (WSC) side, see (1) in the diagram. Typically this enforcement point can be used to control whether WSC is allowed to talk to the Web Service Provider (WSP). It can also be used to control whether the data whose submission to WSP is contemplated, is allwed to leave the WSC, and if so, under which obligations or usage directives. Finally, this control point can be used to formulate pledges about which obligations the WSC is willing to honour. Again, such pledges are passed as a usage directive on the wire.


Request inbound enforcement point on WSP side, see (2) in the diagram. This is the main PEP that filters the requests "at the gate" before they get in. When most people think about a PEP, they think about this type of PEP. The PEPMAP_RQIN can implement tests on requesting identity attributes, target identity (resource owner) attributes, obligations requirements and obligations pledges conveyed in the usage directives, as well as the actual operation contemplated and data in the operation.


Response outbound enforcement point on WSP side, see (3) in the diagram. This PEP is in position to filter outbound data before it is returned to the WSC. It can also attach obligations to this data, as usage directives.


Response inbound enforcement point on WSC side, see (4) in the diagram. This PEP is mainly useful for checking whether the usage directives and obligations attached to the data are acceptable. If not, the data can be rejected at this point.

5.4 Configuring UsageDirectives, including obligations pledges and requests

All ID-WSF messages, requests and responses, are able to carry a UsageDirectives SOAP header, but unfortunately the content and meaning of this header is not well specified (as of 2010). In essence, the header can carry obligations imposed on the sent data, or it can carry a pledge to respect obligations if data is returned. While Liberty ID-WSF UsageDirective has no way of separating between the two cases, we can make the distinction at the level of the XACML <xa:Oblication> tag's FullfillOn XML attribute.

6 Full Configuration Option Reference

This section is generated based on comments in zxidconf.h and is updated periodically. See zxidconf.h for authorative definitions. See also zxid.h for struct zxid_conf which is the internal runtime structure capturing these options.

Most of the configuration options can be set via configuration file /var/zxid/zxid.conf or using -O command line flag(s). In config file or on command line you should omit the ZXID_ prefix and use attribute=value syntax separated by newlines or & characters (the parser implements CGI query string syntax with extension that also is accepted as separator).

N.B. The options marked as "(compile)" can not be set on command line or configuration file. They require a recompile.

6.1 Configuration Options

6.1.1 Compile time configuration enforcement

Whether configuration is entirely determined at compile time by this file or whether it is possible to use a config file or provide options on command line using -O flags (such as via shell script wrapper). When zxid is used as a library, it depends on application to call zxid_parse_conf(). Generally we recommend you leave these turned on (1).


(compile) (default: 1)


(compile) (default: 1)


Whether configuration is viewable from url o=d (default: 1)

6.1.2 ZXID configuration and working directory path

Where metadata cache and session files are created. Note that the directory is not hashed: you should use a file system that scales easily to oodles of small files in one directory. Say `make dir' to create the directory with proper layout. If you change it here, also edit Makefile.


(default: "c:/var/zxid/")


(default: "/var/zxid/")

6.1.3 SP Nickname for IdP User Interface

IMPORTANT: You should really configure this option. The nice name may be used by IdP user interface to refer to the SP. It is usually a short human readable name or description. It will also appear in metadata as Organization/OrganizationDisplayName


(default: "ZXID configuration NICE_NAME: Set this to describe your site to humans")

6.1.4 Web Site URL - root of EntityID

IMPORTANT: Failure to config this option may block zxid from operating. URL for most zxid operations. It must end in whatever triggers the ZXID functionality in the web server. The hostname and port number should match the server under which zxid CGI is accessible. N.B. There is no explicit way to configure Entity ID (Provider ID) for the zxid SP. The Entity ID is always of form ZXID_URL?o=B, for example 

(default: "")

6.1.5 Override standard EntityID Construction

The best practise is that SP Entity ID is chosen by the SP (and not forced upon SP by IdP). In ZXID this is done by setting ZXID_URL, see above. However, should you have to work with an obstinate IdP that refuses to follow this best practise, you can use this option to manually set the Entity ID. Not following the best practise breaks automatic metadata exchange (Auto-CoT). Recommended value: leave as 0 so that Entity ID is formed from ZXID_URL


(default: 0)

6.1.6 Allow omission of o=B, i.e. make the URL be the entity ID. */


6.1.7 Illadviced ACS URL Hack

Sometimes an illadvised authority may impose to you Assertion Consumer Service URL, this URL happens to be different than ZXID uses, and you do not have political leverage to change these decisions. In those times you can use this hack to try to map the imposed URL to the one that works in ZXID. Normally you should register at IdP to use the ZXID default URLs (easiest way to do this is to use metadata). This only works in mod_auth_saml.


(default: 0)


(default: 0)

6.1.8 Additional Metadata Fields. Safe to leave all as NULL.

The LOCALITY, STATE, and COUNTRY will appear in certificates so you may want to set them to sensible values.


(default: "Unspecified ORG_NAME conf variable")


(default: 0)


(default: "Lisboa")


(default: "Lisboa")


(default: "PT")


(default: 0)


(default: 0)


(default: 0)


(default: 0)

6.1.9 If set (by default this is always set when URL is set, you have to

explicitly unset it if you do not want it), causes IdP to include fedusername attribute in the assertion. The value of this attribute will be the (persistent) nameid followed by @ sign and this suffix, for example:

The fedusername attribute is a helper for the SP web sites that are fixated on the notion of needing a username and/or requiring the username to look like an email. By packaging the psedonym this way it is easy to get them to work with minimal modification. N.B. Although it looks like an email address, it is not. Do not try sending mail to it (unless you hack your mailserver to understand it).


(default: "set-this-or-url-to-site-dependent-value")

6.1.10 IdP Attribute Generation Options

0x01 If fedusername is generated, also generate

      urn:oid: (aka ~eduPersonPrincipalName~)

(default: 0x01)

6.1.11 Common Domain Cookie URL

URL for reading Common Domain Cookie. It must end in "zxid". The hostname and port number should match the server under which zxid CGI is accessible. Specifying empty CDC_URL disables CDC check in zxid_simple() API.


CDC disabled (default: "")

6.1.12 CDC designated IdP Handling

How to handle CDC designated IdP. See zxid.h for explanation of constants.



6.1.13 Metadata Fetching Options (Auto-CoT)

Following four boolean configuration options control how metadata is obtained. The metadata can be in a cache (by default directory /var/zxid/cot) or it can be fetched "on the fly" using the well known location (WKL) method.


controls whether fetching is performed. This necessitates that ZXID was linked with libcurl. If you do not enable fetching, you will need to populate the cache manually, perhaps by using a web browser to fetch the meta data xml files from well known location URLs (or other URLs if you know better). Or you could use or zxcot(1) tool.

N.B. Even if fetching is enabled, the fetch can still fail due to network connectivity issues or due to other end not supporting it.


controls whether ZXID will write the metadata to the on-disk cache. This requires ZXID_MD_FETCH to be enabled and the file system permissions of the cache directory (e.g. /var/zxid/cot) to allow writing.


controls whether cache will be checked before fetching is attempted. If cache misses, ZXID_MD_FETCH governs whether fetch is tried.


If true, metadata is obtained from cache if fetch was disabled or failed.

If you want to control manually your CoT (e.g. because human process is needed to verify that all the paperwork is in place), set MD_FETCH to 0.

If you want as automatic operation as possible, set all four to 1.


The Auto-CoT ena option (default: 1)


(default: 1)


(default: 1)


(default: 1)

6.1.14 Whether to load CoT cache from a file containing the concatenated metadata

of the Circle of Trust. Some real world federations distribute their metadata this way. Setting this to 0 disables the feature (default). Setting this to file name or path enables this feature.


(default: 0)

6.1.15 Automatic Self-signed Cert Generation (Auto-Cert)

If ZXID does not find one of the certificate plus private key pairs it needs to operate, it will generate automatically a self-signed certificate and private key and populate it to the assigned place. The certificate will be valid until the end of the Unix epoch (2037). If you do not want this to happen, you should disable this option and install the certificate - private key pairs manually to


Hint: you can use same certificate - private key pair for all purposes. Just copy the file.


(default: 1)

6.1.16 Authentication Request Signing

Whether AuthnReq is signed SP (controls both metadata and actual behavior).


(default: 1)

6.1.17 Assertion Signing

Whether SP insists that SSO assertions are signed. Affects metadata. The actual insistence on signing is controlled by ZXID_NOSIG_FATAL, far below. Boolean. Recommended value: 1.


(default: 1)

6.1.18 SSO SOAP Message Signing

Whether SOAP messages for ArtifactResolution, SLO, and MNI are signed. Whether responses are signed as well.


(default: 1)


(default: 1)

6.1.19 IdP Signing Options

Which components should be signed by IdP in SSO Response and Assertion. Bit mask:

  0x01  Assertion should be signed (default and highly recommended)
  0x02  The surrounding Response element should be signed
  0x03  Both Assertion and Response are signed. 

(default: 0x01)

6.1.20 NameID Encryption

Whether SLO and MNI requests emitted by ZXID will encrypt the NameID (on received requests ZXID accepts either plain or encrypted automatically and without configuration).


(default: 0x0f)

6.1.21 Assertion Encryption in POST

Whether to encrypt assertions when using POST bindings.


(default: 1)

6.1.22 When producing EncryptedID, EncruptedAssertion, or EncryptedAttribute,

how is the EncryptedKey stored relative to EncryptedData

0x00 Sibling, without Recipient hint (interops with many commercial implementations and Shibboleth Sept 2010) 0x01 Sibling, with Recipient hint (interops with many commercial implementations and Shibboleth as of August 2010) 0x20 Nested method, i.e. EncryptedData/KeyInfo/EncryptedKey (interops with all versions of Shibboleth and many others)


SAML2 specs fail to say which approach is preferred, therefore both approaches are valid. In reading messages ZXID automatically understands both. This option only controls how outbound messages are generated so that others can understand them (ideally they would autodetect so we would not need this option).


(default: 0x20)

6.1.23 Controls whether new fedarations can be created during discovery. */


/*(c) Controls the default NameID Format for discovery: p=persistent, t=transient


(default: 'p')

6.1.24 Controls whether assertions emitted by discovery are encrypted.

It is highly recommended to encrypt the assertions to avoid man-in-the-middle attacks.


(default: 1)

6.1.25 Control how many levels of bootstraps are added to assertions. Normally

only first level is added, i.e. all available bootstraps are embedded in the assertion, but the assertions of the embedded bootstraps only get discovery bootstrap. 2 would cause the assertions of the first order bootstraps to have further bootstraps embedded, etc. Since bootstrap generation tends to be expensive and wasteful, you should use discovery instead and leave BOOTSTRAP_LEVEL set to 1.


(default: 1)

6.1.26 WSC Signing Options

Which components of a web service request should be signed by WSC Bit mask:

  0x01  SOAP Headers
  0x02  SOAP Body
  0x03  Both Headers and Body are signed. 

(default: 0x03)

6.1.27 WSP Signing Options

Which components of a web service response should be signed by WSP Bit mask:

  0x01  SOAP Headers
  0x02  SOAP Body
  0x03  Both Headers and Body are signed. 

(default: 0x03)

6.1.28 Command that will be executed by zxidwspcgi to respond to a web service call. */

#define ZXID_WSPCGICMD "./"

/*(c) Bit length of identifiers, unguessability How many random bits to use in an ID. It would be useful if this was such that it produces nice unpadded base64 string, i.e. multiple of 24 bits. Longer IDs reduce chances of random collision (most code does not check uniqueness of ID) and may increase security. For security purposes 144 bits is probably good enough. The unguessability of ID has security implications, among others, in session IDs. You may want to use less than 144 bits if your application could benefit from shorter IDs (e.g. you target browsers with length constrained URLs) and does not need to be secure against attacks with government level resources. E.g: 24 bits == 3 bytes == 4 safe_base64 chars,

      48 bits ==  6 bytes ==  8 safe_base64 chars,
     120 bits == 15 bytes == 20 safe_base64 chars,
     144 bits == 18 bytes == 24 safe_base64 chars 

(compile) (default: 144)


used for static buffer allocation (compile) (default: 168)

6.1.29 True randomness vs. pseudorandom source

Whether true randomness is obtained. 0=use OpenSSL RAND_pseudo_bytes(), which usually uses /dev/urandom 1=use OpenSSL RAND_bytes(), which usually uses /dev/random

Although true randomness may be more secure, it is operationally problematic because if not enough randomness is available, the system will block (stop) until enough randomness arrives. Generally true randomness is not feasible in a server environment unless you have a hardware random number generator.


(compile) (default: 0)

6.1.30 Session Archival Directory

If set to a string, indicates a file system directory to which dead sessions are moved (sessions are files). This directory must be on the same file system as active session directory, usually /var/zxid/ses, for example /var/zxid/oldses. You may want to archive old sessions because they contain the SSO assertions that allowed the users to log in. This may have legal value for your application, you may even be required by law to keep this audit trail.

If set to 0, causes old sessions to be unlink(2)'d.


0=Remove dead sessions. (default: 0)

6.1.31 Session cookies.

For original Netscape cookie spec see: (Oct2007)

If SES_COOKIE_NAME is nonempty string, then zxid_simple() will look for said cookie and use it as session ID. It will also attempt to set a cookie by that name when new session is created (but this may rely on some support in the calling app, generally the need to set a cookie is expressed by presence of setcookie attribute in the LDIF entry. setcookie specifies what should appear in the Set-Cookie HTTP header of HTTP response).


(default: "ZXIDSES")

6.1.32 Local user account management.

This is optional unless you require IdP initiated ManageNameID requests to work. Local user account management may be useful on its own right if your application does not yet have such system. If it already has, you probably want to continue to use the application's own system. Local accounts are stored under /var/zxid/user/SHA1


(default: 1)

6.1.33 Mini IdP

Whether limited IdP functionality is enabled. Affects generated metadata.


(default: 0)

6.1.34 IdP Proxying, i.e. IdP can be SP towards another IdP.

  #define ZXID_IDP_PXY_ENA 0

6.1.35 Identity Mapper and People Service

Whether limited Identity Mapper and People Service functionality is enabled. For this to work, IDP_ENA=1 is needed.


(default: 0)

6.1.36 Mini Authentication Service

Whether limited Authentication Service functionality is enabled. Please note that the AuthenticationService impmenetation at present (2010) is incomplete and fails to properly authenticate and authorize the caller system entity, i.e. anyone who knows a username and password can call it.


(default: 0)

6.1.37 Dummy PDP

Whether limited PDP functionality is enabled.


(default: 1)

6.1.38 IdP Insitence on Signed AuthnReq

Must AuthnReq be signed (controls both IdP metadata and actual behavior, i.e. the check).


(default: 1)


(compile) (default: 1024)

6.1.39 Logging Options

See zxid-log.pd for further explanation. Generally you need error and activity logs to know yourself what is going on. You need the issue logs to know whether other's claims towards you are justified. You need the rely logs to hold others responsible. The bits of the value are as follows 0x00 Don't log. 0x01 Log enable 0x06 Signing options

        0:: no signing (Px)
        2:: sha1 MD only (Sx)
        4:: RSA-SHA1 (Rx)
        6:: DSA-SHA1 (Dx)

0x08 reserved 0x70 Encryption options

        0x00:: no encryption (xP)
        0x10:: zip-base64 (xZ)
        0x20:: RSA-AES (xA)
        0x30:: RSA-3DES (xT)
        0x40:: Symmetric AES (xB)
        0x50:: Symmetric 3DES (xU)
        0x60:: reserved
        0x70:: reserved

0x80 reserved

N.B. Every encryption and signature has computational cost so be sure to factor this in when doing benchmarks - or disable log enc and sign when performance is at premium.

Log signing may help you to argue that log evidence was (not) tampered with. The private key for signing must be available in /var/zxid/pem/logsign-nopw-cert.pem

Log encryption may help to keep the logs confidential. For RSA modes the public key for encryption must be available in /var/zxid/pem/logenc-nopw-cert.pem. For symmetric encryption the key is the sha1 hash of file /var/zxid/pem/logenc.key All modes, except for 0, also RFC1951 zip compress the log line and safe-base64 encode the result of the encryption.


(default: 0x00)


(default: 0x01)


(default: 0x05)


(default: 0x21)


(default: 0x25)


Log errors to /var/zxid/log/err (default: 0x01)


Log activity to /var/zxid/log/act (default: 0x01)


Log each issued assertion to /var/zxid/log/issue/SHA1/a7n/asn (default: 0x01)


Log each issued PDU to /var/zxid/log/issue/SHA1/msg/asn (default: 0x01)


Log each received assertion to /var/zxid/log/rely/SHA1/a7n/asn (default: 0x01)


Log each received PDU to /var/zxid/log/rely/SHA1/msg/MSGID (default: 0x01)


(default: 0x00)


(default: 0x25)


(default: 0x23)


(default: 0x45)


(default: 0x41)


(default: 0x11)

6.1.40 Choice of log given Error or Action

Each operation has its status code and generally those lines that indicate successful status (or intermediate status like "continue" or "redirect") are considered normal activity. However, you may want to consider carefully whether signature failure in assertion or message disqualifies an operation as "activity". One approach is to simply log everything (errors and all) to activity log and rely on some log analysis software to flag the errors.


Log errors to /var/zxid/log/act (in addition to err) (default: 1)


Log actions to /var/zxid/log/err (in addition to act) (default: 1)


Log line with signature validation error to /var/zxid/log/err (default: 1)

6.1.41 Log level for activity log.

0 = Only essential audit relevant events are logged. Note that

    there is no way to turn off logging audit relevant events.

1 = Audit and external interactions 2 = Audit, external interactions, and significant internal events 3 and higher: reserved for future definition and debugging


(default: 2)

6.1.42 Per user activity logging.

This option enables logging in /var/zxid/idpuid/UID/.log some key events such as authentication, SSO, and SLO.


(default: 1)

6.1.43 Assertion validation options.

These MUST all be turned on (and assertions signed) if you want to rely on assertions to hold the other party liable.


Signature validation error is fatal (prevents SSO) (default: 1)


Missing signature is fatal (prevents SSO) (default: 1)


Message layer signature (e.g. SimpleSign) is sufficeint when assertion signature is missing. (default: 1)


Whether AudienceRestriction is checked. (default: 1)


Whether NotBefore and NotOnOrAfter are checked (default: 1)


Whether duplicate AssertionID is considered fatal. (default: 1)


Whether duplicate MessageID or message is considered fatal. (default: 1)


Whether failure to correlate RelatesTo to MessageID, or total lack of RelatesTo, is considered fatal. (default: 1)

6.1.44 Web service request and response validation options. For the token

in the request, the assertion validation options apply.


Missing Security/Signature is fatal. (default: 1)


Missing Security/Timestamp is fatal. (default: 1)

6.1.45 XML canonicalization compatibility kludges

  #define ZXID_CANON_INOPT 0

6.1.46 Shibboleth compatibility

Shibboleth 2.1.5 IdP miscanonicalizes by ignoring InclusiveNamespaces/@PrefixList, yet it still supplies such list. The miscanonicalization leads namespaces missing. This has been reported to Scott Cantor as of 20101005


(default: 0x01)

6.1.47 XML encoding optimizations.

1 = optimize close tag of empty elements as <ns:foo/>


(default: 1)

6.1.48 SOAP Envelope validation options. In well configured and

bug free environment, you should not need any of these options. Turning them on will reduce security as validations are not made.

0x01 Skip response header validation entirely, see zxid_wsc_valid_re_env()


(default: 0x00)


(default: 0x01)

6.1.49 Time Slop

Because clock sychronization amoung the servers in the CoT is unlikely to be perfect, not to speak of timezone misconfigurations and the dreaded officially introduced time errors (e.g. daylight "savings" time), you can configure some slop in how the timeout is evaluated. For production use something like 60 seconds could be a good value. 3600 = 1 hour, 86400 = 1 day. All servers of CoT MUST use GMT (aka UTC), not local timezones. You can synchronize clocks with ntpdate (see man ntpdate). Slop is used in assessing validity of assertions as well as message timestamps. Time skew allows our end to lie about the time, e.g. if we are in GMT, but the other end is not and therefore we are rejected. Note that the time skew is same for all other ends, therefore this is not really a good solution. Only good solution is to have all servers synchronized to GMT (UTC) as the specs say. While flexibility is nice, there is enough rope here to hang yourself so don't do that. :-)


Number of seconds before that is acceptable. (default: 39600)


Number of seconds after that is acceptable. (default: 7300)


Timeskew, in seconds, for timestamps we emit. (default: 0)


Time To Live for IdP issued Assertions (default: 3600)

6.1.50 Redirect to Content

Should explicit redirect to content be used (vs. internal redir). With internal redirect there is one over-the-wire transaction less, but the URL appears as whatever was sent by the IdP. With explicit (302) redirect the URL will appear as the true content URL, without the SAML SSO goo.


(default: 1)

6.1.51 ID-WSF SOAP Call parameters

  #define ZXID_MAX_SOAP_RETRY 5  /* Maximum retries due, e.g., EndpointMoved */

6.1.52 Session Management Trigger Suffix

In mod_auth_saml the URL ending that triggers session management (e.g. SLO MNI).

6.1.53 Attribute Prefix

In mod_auth_saml the prefix (potentially empty) for attributes brought into environment.


(default: "SAML_")

6.1.54 Fake Basic Auth by generating REMOTE_USER

In mod_auth_saml generate REMOTE_USER subprocess environment variable.


(default: 1)

6.1.55 Query String if None Given

  #define ZXID_DEFAULTQS ""   /* Default Query String used by mod_auth_saml for protected page */

6.1.56 Anonymous can see protected content

If ANON_OK is set and matches prefix of the local URL, SSO failure does not block protected content from being shown. While this usually is a security problem, in some circumstances you may want to show error message or nonpersonalized content from the application layer. If application checks that the SSO really happened, then there is no security problem - the responsibility is application's. Typically ANON_OK=/dir/ is used with IsPassive (fp=1) to implement personalization if user already has session, but allow the user to access page anonymously without logging in if he does not have session.


(default: 0)

6.1.57 Required Authentication Context Class Ref.

This can be used to ensure that the IdP has authenticated user sufficiently. In some cases this can trigger step-up authentication. Value should be dollar separated string of acceptable authn context class refs, e.g. "" If step-up authentication is triggered, you need to ensure the fa query string argument of the IdP selection page also requests the desired authentication contrext class reference. If not specified, then any authentication context is acceptable.


(default: 0)

6.1.58 IdP: Authentication Context Class Ref for Passwords

What authentication context IdP issues for password authentication. The problem here is that ZXID does not know whether transport layer is TLS (assumed). If it is not, you should configure this to be "urn:oasis:names:tc:SAML:2.0:ac:classes:Password" or you can configure this according to your IdP operational policies.


(default: "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport")

6.1.59 IdP preference for ACS

If SP does not manifest preference regarding the binding for Assertion Consumer Service, then this IdP preference is used, unless SP metadata indicates it can not support this binding, in which case the first ACS from metadata is used.


(default: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST")

6.1.60 List of unsuppressible attributes. Every SSO and discovery will include

these attributes, if they are defined for the user. Comma separated list.


(default: "zxidvers,zxidloa")

6.1.61 Attribute Broker definitions

  #define ZXID_NEED "idpnid,affid,role$undisclosed,log$400000$$"
  #define ZXID_WANT "*,authnctxlevel,sesid,setcookie,cookie,rs,cn$undisclosed,log$400000$$"
  #define ZXID_ATTRSRC ""
  #define ZXID_INMAP ""
  #define ZXID_OUTMAP ""
  //#define ZXID_SUPPRESS ""

6.1.62 Policy Decision Point (PDP) URLs

If PDP_URL is set, then the indicated PDP will be consulted in the end of SSO, i.e. by zxid_simple(). PDP_CALL_URL is used if zxid_az() family of functions are called. If PDP_CALL_URL is not set, but PDP_URL is set, the PDP_URL value will be used by zxid_az(). If you always want to explicitly call zxid_az() and do not want zxid_simple() to make implicit calls to PDP, just set PDP_CALL_URL and leave PDP_URL as 0.


(default: 0)


(default: 0)

6.1.63 Trust Policy Decision Point (PDP) URL If TRUSTPDP_URL is set and

appropriate discovery options are passed, then the indicated PDP will be consulted during discovery processing to determine if a service should be returned. Default value 0 prevents such processing.


(default: 0)

6.1.64 Enable discovery and web service call to perform TAS3 Credentials

and Privacy Negotiation call. For this to work, there must be discovery registration for service type urn:tas3:cpn-agent as well.


(default: 0)

6.1.65 Kludgy options for AZ debugging and to work-around bugs of others.

0x01: prevent WS-Security header in SOAP XACML requests.


(default: 0)

6.1.66 Which version of XACML to speak

e.g. "2.0" or "2.0-cd1" or "xac-soap"

  #define ZXID_XASP_VERS "2.0"

6.1.67 What to pass in XACML PolicySetIdReference when calling PDP

Empty means not to pass PolicySetIdReference.


*** implement (default: "")

6.1.68 Specify common XACML Attributes for PEPs in format nsArulebext (compile)

The ZXIDCOMMAP can only be specified at compile time. At run time each map has to be specified separately, sorry. The order of processing rules has not been fixed yet, but currently (Feb2011/R0.76) the first rule is processed last, e.g. the "env*" stanza that appears as first below causes all other attributes to be considered environment attributes. See documentation for INMAP for syntax of the stanzas.


(default: "env*;subjidpnidrenameurn:oasis:names:tc:xacml:1.0:subject:subject-id;subjurn:oasis:names:tc:xacml:1.0:subject:subject-id;subjurn:oid:;subjurn:oid:;subjeduPersonAffiliation;subjeduPersonEntitlementsubjrole;rsrcrsrenameurn:oasis:names:tc:xacml:1.0:resource:resource-id;rsrcurn:oasis:names:tc:xacml:1.0:resource:resource-id;actActionrenameurn:oasis:names:tc:xacml:1.0:action:action-id;acturn:oasis:names:tc:xacml:1.0:action:action-id;envZXIDPEPvers;cookiedel;setcookiedel")

6.1.69 Specify XACML Attributes for SSO / frontchannel request in PEP

in format nsArulebext


6.1.70 Specify XACML Attributes for Request Outbound PEP at WSC (1)

in format nsArulebext


(default: ZXID_COMMAP)

6.1.71 Specify XACML Attributes for Request Inbound PEP at WSP (2)

in format nsArulebext


6.1.72 4.1.66) Specify XACML Attributes for Response Outbound PEP at WSP (3)

in format nsArulebext


(default: ZXID_COMMAP)

6.1.73 Specify XACML Attributes for Response Inbound PEP at WSC (4)

in format nsArulebext


  //#define ZXID_XACML2_SUBJ  "idpnid=$idpnid&role=$role"
  //#define ZXID_XACML2_RSRC  "URL=$URL"
  //#define ZXID_XACML2_ACT   "Action=$Action"
  //#define ZXID_XACML2_ENV   "ZXID_PEPVers"

6.1.74 Default AAMAP

to pass all attributes (except dangerous ones) through. idpsesid is blocked on grounds of being a sessionwide correlation handle.


(compile) (default: "*;idpsesiddel")

6.1.75 Whitelists and blacklists for the primitive SSO local PDP

Comma separated lists.

  #define ZXID_LOCALPDP_ROLE_PERMIT 0   /* Whitelist of roles (empty: anything goes) */

Blacklist of roles (default: "local_deny")


Whitelist of permitted users (empty: anything goes) (default: 0)


Blacklist of denied users (default: "denynid")

6.1.76 Obligations we are willing to respect

(unless an explicit UsageDirectives header is specified by caller), require, generate, and accept.


String: WSC pledged obligations in SOL notation (default: 0)


String: WSP required obligations in SOL notation (default: 0)


String: WSP obligations emitted on resp (default: 0)


String: WSC acceptable obligations in SOL notation (default: 0)

6.1.77 Simple API HTML customization.

These allow simple branding and customization. If these options are not enough for you, consider simply rendering your own forms.

6.1.78 Whether to show more technical fields in the GUI. Normally they

are hidden and POST profile is used


(default: 0)

6.1.79 Body tag for some old ZXID generated pages

Edit this to change the colors. But usually you should be editing stylesheet or template.


(compile) (default: "<body bgcolor=white>")

6.1.80 Path for Template for IdP Selector Page

This template is used by Service Provider to render the SP "login" screen which really is the IdP selection screen (as the authentication login is done on IdP side).


(default: "idpsel.html")

6.1.81 Template for IdP Selector Page

Used if the path does not work. This is really meant to be the last resort.


(default: "<title>ZXID SP SSO: Choose IdP</title>"\)

6.1.82 Choose the method for rendeing IdP list.

0 = popup menu 1 = buttons 2 = branded image buttons (not implemented as of 20100922)


(default: 0)


(default: 0)


(default: 1)


(default: 2)

6.1.83 IdP Selector Page URL

If the IDP_SEL_TEMPL_FILE or IDP_SEL_TEMPL, above, is not sufficient for your customization needs, you can provide URL to page of your own design. This page will receive as query string argument the relay state. 0 (zero) disables.


(default: 0)

6.1.84 If user clicks "Create New User" he is redirected to this page.

  #define ZXID_NEW_USER_PAGE 0

6.1.85 If user clicks on recover password, redirect to this page.


(default: 0)

6.1.86 If attribute selection is desired during SSO, redirect to this page.

  #define ZXID_ATSEL_PAGE 0

6.1.87 Authentication Page URL

If the template customization options are not sufficient, you can provide URL to page of your own design. If set, takes priority over AN_TEMPL_FILE. 0 (zero) disables.


(default: 0)

6.1.88 Path for Template for IdP Authentication Page

  #define ZXID_AN_TEMPL_FILE "an-main.html"

6.1.89 Template for IdP Authentication Page

Used if the path does not work. This is really meant to be the last resort.


(default: "<title>ZXID IdP: Authentication</title>"\)

6.1.90 Path for Template for POST profile page

  #define ZXID_POST_TEMPL_FILE "post.html"

6.1.91 Template for POST profile age

Used if the path does not work. This is really meant to be the last resort.


(default: "<title>ZXID Post Profile</title>"\)

6.1.92 Error Page URL

If the template customization options are not sufficient, you can provide URL to page of your own design. If set, takes priority over ERR_TEMPL_FILE. 0 (zero) disables.


(default: 0)

6.1.93 Path for Template for Error Page

  #define ZXID_ERR_TEMPL_FILE "err.html"

6.1.94 Template for Error Page

Used if the path does not work. This is really meant to be the last resort.


(default: "<title>ZXID: Error</title>"\)


(default: "<title>ZXID SP Mgmt</title><link type=\"text/css\" rel=stylesheet href=\"idpsel.css\"><body bgcolor=white><h1 class=zxtop>ZXID SP Management (user logged in, session active)</h1>")


(default: "<input type=submit name=gl value=\" Local Logout \"><input type=submit name=gr value=\" Single Logout (R) \"><input type=submit name=gs value=\" Single Logout (S) \">")


(default: "<input type=submit name=gt value=\" Defederate (R) \"><input type=submit name=gu value=\" Defederate (S) \">")


(default: "<div class=zxbot><a class=zx href=\"\"></a>, ")


(default: "</div>")

7 License

Copyright (c) 2006-2009 Symlabs (, All Rights Reserved. Author: Sampo Kellomäki (

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


8.1 Configuration Questions

  1. Q: In mod_auth_saml, what is the relation between ZXIDConf and httpd.conf?

    A: httpd.conf can contain ZXIDConf directives. Those directives are processed as if they came from /var/zxid/zxid.conf file (which is processed first, before and ZXIDConf directives), except that if you specify ZXIDConf "PATH=/your/path", this triggers reporcessing of the zxid.conf (from the new path).

  2. Q: In mod_auth_saml, what is the relation between the port in ZXIDConf and the port in the httpd.conf?

    A: The ports must agree. ZXID configuration must match the way the Apache layer is configured.

  3. Q: Multiple roles of same entity, acting as SP, WSC, and WSP for different services


    Part of what you are saying is that the service registration is WSC. This is rather confusing since the case is a WSP acting as a WSC of the Discovery Service. For the ClientLib thus far, I have chosen to think of service registration as a WSP to WSP. What is the downside to this approach?


    Service registrations can't be done WSP to WSP with any Liberty protocol (in fact, we don't define any such method of invocation as the invoking party is always a WSC for the intent of that message - there's no problem with a WSP in turn being a WSC of another service instance, just

    Right. You can don WSC role whenever convenient. There is nothing confusing about WSP of one service being WSC of another service. Perhaps the confusion would be avoided if everybody fully qualified their descriptions until common convention about less than fully qualified roles emerges.

    Entity E1, an ID-DAP WSP (primary role), will act as Discovery WSC (secondary role) to perform metadata registration. This same entity E1 will also have SP interface (another secondary role) which allows the user to trigger discovery association, again E1 acting in secondary role of Discovery WSC.

    No confusion as far as I can see.

8.2 Common Mistakes

  1. When I try accessing nothing happens!

    Assuming you have the web server correctly running, the most common gotcha is that zxidhlo has dynamic linking problem. See subsection "Dynamic Linking Problems", for explanation and resolution.

  2. Single Logout does not end the IdP session (i.e. IdP does not force you to supply password when you do SSO next time).

    Usual cause is that the management form (the one with the SLO buttons) does not have correct or any session ID. Do a view source on the the page and look for field called "s". The session ID is supposed to be extracted from the Single Sign-On result. For zxid_simple() you need to parse the returned LDIF and take the sesid. Pass that to zxid_fed_mgmt() as second argument.

  3. Login buttons do nothing.

    A possible cause is that the entity ID is not passed from the IdP selection form. If the form is using POST method, you must make sure you actually read the HTTP body and pass its contents to the zxid_simple() as the qs argument.

  4. The SP Login, a.k.a. IdP selection, page shows, but SSO does not work

    1. Your configuration does not match actual URL used to access the zxid system. For the zxidhlo family of examples you MUST edit the configuration string to match your situation. Watch out for domain name and port number.

    2. Connectivity issue prevents IdP from fetching metadata. Make sure your domain name is resolvable at IdP (e.g. add it to /etc/hosts). See also next point.

    3. IdP is not configured to get your metadata automatically. You have to configure your metadata to the IdP manually. How to do this depends on IdP product. Do not ask us.

    4. You supplied IdP URL that, in fact, is not the well known location for fetching IdP metadata. Or the IdP does not have well known location enabled. In the latter case you will need to install the IdP metadata manually . See [SAML2meta] section 4.1 "Publication and Resolution via Well-Known Location", p.29, for normative description of this method.

    5. Connectivity issue at web browser level. Make sure your web browser can resolve both SP and IdP domain names. Edit /etc/hosts as needed on the machine where the browser runs.

    6. Personal firewall blocks access. Check firewall set up on

      • browser machine

      • SP machine

      • IdP machine

  5. The SP Login, a.k.a. IdP selection, page does not show at all

    1. Connectivity issue at web browser level. Make sure your web browser can resolve both SP and IdP domain names. Edit /etc/hosts as needed.

    2. Personal firewall blocks access. Check firewall set up on

      • browser machine

      • SP machine

    3. You deployed the zxid in some other URL than you thought. Double check your webserver or servlet container configuration and be sure you understand where zxid is supposed to appear. Be sure you are editing the right configuration - some people run multiple web servers in their machine and get confused about which one actually is active on which port and where the configuration files are located.

    4. ZXID lacks execute permissions, dynamic link libraries are missing (use "ldd zxid" to check), or CGI permission setup prevents it from running. See previous bullet.

  6. Mystery configuration problems. Double check /var/zxid/zxid.conf or consider removing it if you do not understand what it does. Double check the conf string if using zxid_simple() interface.

  7. Writes a user...

    tb77f96c0 zxidmeta.c:352 zxid_get_ent_by_sha1_name zxid d Trying sha1_name(cot) open (vopen_fd_from_path): No such file or directory

    Did you create the /var/zxid hierarchy (make dir) and make sure your web user (nobody?) has write permission to the log directory? Or did you configure it to use some other directory than /var/zxid?

  8. What is this /var/zxidcot directory?

    It is supposed to be /var/zxid/cot

    When configuring PATH, did you forget trailing slash? E.g.

          "PATH=/var/zxid&URL=..."    # WRONG!
          "PATH=/var/zxid/&URL=..."   # Right
  9. If configuration appears to be prematurely truncated, then see if you need to adjust ZXID_MAX_CONF (default 4KB) in zxidconf.h and recompile.


"Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-core-2.0-os
"Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-profiles-2.0-os
"Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-bindings-2.0-os
"Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-authn-context-2.0-os
Cantor, Moreh, Phipott, Maler, eds., "Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-metadata-2.0-os
"Security and Privacy Considerations for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-sec-consider-2.0-os
"Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-conformance-2.0-os <!?!HEADER_TITLE

ZXID Configuration

>> <> #/var/zxid/zxid.conf IDP_SEL_START=ZXID SP SSO: Choose IdP

ZXID SP Federated SSO (user NOT logged in, no session)


Login Using New IdP

A new IdP is one whose metadata we do not have yet. We need to know the IdP URL (aka Entity ID) in order to fetch the metadata using the well known location method. You will need to ask the adminstrator of the IdP to tell you what the EntityID is.

IdP URL \n
IDP_SEL_OUR_EID=Entity ID of this SP (click on the link to fetch the SP metadata): IDP_SEL_TECH_USER=

Technical options

Create federation, NID Format: