<<if: ZXIDBOOK>>
<<else: >>Configuring ZXID 
################
<<author: Sampo Kellomäki (sampo@iki.fi)>>
<<cvsid: $Id: zxid-conf.pd,v 1.11 2010-01-08 02:10:09 sampo Exp $>>
<<class: article!a4paper!!ZXID Conf 02>>
<<define: ZXDOC=ZXID Configuration>>

<<abstract:

ZXID.org Identity Management toolkit implements standalone SAML 2.0 and
Liberty ID-WSF 2.0 stacks. This document explains configuration options
of ZXID.

>>

<<maketoc: 1>>

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 <<link:zxid-install.html: 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 <<link:zxid-cot.html: 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 <<link:../mod_auth_saml/mod_auth_saml.html: 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
-------------------

<<doc-inc.pd>>
<<htmlpreamble: <title>Configuring ZXID</title><link type="text/css" rel=stylesheet href="zx.css"><body><h1>Configuring ZXID</h1> >>

2 Configuring and Running
=========================
<<fi: >>

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. http://sp1.zxidsp.org:8080/sso?o=d

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
  PATH=/var/zxid/
  URL=https://sp.mydomain.com:8443/zxid
  NICE_NAME=My SP's human%0areadable name.
  ORG_NAME=My Company, Inc.
  ORG_URL=http://www.mycompany.be/
  LOCALITY=City of Industry
  STATE=Vlaams
  COUNTRY=BE
  #EOF

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):

   a. Install machine (instantiate) from reliable OS media, secure logins and
      have rigour in issuance of ssh credentials and sudo root rights
   b. Harden system by eliminating unnecessary services, applying patches, and
      configuring firewalls (decide which ports you use: typical is 443 for https)
   c. 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.
   d. Implement secure log collection, analysis, and storage (encrypt data at rest)
   e. Implement secure backup. Encrypt data at rest, e.g. using pgp(1). Do not
      forget key escrow.
   f. Register domain names and have certificates issued

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

   a. 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.

   b. Arrange for ZXID to be invoked. This could mean configuring
      zxidhlo, zxid-java.sh, or zxidhlo.pl 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

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

   b. Generate or acquire certificate

   c. 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=https://example.com/sso -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

  URL=http://sp1.zxidsp.org:8080/sso&PATH=/var/zxid/&PEP_ENA=0

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

  /var/zxid/
   |
   +-- 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 

NICE_NAME::  (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 .<<footnote: Actually there is: BARE_URL_ENTITYID option,
but that is an advanced topic and will not be discussed here.>> For
example

  https://sp1.zxidsp.org:8443/zxid?o=B 

URL::  (default: "https://sp1.zxidconf-you-should-set-URL-conf-variable-to-some-useful-and-site-dependent-value.org:8443/zxid")

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

  /var/zxid/
   |
   +-- 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.

ca.pem:: 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.
sign-nopw-cert.pem:: 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).
enc-nopw-cert.pem:: 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
    MUST NOT be used as the encryption certificate to avoid key compromise
    through encryption from compromising the signatures. Attacks that
    do just this (Backwards Compatibility attacks) are described in
    http://www.nds.ruhr-uni-bochum.de/research/publications/backwards-compatibility/

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-nopw-cert.pem:: 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.
cdc-nopw-cert.pem:: 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

  /var/zxid/cot/Inkl5fOnhVNa0LbWjHem2Y2UphY

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
  PATH=/var/zxid/
  URL=https://sp.mydomain.com:8443/zxid
  NICE_NAME=My SP's human%0areadable name.
  #EOF

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
<<link:html/zxid-simple.html: zxid_simple()>> Easy API for SAML.


3.1.1 Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** This section also appears in zxid-simple.pd)

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:

PATH:: Where files are kept and configuration file is found.
NICE_NAME:: Human readable namme of the SP
URL:: The URL of the SP
CDC_URL:: The Common Domain URL (optional, if omitted
    the Common Domain Cookie processing is disabled)

