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

# Configuring ZXID

>> 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//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) | +-- 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 | `-- 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> directives. > 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 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-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 <> 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_perm, 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. 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 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 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 ntp1.funet.fi (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: "
") 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: "ZXID SP SSO: Choose IdP"\) 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: "ZXID IdP: Authentication"\) 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: "ZXID Post Profile"\) 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: "ZXID: Error"\) MGMT_START:: (default: "ZXID SP Mgmt

# ZXID SP Management (user logged in, session active)

\n") MGMT_LOGOUT:: (default: "\n\n\n") MGMT_DEFED:: (default: "\n\n") MGMT_FOOTER:: (default: "
zxid.org, ") MGMT_END:: (default: "
") <<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=ZXID SP SSO: Choose IdP

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

IDP_SEL_NEW_IDP=

### 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:
IDP_SEL_TECH_SITE= IDP_SEL_FOOTER=

zxid.org, IDP_SEL_END= <<fi: >>