3.1.2 AUTO options (auto flags)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** This section also appears in zxid-simple.pd)

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: 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:

  HC
  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

  TF
  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

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

3.1.3 Configuration options for customizing HTML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** This section also appears in zxid-simple.pd)

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

IDP_SEL_TEMPL_FILE:: 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.

IDP_SEL_TEMPL:: 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".

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

IDP_SEL_PAGE::  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

fc:: Create federation (AllowCreate flag)
fn:: Name ID format
    prstnt:: Persistent (pseudonym)
    trnsnt:: Transient, temporary pseudonym

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

fq:: Affiliation ID (usually empty)
fy:: Consent obtained by SP for the federation or SSO
    empty:: No statement about consent
    urn:liberty:consent:obtained:: Has been obtained (unspecified way)
    urn:liberty:consent:obtained:prior:: Obtained prior to present
        transaction, e.g. user signed terms and conditions of service
    urn:liberty:consent:obtained:current:implicit:: Consent
        is implicit in the situation where user came to invoke service
    urn:liberty:consent:obtained:current:explicit:: Obtained explicitly
    urn:liberty:consent:unavailable:: Consent can not be obtained
    urn:liberty:consent:inapplicable:: Obtaining consent is not
        relevant for the SP or service.
fa:: Authentication Context (strength of authentication) needed by the SP
fm:: Matching rule for authentication strength (usually empty, IdP decides)
fp:: Forbid IdP from interacting with the user (IsPassive flag)
ff:: Request reauthentication of user (ForceAuthn flag)

4 ZXID Attribute Broker (ZXAB)
==============================

<<dia: arch-zxid-attr-brkr:bg,fg: 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.

*Example*

  <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"
  </Location>

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.

  NEED=A,B$usage$retention$oblig$ext

A,B:: Names of attributes (comma separated list) needed by subprocess
    environment
usage:: 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.
retention:: 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.
oblig:: The obligations that will be complied to WRT these attributes
    if they are received. Specific enumerators or language are +still TBD+.
ext:: 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.

  WANT=A,B$usage$retention$oblig$ext$default

A,B:: Names of attributes (comma separated list) needed by subprocess
    environment. If star (*) is specified, all available attributes
    are requested.<<footnote: This
    should not be used light heartedly. Much better to spell out explicitly the
    attribute requirements so that proper CARML description can be made.>>
usage:: The promised usage of the attributes (feeds out to CARML
    declaration). Specific usage enumerators or policy language
    are +still To Be Defined+.
retention:: The data retention policy that will be applied to these
    attributes if they are received. Specific enumerators or language
    are +still To Be Defined+.
oblig:: The obligations that will be complied to WRT these attributes
    if they are received. Specific enumerators or language are +still TBD+.
ext:: Extension fields to describe attribute policies in more detail.
default:: 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.

  ATTRSRC=namespace$A,B$weight$accessparamURL$AAPMLref$otherLim$ext

namespace:: Namespace string assigned to this attribute source.
A,B:: List of attributes available from this source
weight:: Weighting factor (integer) determining the prioirity of this
    source. Less indicates higher preference.
accessparam:: Typically URL for contacting the source, or special
    value "reset" to clear the list and start building anew.
AAPMLref:: Reference to AAPML declaration about policies applying
    to this attribute source
otherLim:: Description of additional policies applying to this attribute source
ext:: Extensions

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

* Requester token (assertion). This attribute source will
  use as namespace the issuer's entity ID. Essentially this is
  similar to the Single Sign-On assertion treatment.
* Target Identity token (assertion). This attribute source will
  use as namespace the issuer's entity ID. Further, the actual
  attributes are prefixed with "tgt_".
* Attributes passed in SOL (Simple Obligations Language) formatted
  UsageDirective. This attribute source will use as namespace the
  entity ID of the message signer, i.e. the WSC that pledges
  to respect the obligations.

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.

  INMAP=ns$A$rule$b$ext

ns:: Source namespace of the attribute
A:: Attribute name in the source namespace
b:: Attribute name in common namespace (if omitted, same as +A+)
rule:: transformation rule:
    rename:: Just renames the attribute. Value is passed intact. Default.
    del:: Deletes the attribute.
    feidedec:: Decode the attribute value accoring to Feide (Norway) rules.
        Also rename if +b+ provided.
    feideenc:: Encode the attribute value accoring to Feide (Norway) rules.
        Also rename if +b+ provided.
    unsb64-inf:: Decode the attribute value accoring to safebase64-inflate
        rules ([RFC3548], [RFC1951]). Also rename if +b+ provided.
    def-sb64:: Encode the attribute value accoring to deflate-safebase64
        rules ([RFC1951], [RFC3548]). Also rename if +b+ provided.
    unsb64:: Decode the attribute value according to safebase64 [RFC3548]
        rule (NZ). Also rename if +b+ provided.
    sb64:: Encode the attribute value according to safebase64 [RFC3548]
        rule (NZ). Also rename if +b+ provided.
    a7n:: Wrap the attribute in a SAML2 assertion
    x509:: Wrap the attribute in a X509 AC attribute certificate
    file:: Obtain the value of the attribute from file specified in the +ext+ field
    a7n-feideenc:: Combination of ~a7n~ and ~feideenc~
    a7n-def-sb64:: Combination of ~a7n~ and ~def-sb64~
    a7n-sb64:: Combination of ~a7n~ and ~sb64~
    x509-feideenc:: Combination of ~x509~ and ~feideenc~
    x509-def-sb64:: Combination of ~x509~ and ~def-sb64~
    x509-sb64:: Combination of ~x509~ and ~sb64~
    file-feideenc:: Combination of ~file~ and ~fedieenc~
    file-def-sb64:: Combination of ~file~ and ~def-sb64~
    file-sb64:: Combination of ~file~ and ~sb64~
    reset:: Special pseudo rule that clears previous map configuration. (e.g. $$reset$$)
ext:: 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*

nameid:: Concatenation of +affid+ and +idpnid+ like: "affid$idpnid". (*** problem with dollar sep)

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~.

  OUTMAP=src$A$rule$b$ext

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):

  /var/zxid/idpuid/.all/SP_SHA1_NAME/.cf
  /var/zxid/idpuid/.all/.bs/.cf

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

  AAMAP=$*$$$;$idpsesid$del$$

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

<<ignore:
4.1.6 Additional Filtering
~~~~~~~~~~~~~~~~~~~~~~~~~~

*** The del rules in INMAP and OUTMAP achive same purpose.

NOT IMPLEMENTED YET!

By default only attributes listed in +NEED+ and +WANT+ specifications are
passed thru, and even then only if the available usage policies are acceptable.
However, if additional attributes are available, they can be accepted using
+WANT+ specification with "*". In this case, some attributes can be filtered
out using +SUPPRESS+ directive (in fact +SUPPRESS+ applies inconditionally
to all attributes just before +out-map+ stage):

  SUPPRESS=A,B,C
>>

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.

* Explicit Deny stops processing
* Explicit Allow moves to next phase
* Lack of Allow or Deny at end of phase moves to next phase
* Lack of Allow after all phases is Deny

5.1 Local PDP Authorization Functionality
-----------------------------------------

The authorization module can authorize access locally based on

* List of approved user names or forbidden user names
* Role attribute having a value or not having a value
* Authorization token (NI 20090904) (***)

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

* "subj": Subject Attributes  (default: idpnid and role=guest)
* "rsrc": Resource Attributes (default: URL=url of page)
* "act":  Action Attributes   (default: Action=access)
* "env":  Environment Attributes (default: ZXID_PEPvers)

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:

  ns$srcattr$rule$dstattr$ext

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.

<<dia: stackable-filter-master-pdp:bg,rules,pdp: 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:

PEPMAP_RQOUT:: 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.

PEPMAP_RQIN:: 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.

PEPMAP_RSOUT:: 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.

PEPMAP_RSIN:: 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. (*** specify values)



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 \n 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.

<<ignore: ./gen-conf-ref.pl <zxidconf.h >foo.pd >>

6.1 Configuration Options
-------------------------

4.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). 

CONF_FILE:: (compile) (default: 1)

CONF_FLAG:: (compile) (default: 1)

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


4.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. 

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

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


4.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 

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


4.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
  https://sp1.zxidsp.org:8443/zxid?o=B 

URL::  (default: "https://sp1.zxidconf-you-should-set-URL-conf-variable-to-some-useful-and-site-dependent-value.org:8443/zxid")


4.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 

NON_STANDARD_ENTITYID::  (default: 0)


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

  #define ZXID_BARE_URL_ENTITYID 0

4.1.6 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. 

REDIRECT_HACK_IMPOSED_URL::  (default: 0)

REDIRECT_HACK_ZXID_URL::  (default: 0)


4.1.7 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. 

ORG_NAME::  (default: "Unspecified ORG_NAME conf variable")

ORG_URL::  (default: 0)

LOCALITY::  (default: "Lisboa")

STATE::  (default: "Lisboa")

COUNTRY::  (default: "PT")

CONTACT_ORG::  (default: 0)

CONTACT_NAME::  (default: 0)

CONTACT_EMAIL::  (default: 0)

CONTACT_TEL::  (default: 0)


4.1.8 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: FXyysxhM4F6d3DIwrtoiFdi0i@zxidp.org

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).
 

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


4.1.9 IdP Attribute Generation Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0x01  If fedusername is generated, also generate
      urn:oid:1.3.6.1.4.1.5923.1.1.1.6 (aka ~eduPersonPrincipalName~)
 

IDPATOPT::  (default: 0x01)


4.1.10 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_URL:: CDC disabled (default: "")


4.1.11 CDC designated IdP Handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

CDC_CHOICE::  (default: ZXID_CDC_CHOICE_UI_PREF)


4.1.12 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.

MD_FETCH:: 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 zxidcot.pl?op=md 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.

MD_POPULATE_CACHE:: 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.

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

MD_CACHE_LAST:: 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.
 

MD_FETCH:: The Auto-CoT ena option (default: 1)

MD_POPULATE_CACHE::  (default: 1)

MD_CACHE_FIRST::  (default: 1)

MD_CACHE_LAST::  (default: 1)


4.1.13 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. 

LOAD_COT_CACHE::  (default: 0)


4.1.14 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

  /var/zxid/pem/enc-nopw-cert.pem
  /var/zxid/pem/sign-nopw-cert.pem
  /var/zxid/pem/logenc-nopw-cert.pem
  /var/zxid/pem/logsign-nopw-cert.pem
  /var/zxid/pem/ssl-nopw-cert.pem

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

AUTO_CERT::  (default: 1)


4.1.15 Authentication Request Signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

AUTHN_REQ_SIGN::  (default: 1)


4.1.16 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. 

WANT_SSO_A7N_SIGNED::  (default: 1)


4.1.17 SSO SOAP Message Signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whether SOAP messages for ArtifactResolution, SLO, and MNI are signed. Whether
responses are signed as well. (*** doc) 

SSO_SOAP_SIGN::  (default: 1)

SSO_SOAP_RESP_SIGN::  (default: 1)


4.1.18 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. 

SSO_SIGN::  (default: 0x01)


4.1.19 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). (*** doc) 

NAMEID_ENC::  (default: 0x0f)


4.1.20 Assertion Encryption in POST
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whether to encrypt assertions when using POST bindings. 

POST_A7N_ENC::  (default: 1)


4.1.21 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)

N.B:: 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).
 

ENCKEY_OPT::  (default: 0x20)


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

#define ZXID_DI_ALLOW_CREATE '1'

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

DI_NID_FMT::  (default: 'p')


4.1.23 Controls whether assertions emitted by discovery are encrypted.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

DI_A7N_ENC::  (default: 1)


4.1.24 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. 

BOOTSTRAP_LEVEL::  (default: 1)


4.1.25 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. 

WSC_SIGN::  (default: 0x03)


4.1.26 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. 

WSP_SIGN::  (default: 0x03)


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

#define ZXID_WSPCGICMD "./zxid-wspcgicmd.sh"

/*(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 

ID_BITS:: (compile) (default: 144)

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


4.1.28 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. 

TRUE_RAND:: (compile) (default: 0)


4.1.29 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. 

SES_ARCH_DIR:: 0=Remove dead sessions. (default: 0)


4.1.30 Session cookies.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For original Netscape cookie spec see: http://curl.haxx.se/rfc/cookie_spec.html (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). 

SES_COOKIE_NAME::  (default: "ZXIDSES")


4.1.31 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 

USER_LOCAL::  (default: 1)


4.1.32 Mini IdP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whether limited IdP functionality is enabled. Affects generated metadata. 

IDP_ENA::  (default: 0)


4.1.33 IdP Proxying, i.e. IdP can be SP towards another IdP.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  #define ZXID_IDP_PXY_ENA 0

4.1.34 Identity Mapper and People Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

IMPS_ENA::  (default: 0)


4.1.34 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. 

AS_ENA::  (default: 0)


4.1.35 Dummy PDP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whether limited PDP functionality is enabled. 

PDP_ENA::  (default: 1)


4.1.36 IdP Insitence on Signed AuthnReq
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

WANT_AUTHN_REQ_SIGNED::  (default: 1)

MAX_BUF:: (compile) (default: 1024)


4.1.37 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.
 

LOG_OP_NOLOG::  (default: 0x00)

LOG_OP_LOG::  (default: 0x01)

LOG_OP_LOG_SIGN::  (default: 0x05)

LOG_OP_LOG_ENC::  (default: 0x21)

LOG_OP_LOG_SIGN_ENC::  (default: 0x25)

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

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

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

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

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

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

LOG_ERR::  (default: 0x00)

LOG_ACT::  (default: 0x25)

LOG_ISSUE_A7N::  (default: 0x23)

LOG_ISSUE_MSG::  (default: 0x45)

LOG_RELY_A7N::  (default: 0x41)

LOG_RELY_MSG::  (default: 0x11)


4.1.38 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_ERR_IN_ACT:: Log errors to /var/zxid/log/act (in addition to err) (default: 1)

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

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


4.1.39 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 

LOG_LEVEL::  (default: 2)


4.1.40 Per user activity logging.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

LOGUSER::  (default: 1)


4.1.41 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. 

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

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

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

AUDIENCE_FATAL:: Whether AudienceRestriction is checked. (default: 1)

TIMEOUT_FATAL:: Whether NotBefore and NotOnOrAfter are checked (default: 1)

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

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

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


4.1.42 Web service request and response validation options. For the token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

in the request, the assertion validation options apply. 

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

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


4.1.43 XML canonicalization compatibility kludges
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  #define ZXID_CANON_INOPT 0

4.1.43 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 

CANON_INOPT_SHIB215IDP_INCLUSIVENAMESPACES::  (default: 0x01)


4.1.44 XML encoding optimizations.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

ENC_TAIL_OPT::  (default: 1)


4.1.45 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()
 

VALID_OPT::  (default: 0x00)

VALID_OPT_SKIP_RESP_HDR::  (default: 0x01)


4.1.46 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 pool.ntp.org (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. :-) 

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

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

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

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


4.1.47 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. 

REDIR_TO_CONTENT::  (default: 1)


4.1.48 ID-WSF SOAP Call parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


4.1.49 Session Management Trigger Suffix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


4.1.50 Attribute Prefix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

MOD_SAML_ATTR_PREFIX::  (default: "SAML_")


4.1.51 Fake Basic Auth by generating REMOTE_USER
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In mod_auth_saml generate REMOTE_USER subprocess environment variable. 

REMOTE_USER_ENA::  (default: 1)


4.1.52 Query String if None Given
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


4.1.53 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. 

ANON_OK::  (default: 0)


4.1.54 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. 

REQUIRED_AUTHNCTX::  (default: 0)


4.1.55 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. 

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


4.1.56 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. 

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


4.1.57 List of unsuppressible attributes. Every SSO and discovery will include
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

MANDATORY_ATTR::  (default: "zxidvers,zxidloa")


4.1.58 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 ""


4.1.59 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. 

PDP_URL::  (default: 0)

PDP_CALL_URL::  (default: 0)


4.1.60 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. 

TRUSTPDP_URL::  (default: 0)


4.1.61 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. 

CPN_ENA::  (default: 0)


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

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

AZ_OPT::  (default: 0)


4.1.63 Which version of XACML to speak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

  #define ZXID_XASP_VERS "2.0"

4.1.63 What to pass in XACML PolicySetIdReference when calling PDP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Empty means not to pass PolicySetIdReference. 

XA_POLICY_SET_ID_REF:: *** implement (default: "")


4.1.64 Specify common XACML Attributes for PEPs in format ns$A$rule$b$ext (compile)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ZXID_COMMAP 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. 

COMMAP::  (default: "env$*$$$;subj$idpnid$rename$urn:oasis:names:tc:xacml:1.0:subject:subject-id$;subj$urn:oasis:names:tc:xacml:1.0:subject:subject-id$$$;subj$urn:oid:1.3.6.1.4.1.5923.1.1.1.1$$$;subj$urn:oid:1.3.6.1.4.1.5923.1.1.1.7$$$;subj$eduPersonAffiliation$$$;subj$eduPersonEntitlement$$$subj$role$$$;rsrc$rs$rename$urn:oasis:names:tc:xacml:1.0:resource:resource-id$;rsrc$urn:oasis:names:tc:xacml:1.0:resource:resource-id$$$;act$Action$rename$urn:oasis:names:tc:xacml:1.0:action:action-id$;act$urn:oasis:names:tc:xacml:1.0:action:action-id$$$;env$ZXID_PEPvers$$$;$cookie$del$$;$setcookie$del$$")


4.1.65 Specify XACML Attributes for SSO / frontchannel request in PEP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

in format ns$A$rule$b$ext

  #define ZXID_PEPMAP       ZXID_COMMAP

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

in format ns$A$rule$b$ext 

PEPMAP_RQOUT::  (default: ZXID_COMMAP)


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

in format ns$A$rule$b$ext

  #define ZXID_PEPMAP_RQIN  ZXID_COMMAP

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

in format ns$A$rule$b$ext 

PEPMAP_RSOUT::  (default: ZXID_COMMAP)


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

in format ns$A$rule$b$ext

  #define ZXID_PEPMAP_RSIN  ZXID_COMMAP

  //#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"

4.1.67 Default AAMAP
~~~~~~~~~~~~~~~~~~~~

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

DEFAULT_IDP_AAMAP:: (compile) (default: "$*$$$;$idpsesid$del$$")


4.1.68 Whitelists and blacklists for the primitive SSO local PDP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Comma separated lists.

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

LOCALPDP_ROLE_DENY:: Blacklist of roles (default: "local_deny")

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

LOCALPDP_IDPNID_DENY:: Blacklist of denied users (default: "denynid")


4.1.69 Obligations we are willing to respect
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

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

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

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


4.1.70 Simple API HTML customization.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


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

are hidden and POST profile is used 

SHOW_TECH::  (default: 0)


4.1.72 Body tag for some old ZXID generated pages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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


4.1.73 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). 

IDP_SEL_TEMPL_FILE::  (default: "idpsel.html")


4.1.74 Template for IdP Selector Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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


4.1.75 Choose the method for rendeing IdP list.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

IDP_LIST_METH::  (default: 0)

IDP_LIST_POPUP::  (default: 0)

IDP_LIST_BUTTON::  (default: 1)

IDP_LIST_BRAND::  (default: 2)


4.1.76 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. 

IDP_SEL_PAGE::  (default: 0)


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

  #define ZXID_NEW_USER_PAGE 0

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

RECOVER_PASSWD::  (default: 0)


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

  #define ZXID_ATSEL_PAGE 0

4.1.78 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. 

AN_PAGE::  (default: 0)


4.1.79 Path for Template for IdP Authentication Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  #define ZXID_AN_TEMPL_FILE "an-main.html"

4.1.79 Template for IdP Authentication Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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


4.1.80 Path for Template for POST profile page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  #define ZXID_POST_TEMPL_FILE "post.html"

4.1.80 Template for POST profile age
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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


4.1.81 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. 

ERR_PAGE::  (default: 0)


4.1.82 Path for Template for Error Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  #define ZXID_ERR_TEMPL_FILE "err.html"

4.1.82 Template for Error Page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

MGMT_START::  (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>\n")

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

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

MGMT_FOOTER::  (default: "<div class=zxbot><a class=zx href=\"http://zxid.org/\">zxid.org</a>, ")

MGMT_END::  (default: "</div>")


<<if: ZXIDBOOK>>
<<else: >>

96 License
==========

Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved.
Author: Sampo Kellomäki (sampo@iki.fi)

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
http://www.apache.org/licenses/LICENSE-2.0

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.

97 FAQ
======


97.3 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

   Asa:
   > 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?

   Conor:
   > 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.

97.3 Common Mistakes
--------------------

1.  When I try accessing https://sp1.zxidsp.org:8443/zxidtest.sh nothing happens!

    Assuming you have the web server correctly running, the most common
    gotcha is that zxidhlo has dynamic linking problem.
    See <<see: ZXID-Installing-CannedTutorialRunningZXIDasCGIundermini_httpd-AccessingZXID>>
    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

    a. 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.

    b. 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.

    c. 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.

    d. 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 (*** procedure to be documented). See [SAML2meta]
       section 4.1 "Publication and Resolution via Well-Known Location",
       p.29, for normative description of this method.

    e. 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.

    f. 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

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

    b. Personal firewall blocks access. Check firewall set up on
       * browser machine
       * SP machine

    c. 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.

    d. 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...

    > Once it has been compiled, I copied the files zxidhlo.php and zxid.php
    > to /var/www/zxid (my webroot). I accessed zxidhlo.php?o=E with my browser
    > and I saw a page asking for IDP metadata. But when I looked at
    > the /var/log/apache2/error.log, I found these: 
    > 
    >  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.


<<references:

[SAML2core] "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-core-2.0-os

[SAML2prof] "Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-profiles-2.0-os

[SAML2bind] "Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-bindings-2.0-os

[SAML2context] "Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-authn-context-2.0-os

[SAML2meta] 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

[SAML2security] "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

[SAML2conf] "Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-conformance-2.0-os

<<doc-end.pd>>
<<notapath: TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>>
<<EOF: >>

#/var/zxid/zxid.conf

IDP_SEL_START=<title>ZXID SP SSO: Choose IdP</title><body bgcolor=white><h1>ZXID SP Federated SSO (user NOT logged in, no session)</h1>

IDP_SEL_NEW_IDP=<h3>Login Using New IdP</h3><i>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.</i><p>IdP URL <input name=e size=80><input type=submit name=l1 value=" Login (A2) ">\n<input type=submit name=l2 value=" Login (P2) "><br>

IDP_SEL_OUR_EID=Entity ID of this SP (click on the link to fetch the SP metadata): 

IDP_SEL_TECH_USER=<h3>Technical options</h3><input type=checkbox name=fc value=1 checked> Create federation, NID Format: <select name=fn><option value=prstnt>Persistent<option value=trnsnt>Transient<option value="">(none)</select><br>

IDP_SEL_TECH_SITE=<input type=hidden name=fq value=""><input type=hidden name=fy value=""><input type=hidden name=fa value=""><input type=hidden name=fm value=""><input type=hidden name=fp value=0><input type=hidden name=ff value=0><!-- ZXID built-in defaults, see IDP_SEL_TECH_SITE in zxidconf.h -->

IDP_SEL_FOOTER=<hr><a href=\"http://zxid.org/\">zxid.org</a>, 
IDP_SEL_END=<!-- EOF -->


<<fi: >>