ZXID.org Identity Management toolkit implements standalone SAML 2.0 and Liberty ID-WSF 2.0 stacks. This document explains configuration options of ZXID.
ZXID, out-of-box, needs very little configuration. Generally you only need to decide the URL and NICE_NAME of your web site.
Tip: You can view current configuration by supplying URL suffix o=d
Compile time configuration, based on Makefile and zxidconf.h is explained in separate document ZXID Compilation and Installation.
In addition to setting runtime configure options, you will need to join a Circle of Trust - or create your own. This part of set-up is explained in Building CoT.
If you are interested in using mod_auth_saml Apache module, you can perform some of the configuration in the Apache httpd.conf file as explained in mod_auth_saml.
You should remember that some of the configuration will happen in the web server level, see your web server's configuration reference, e.g. httpd.conf
mod_auth_saml Apache module documentation: SSO without programming.
zxid_simple() Easy API for SAML
ZXID Raw API: Program like the pros (and fix your own problems). See also Function Reference
ZXID ID-WSF API: Make Identity Web Services Calls using ID-WSF
ZXID Compilation and Installation: Compile and install from source or package. See also INSTALL.zxid for quick overview.
ZXID Configuration Reference: Nitty gritty on all options.
ZXID Circle of Trust Reference: How to set up the Circle of Trust, i.e. the partners your web site works with.
ZXID Logging Reference: ZXID digitally signed logging facility
javazxid: Using ZXID from Java
Net::SAML: Using ZXID from Perl
php_zxid: Using ZXID from PHP
zxididp: Using ZXID IdP and Discovery
README.smime: Crypto and Cert Tutorial
FAQ: Frequently Asked Questions
README.zxid: ZXID project overview
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.
ZXID uses a configuration file in default path
/var/zxid/zxid.conf
for figuring out its parameters. If this file is not present, built-in
default configuration is used (see zxidconf.h). The 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 generate your own certificate and private key.
Usually configuring a system involves following tasks
Configure web server (see your web server documentation)
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.
Arrange for ZXID to be invoked. This could mean configuring zxid, zxid-java.sh, or zxid.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.
Configure ZXID, including signing certificate and CoT with peer metadata
generate or acquire certificate
Obtain peer metadata (from their well known location) or enable Auto CoT feature.
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). For this to happen you need to have web server and ZXID up and running.
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.
Directory that holds various certificates. The certificates have hardwired names that are not configurable.
Certification Authority certificates. These are used for validating any certificates received from peers (other sites on the CoT). The CA certificates may also be shipped to the peers to facilitate them validating our signatures. This is especially relevant if the certificate is issued by multilayer CA hierarchy where the peer may not have the intermediate CA certificates.
The signing certificate AND private key (concatenated in one file). The private key MUST NOT be encrypted (there will not be any opportunity to supply decryption password).
The encryption certificate AND private key (concatenated in one file). The private key MUST NOT be encrypted (there will not be any opportunity to supply decryption password). The signing certificate can be used as the encryption certificate. If encryption certificate is not specified it will default to signing certificate.
In addition to the above certificates and private keys, you will need to configure your web server to use TLS or SSL certificates for the main site and the Common Domain site. We suggest the following naming
SSL or TLS certificate for main site. In order to avoid browser warnings, the CN field of this certificate should match the domain name of the site. The SSL certificate can be same as signing or encryption certificate.
SSL or TLS certificate for Common Domain Cookie introduction site. In order to avoid browser warnings, the CN field of this certificate should match the domain name of the site. The SSL certificate can be same as signing or encryption certificate.
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).
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:
Built in default configuration
Configuration file, usually /var/zxid/zxid.conf, if any
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.
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.
For full description of the simple API, plese see zxid_simple() Easy API for SAML.
The zxid_simple() can be configured by conf string as argument as well as by configuration file. In addition a flags argument is accepted, see next subsection "AUTO options", to specify simple API specific automation options.
Turns out that often the default configuration modified by the configurations string is all you need - you do not need to prepare a configuration file.
See section "Configuring and Running" for complete list of configuration options, but generally it is sufficient to specify only a handful:
Where files are kept and configuration file is found.
The URL of the SP
The Common Domain URL (optional, if omitted the Common Domain Cookie processing is disabled)
The auto_flags argument allows you to control which operations should be performed automatically and which should be passed to the calling application, see "Gaining More Control" section, below, for full description of this case.
The auto options can be added together.
Table 1:zxid_simple() AUTO options
| Dec | Hex | Symbol | Description |
|---|---|---|---|
| 1 | 0x01 | ZXID_AUTO_EXIT | Call exit(), 0=return "n", even if auto CGI |
| 2 | 0x02 | ZXID_AUTO_REDIR | Automatic. handle redirects, assume CGI (calls exit(2)) |
| 4 | 0x04 | ZXID_AUTO_SOAPC | SOAP response handling, content gen |
| 8 | 0x08 | ZXID_AUTO_SOAPH | SOAP response handling, header gen |
| 16 | 0x10 | ZXID_AUTO_METAC | Metadata response handling, content gen |
| 32 | 0x20 | ZXID_AUTO_METAH | Metadata response handling, header gen |
| 64 | 0x40 | ZXID_AUTO_LOGINC | IdP select / Login page handling, content gen |
| 128 | 0x80 | ZXID_AUTO_LOGINH | IdP select / Login page handling, header gen |
| 256 | 0x100 | ZXID_AUTO_MGMTC | Management page handling, content gen |
| 512 | 0x200 | ZXID_AUTO_MGMTH | Management page handling, header gen |
| 1024 | 0x400 | ZXID_AUTO_FORMF | In idp list and mgmt screen, generate form fields |
| 2048 | 0x800 | ZXID_AUTO_FORMT | In idp list & mgmt screen, wrap in |
| 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
When whole page is generated, some templating information is taken from the configuration.
Path for Template for IdP Selecton Page. Default "idpsel.html". This file, which you can edit for customization, is used as template to render the IdP selection page on the SP side. If the file does not exist, the value of ZXID_IDP_SEL_TEMPL configuration option is used as template. By default idpsel.html uses idpsel.css as stylesheet. You can make many kinds of customization just by editing this stylesheet.
Template for IdP Authentication Page that is used if the path does not work. This is really meant to be the last resort. The default value of this page is the compiled in template "ZXID SP SSO: Choose IdP".
Choose the method for rendeing IdP list. 0 = popup menu, 1 = buttons, 2 = branded image buttons (not implemented as of 20100922)
IdP Selector Page URL
If the IDP_SEL_TEMPL_FILE or IDP_SEL_TEMPL, above, is not sufficient for your customization needs, you can provide URL to page of your own design. This page will receive as query string argument the relay state. 0 (zero) disables.
You can set several rather technical configuration options by editing the IdP selection template and adding (hidden) form fields. You may want to hardwire these or allow user to set them
Create federation (AllowCreate flag)
Name ID format
Persistent (pseudonym)
Transient, temporary pseudonym
Technical parameters that the site administrator should decide and set. Usually hidden form fields in the template:
Affiliation ID (usually empty)
Consent obtained by SP for the federation or SSO
No statement about consent
Has been obtained (unspecified way)
Obtained prior to present transaction, e.g. user signed terms and conditions of service
Consent is implicit in the situation where user came to invoke service
Obtained explicitly
Consent can not be obtained
Obtaining consent is not relevant for the SP or service.
Authentication Context (strength of authentication) needed by the SP
Matching rule for authentication strength (usually empty, IdP decides)
Forbid IdP from interacting with the user (IsPassive flag)
Request reauthentication of user (ForceAuthn flag)
Fig-1: Liberty IGF Compliant Attribute Broker fetches the needed attributes from available providers and populates them to the subprocess environment.
As can be seen in the accompanying figure, the provision of attributes to the applications in the Apache subprocess environment (CGI, mod_perm, mod_php, etc.) is handled as follows:
Configure attribute needs and names (this corresponds to CARML declaration)
Configure attribute sources (this corresponds to AAPML declaration)
Configure source or input mappings (INMAP)
Filter for needs (and optional wants)
Map to application domain (OUTMAP)
Provide attributes in to subprocess environment
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.
*** This is provisory specification
The Attribute Broker configuration in Apache set-up is per
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>
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
Names of attributes (comma separated list) needed by subprocess environment
The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined. Special value "reset" clears previous need configuration.
The data retention policy that will be applied to these attributes if they are received. Specific enumerators or language are still To Be Defined. The example illustrates retention in seconds.
The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still TBD.
Extension fields to describe attribute policies in more detail.
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
Names of attributes (comma separated list) needed by subprocess environment. If star (*) is specified, all available attributes
are requested.
The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined.
The data retention policy that will be applied to these attributes if they are received. Specific enumerators or language are still To Be Defined.
The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still TBD.
Extension fields to describe attribute policies in more detail.
Optional default value to use in case the attribute is not available.
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 string assigned to this attribute source.
List of attributes available from this source
Weighting factor (integer) determining the prioirity of this source. Less indicates higher preference.
Typically URL for contacting the source, or special value "reset" to clear the list and start building anew.
Reference to AAPML declaration about policies applying to this attribute source
Description of additional policies applying to this attribute source
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.
INMAP specification provides for various input attribute renaming and input attribute value decoding operations.
INMAP=ns$A$rule$b$ext
Source namespace of the attribute
Attribute name in the source namespace
Attribute name in common namespace (if omitted, same as +A+)
transformation rule:
Just renames the attribute. Value is passed intact. Default.
Deletes the attribute.
Decode the attribute value accoring to Feide (Norway) rules. Also rename if +b+ provided.
Encode the attribute value accoring to Feide (Norway) rules. Also rename if +b+ provided.
Decode the attribute value accoring to safebase64-inflate rules ([RFC3548], [RFC1951]). Also rename if +b+ provided.
Encode the attribute value accoring to deflate-safebase64 rules ([RFC1951], [RFC3548]). Also rename if +b+ provided.
Decode the attribute value according to safebase64 [RFC3548] rule (NZ). Also rename if +b+ provided.
Encode the attribute value according to safebase64 [RFC3548] rule (NZ). Also rename if +b+ provided.
Wrap the attribute in a SAML2 assertion
Wrap the attribute in a X509 AC attribute certificate
Obtain the value of the attribute from file specified in the ext field
Combination of a7n and feideenc
Combination of a7n and def-sb64
Combination of a7n and sb64
Combination of x509 and feideenc
Combination of x509 and def-sb64
Combination of x509 and sb64
Combination of file and fedieenc
Combination of file and def-sb64
Combination of file and sb64
Special pseudo rule that clears previous map configuration. (e.g. reset)
Extended argument that may be used by some rules.
The order of evaluation of INMAP stanzas is not defined, therefore it is not avisable to include same attribute in two stanzas as only one would fire.
SSO derived attributes
Concatenation of affid and idpnid like: "affididpnid".
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
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).
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
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.
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.
ZXID implements a four points of control PEP model for web service calls. This is adopted from the TAS3 project.
Fig-2: Four PEP Control Points on the Web Service call path.
Each control point extracts the attributes from the common namespace of the pool using directives similar to PEPMAP as follows:
Request outbound enforement point on Web Service Client (WSC) side, see (1) in the diagram. Typically this enforcement point can be used to control whether WSC is allowed to talk to the Web Service Provider (WSP). It can also be used to control whether the data whose submission to WSP is contemplated, is allwed to leave the WSC, and if so, under which obligations or usage directives. Finally, this control point can be used to formulate pledges about which obligations the WSC is willing to honour. Again, such pledges are passed as a usage directive on the wire.
Request inbound enforcement point on WSP side, see (2) in the diagram. This is the main PEP that filters the requests "at the gate" before they get in. When most people think about a PEP, they think about this type of PEP. The PEPMAP_RQIN can implement tests on requesting identity attributes, target identity (resource owner) attributes, obligations requirements and obligations pledges conveyed in the usage directives, as well as the actual operation contemplated and data in the operation.
Response outbound enforcement point on WSP side, see (3) in the diagram. This PEP is in position to filter outbound data before it is returned to the WSC. It can also attach obligations to this data, as usage directives.
Response inbound enforcement point on WSC side, see (4) in the diagram. This PEP is mainly useful for checking whether the usage directives and obligations attached to the data are acceptable. If not, the data can be rejected at this point.
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
This section is generated based on comments in zxidconf.h and is updated periodically. See zxidconf.h for authorative definitions. See also zxid.h for struct zxid_conf which is the internal runtime structure capturing these options.
Most of the configuration options can be set via configuration file /var/zxid/zxid.conf or using -O command line flag(s). In config file or on command line you should omit the ZXID_ prefix and use attribute=value syntax separated by newlines or & characters (the parser implements CGI query string syntax with extension that also is accepted as separator).
N.B. The options marked as "(compile)" can not be set on command line or configuration file. They require a recompile.
Whether configuration is entirely determined at compile time by this file or whether it is possible to use a config file or provide options on command line using -O flags (such as via shell script wrapper). When zxid is used as a library, it depends on application to call zxid_parse_conf(). Generally we recommend you leave these turned on (1).
(compile) (default: 1)
(compile) (default: 1)
Whether configuration is viewable from url o=d (default: 1)
Where metadata cache and session files are created. Note that the directory is not hashed: you should use a file system that scales easily to oodles of small files in one directory. Say `make dir' to create the directory with proper layout. If you change it here, also edit Makefile.
(default: "c:/var/zxid/")
(default: "/var/zxid/")
IMPORTANT: You should really configure this option. The nice name may be used by IdP user interface to refer to the SP. It is usually a short human readable name or description. It will also appear in metadata as Organization/OrganizationDisplayName
(default: "ZXID configuration NICE_NAME: Set this to describe your site to humans")
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
(default: "https://sp1.zxidconf-you-should-set-URL-conf-variable-to-some-useful-and-site-dependent-value.org:8443/zxid")
The best practise is that SP Entity ID is chosen by the SP (and not forced upon SP by IdP). In ZXID this is done by setting ZXID_URL, see above. However, should you have to work with an obstinate IdP that refuses to follow this best practise, you can use this option to manually set the Entity ID. Not following the best practise breaks automatic metadata exchange (Auto-CoT). Recommended value: leave as 0 so that Entity ID is formed from ZXID_URL
(default: 0)
#define ZXID_BARE_URL_ENTITYID 0
Sometimes an illadvised authority may impose to you Assertion Consumer Service URL, this URL happens to be different than ZXID uses, and you do not have political leverage to change these decisions. In those times you can use this hack to try to map the imposed URL to the one that works in ZXID. Normally you should register at IdP to use the ZXID default URLs (easiest way to do this is to use metadata). This only works in mod_auth_saml.
(default: 0)
(default: 0)
The LOCALITY, STATE, and COUNTRY will appear in certificates so you may want to set them to sensible values.
(default: "Unspecified ORG_NAME conf variable")
(default: 0)
(default: "Lisboa")
(default: "Lisboa")
(default: "PT")
(default: 0)
(default: 0)
(default: 0)
(default: 0)
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).
(default: "set-this-or-url-to-site-dependent-value")
0x01 If fedusername is generated, also generate
urn:oid:1.3.6.1.4.1.5923.1.1.1.6 (aka ~eduPersonPrincipalName~)
(default: 0x01)
URL for reading Common Domain Cookie. It must end in "zxid". The hostname and port number should match the server under which zxid CGI is accessible. Specifying empty CDC_URL disables CDC check in zxid_simple() API.
CDC disabled (default: "")
How to handle CDC designated IdP. See zxid.h for explanation of constants.
(default: ZXID_CDC_CHOICE_UI_PREF)
Following four boolean configuration options control how metadata is obtained. The metadata can be in a cache (by default directory /var/zxid/cot) or it can be fetched "on the fly" using the well known location (WKL) method.
controls whether fetching is performed. This necessitates that ZXID was linked with libcurl. If you do not enable fetching, you will need to populate the cache manually, perhaps by using a web browser to fetch the meta data xml files from well known location URLs (or other URLs if you know better). Or you could use 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.
controls whether ZXID will write the metadata to the on-disk cache. This requires ZXID_MD_FETCH to be enabled and the file system permissions of the cache directory (e.g. /var/zxid/cot) to allow writing.
controls whether cache will be checked before fetching is attempted. If cache misses, ZXID_MD_FETCH governs whether fetch is tried.
If true, metadata is obtained from cache if fetch was disabled or failed.
If you want to control manually your CoT (e.g. because human process is needed to verify that all the paperwork is in place), set MD_FETCH to 0.
If you want as automatic operation as possible, set all four to 1.
The Auto-CoT ena option (default: 1)
(default: 1)
(default: 1)
(default: 1)
of the Circle of Trust. Some real world federations distribute their metadata this way. Setting this to 0 disables the feature (default). Setting this to file name or path enables this feature.
(default: 0)
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.
(default: 1)
Whether AuthnReq is signed SP (controls both metadata and actual behavior).
(default: 1)
Whether SP insists that SSO assertions are signed. Affects metadata. The actual insistence on signing is controlled by ZXID_NOSIG_FATAL, far below. Boolean. Recommended value: 1.
(default: 1)
Whether SOAP messages for ArtifactResolution, SLO, and MNI are signed. Whether responses are signed as well.
(default: 1)
(default: 1)
Which components should be signed by IdP in SSO Response and Assertion. Bit mask:
0x01 Assertion should be signed (default and highly recommended) 0x02 The surrounding Response element should be signed 0x03 Both Assertion and Response are signed.
(default: 0x01)
Whether SLO and MNI requests emitted by ZXID will encrypt the NameID (on received requests ZXID accepts either plain or encrypted automatically and without configuration).
(default: 0x0f)
Whether to encrypt assertions when using POST bindings.
(default: 1)
how is the EncryptedKey stored relative to EncryptedData
0x00 Sibling, without Recipient hint (interops with many commercial implementations and Shibboleth Sept 2010) 0x01 Sibling, with Recipient hint (interops with many commercial implementations and Shibboleth as of August 2010) 0x20 Nested method, i.e. EncryptedData/KeyInfo/EncryptedKey (interops with all versions of Shibboleth and many others)
SAML2 specs fail to say which approach is preferred, therefore both approaches are valid. In reading messages ZXID automatically understands both. This option only controls how outbound messages are generated so that others can understand them (ideally they would autodetect so we would not need this option).
(default: 0x20)
#define ZXID_DI_ALLOW_CREATE '1'
/*(c) Controls the default NameID Format for discovery: p=persistent, t=transient
(default: 'p')
It is highly recommended to encrypt the assertions to avoid man-in-the-middle attacks.
(default: 1)
only first level is added, i.e. all available bootstraps are embedded in the assertion, but the assertions of the embedded bootstraps only get discovery bootstrap. 2 would cause the assertions of the first order bootstraps to have further bootstraps embedded, etc. Since bootstrap generation tends to be expensive and wasteful, you should use discovery instead and leave BOOTSTRAP_LEVEL set to 1.
(default: 1)
Which components of a web service request should be signed by WSC Bit mask:
0x01 SOAP Headers 0x02 SOAP Body 0x03 Both Headers and Body are signed.
(default: 0x03)
Which components of a web service response should be signed by WSP Bit mask:
0x01 SOAP Headers 0x02 SOAP Body 0x03 Both Headers and Body are signed.
(default: 0x03)
#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
(compile) (default: 144)
used for static buffer allocation (compile) (default: 168)
Whether true randomness is obtained. 0=use OpenSSL RAND_pseudo_bytes(), which usually uses /dev/urandom 1=use OpenSSL RAND_bytes(), which usually uses /dev/random
Although true randomness may be more secure, it is operationally problematic because if not enough randomness is available, the system will block (stop) until enough randomness arrives. Generally true randomness is not feasible in a server environment unless you have a hardware random number generator.
(compile) (default: 0)
If set to a string, indicates a file system directory to which dead sessions are moved (sessions are files). This directory must be on the same file system as active session directory, usually /var/zxid/ses, for example /var/zxid/oldses. You may want to archive old sessions because they contain the SSO assertions that allowed the users to log in. This may have legal value for your application, you may even be required by law to keep this audit trail.
If set to 0, causes old sessions to be unlink(2)'d.
0=Remove dead sessions. (default: 0)
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).
(default: "ZXIDSES")
This is optional unless you require IdP initiated ManageNameID requests to work. Local user account management may be useful on its own right if your application does not yet have such system. If it already has, you probably want to continue to use the application's own system. Local accounts are stored under /var/zxid/user/SHA1
(default: 1)
Whether limited IdP functionality is enabled. Affects generated metadata.
(default: 0)
#define ZXID_IDP_PXY_ENA 0
Whether limited Identity Mapper and People Service functionality is enabled. For this to work, IDP_ENA=1 is needed.
(default: 0)
Whether limited Authentication Service functionality is enabled. Please note that the AuthenticationService impmenetation at present (2010) is incomplete and fails to properly authenticate and authorize the caller system entity, i.e. anyone who knows a username and password can call it.
(default: 0)
Whether limited PDP functionality is enabled.
(default: 1)
Must AuthnReq be signed (controls both IdP metadata and actual behavior, i.e. the check).
(default: 1)
(compile) (default: 1024)
See zxid-log.pd for further explanation. Generally you need error and activity logs to know yourself what is going on. You need the issue logs to know whether other's claims towards you are justified. You need the rely logs to hold others responsible. The bits of the value are as follows 0x00 Don't log. 0x01 Log enable 0x06 Signing options
0:: no signing (Px)
2:: sha1 MD only (Sx)
4:: RSA-SHA1 (Rx)
6:: DSA-SHA1 (Dx)
0x08 reserved 0x70 Encryption options
0x00:: no encryption (xP)
0x10:: zip-base64 (xZ)
0x20:: RSA-AES (xA)
0x30:: RSA-3DES (xT)
0x40:: Symmetric AES (xB)
0x50:: Symmetric 3DES (xU)
0x60:: reserved
0x70:: reserved
0x80 reserved
N.B. Every encryption and signature has computational cost so be sure to factor this in when doing benchmarks - or disable log enc and sign when performance is at premium.
Log signing may help you to argue that log evidence was (not) tampered with. The private key for signing must be available in /var/zxid/pem/logsign-nopw-cert.pem
Log encryption may help to keep the logs confidential. For RSA modes the public key for encryption must be available in /var/zxid/pem/logenc-nopw-cert.pem. For symmetric encryption the key is the sha1 hash of file /var/zxid/pem/logenc.key All modes, except for 0, also RFC1951 zip compress the log line and safe-base64 encode the result of the encryption.
(default: 0x00)
(default: 0x01)
(default: 0x05)
(default: 0x21)
(default: 0x25)
Log errors to /var/zxid/log/err (default: 0x01)
Log activity to /var/zxid/log/act (default: 0x01)
Log each issued assertion to /var/zxid/log/issue/SHA1/a7n/asn (default: 0x01)
Log each issued PDU to /var/zxid/log/issue/SHA1/msg/asn (default: 0x01)
Log each received assertion to /var/zxid/log/rely/SHA1/a7n/asn (default: 0x01)
Log each received PDU to /var/zxid/log/rely/SHA1/msg/MSGID (default: 0x01)
(default: 0x00)
(default: 0x25)
(default: 0x23)
(default: 0x45)
(default: 0x41)
(default: 0x11)
Each operation has its status code and generally those lines that indicate successful status (or intermediate status like "continue" or "redirect") are considered normal activity. However, you may want to consider carefully whether signature failure in assertion or message disqualifies an operation as "activity". One approach is to simply log everything (errors and all) to activity log and rely on some log analysis software to flag the errors.
Log errors to /var/zxid/log/act (in addition to err) (default: 1)
Log actions to /var/zxid/log/err (in addition to act) (default: 1)
Log line with signature validation error to /var/zxid/log/err (default: 1)
0 = Only essential audit relevant events are logged. Note that
there is no way to turn off logging audit relevant events.
1 = Audit and external interactions 2 = Audit, external interactions, and significant internal events 3 and higher: reserved for future definition and debugging
(default: 2)
This option enables logging in /var/zxid/idpuid/UID/.log some key events such as authentication, SSO, and SLO.
(default: 1)
These MUST all be turned on (and assertions signed) if you want to rely on assertions to hold the other party liable.
Signature validation error is fatal (prevents SSO) (default: 1)
Missing signature is fatal (prevents SSO) (default: 1)
Message layer signature (e.g. SimpleSign) is sufficeint when assertion signature is missing. (default: 1)
Whether AudienceRestriction is checked. (default: 1)
Whether NotBefore and NotOnOrAfter are checked (default: 1)
Whether duplicate AssertionID is considered fatal. (default: 1)
Whether duplicate MessageID or message is considered fatal. (default: 1)
Whether failure to correlate RelatesTo to MessageID, or total lack of RelatesTo, is considered fatal. (default: 1)
in the request, the assertion validation options apply.
Missing Security/Signature is fatal. (default: 1)
Missing Security/Timestamp is fatal. (default: 1)
#define ZXID_CANON_INOPT 0
Shibboleth 2.1.5 IdP miscanonicalizes by ignoring InclusiveNamespaces/@PrefixList, yet it still supplies such list. The miscanonicalization leads namespaces missing. This has been reported to Scott Cantor as of 20101005
(default: 0x01)
1 = optimize close tag of empty elements as
(default: 1)
bug free environment, you should not need any of these options. Turning them on will reduce security as validations are not made.
0x01 Skip response header validation entirely, see zxid_wsc_valid_re_env()
(default: 0x00)
(default: 0x01)
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. :-)
Number of seconds before that is acceptable. (default: 39600)
Number of seconds after that is acceptable. (default: 7300)
Timeskew, in seconds, for timestamps we emit. (default: 0)
Time To Live for IdP issued Assertions (default: 3600)
Should explicit redirect to content be used (vs. internal redir). With internal redirect there is one over-the-wire transaction less, but the URL appears as whatever was sent by the IdP. With explicit (302) redirect the URL will appear as the true content URL, without the SAML SSO goo.
(default: 1)
#define ZXID_MAX_SOAP_RETRY 5 /* Maximum retries due, e.g., EndpointMoved */
In mod_auth_saml the URL ending that triggers session management (e.g. SLO MNI).
In mod_auth_saml the prefix (potentially empty) for attributes brought into environment.
(default: "SAML_")
In mod_auth_saml generate REMOTE_USER subprocess environment variable.
(default: 1)
#define ZXID_DEFAULTQS "" /* Default Query String used by mod_auth_saml for protected page */
If ANON_OK is set and matches prefix of the local URL, SSO failure does not block protected content from being shown. While this usually is a security problem, in some circumstances you may want to show error message or nonpersonalized content from the application layer. If application checks that the SSO really happened, then there is no security problem - the responsibility is application's. Typically ANON_OK=/dir/ is used with IsPassive (fp=1) to implement personalization if user already has session, but allow the user to access page anonymously without logging in if he does not have session.
(default: 0)
This can be used to ensure that the IdP has authenticated user sufficiently. In some cases this can trigger step-up authentication. Value should be dollar separated string of acceptable authn context class refs, e.g. "" If step-up authentication is triggered, you need to ensure the fa query string argument of the IdP selection page also requests the desired authentication contrext class reference. If not specified, then any authentication context is acceptable.
(default: 0)
What authentication context IdP issues for password authentication. The problem here is that ZXID does not know whether transport layer is TLS (assumed). If it is not, you should configure this to be "urn:oasis:names:tc:SAML:2.0:ac:classes:Password" or you can configure this according to your IdP operational policies.
(default: "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport")
If SP does not manifest preference regarding the binding for Assertion Consumer Service, then this IdP preference is used, unless SP metadata indicates it can not support this binding, in which case the first ACS from metadata is used.
(default: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST")
these attributes, if they are defined for the user. Comma separated list.
(default: "zxidvers,zxidloa")
#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 ""
If PDP_URL is set, then the indicated PDP will be consulted in the end of SSO, i.e. by zxid_simple(). PDP_CALL_URL is used if zxid_az() family of functions are called. If PDP_CALL_URL is not set, but PDP_URL is set, the PDP_URL value will be used by zxid_az(). If you always want to explicitly call zxid_az() and do not want zxid_simple() to make implicit calls to PDP, just set PDP_CALL_URL and leave PDP_URL as 0.
(default: 0)
(default: 0)
appropriate discovery options are passed, then the indicated PDP will be consulted during discovery processing to determine if a service should be returned. Default value 0 prevents such processing.
(default: 0)
and Privacy Negotiation call. For this to work, there must be discovery registration for service type urn:tas3:cpn-agent as well.
(default: 0)
0x01: prevent WS-Security header in SOAP XACML requests.
(default: 0)
e.g. "2.0" or "2.0-cd1" or "xac-soap"
#define ZXID_XASP_VERS "2.0"
Empty means not to pass PolicySetIdReference.
*** implement (default: "")
The ZXIDCOMMAP can only be specified at compile time. At run time each map has to be specified separately, sorry. The order of processing rules has not been fixed yet, but currently (Feb2011/R0.76) the first rule is processed last, e.g. the "env*" stanza that appears as first below causes all other attributes to be considered environment attributes. See documentation for INMAP for syntax of the stanzas.
(default: "env*;subjidpnidrenameurn:oasis:names:tc:xacml:1.0:subject:subject-id;subjurn:oasis:names:tc:xacml:1.0:subject:subject-id;subjurn:oid:1.3.6.1.4.1.5923.1.1.1.1;subjurn:oid:1.3.6.1.4.1.5923.1.1.1.7;subjeduPersonAffiliation;subjeduPersonEntitlementsubjrole;rsrcrsrenameurn:oasis:names:tc:xacml:1.0:resource:resource-id;rsrcurn:oasis:names:tc:xacml:1.0:resource:resource-id;actActionrenameurn:oasis:names:tc:xacml:1.0:action:action-id;acturn:oasis:names:tc:xacml:1.0:action:action-id;envZXIDPEPvers;cookiedel;setcookiedel")
in format nsArulebext
#define ZXID_PEPMAP ZXID_COMMAP
in format nsArulebext
(default: ZXID_COMMAP)
in format nsArulebext
#define ZXID_PEPMAP_RQIN ZXID_COMMAP
in format nsArulebext
(default: ZXID_COMMAP)
in format nsArulebext
#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"
to pass all attributes (except dangerous ones) through. idpsesid is blocked on grounds of being a sessionwide correlation handle.
(compile) (default: "*;idpsesiddel")
Comma separated lists.
#define ZXID_LOCALPDP_ROLE_PERMIT 0 /* Whitelist of roles (empty: anything goes) */
Blacklist of roles (default: "local_deny")
Whitelist of permitted users (empty: anything goes) (default: 0)
Blacklist of denied users (default: "denynid")
(unless an explicit UsageDirectives header is specified by caller), require, generate, and accept.
String: WSC pledged obligations in SOL notation (default: 0)
String: WSP required obligations in SOL notation (default: 0)
String: WSP obligations emitted on resp (default: 0)
String: WSC acceptable obligations in SOL notation (default: 0)
These allow simple branding and customization. If these options are not enough for you, consider simply rendering your own forms.
are hidden and POST profile is used
(default: 0)
Edit this to change the colors. But usually you should be editing stylesheet or template.
(compile) (default: "
This template is used by Service Provider to render the SP "login" screen which really is the IdP selection screen (as the authentication login is done on IdP side).
(default: "idpsel.html")
Used if the path does not work. This is really meant to be the last resort.
(default: "
0 = popup menu 1 = buttons 2 = branded image buttons (not implemented as of 20100922)
(default: 0)
(default: 0)
(default: 1)
(default: 2)
If the IDP_SEL_TEMPL_FILE or IDP_SEL_TEMPL, above, is not sufficient for your customization needs, you can provide URL to page of your own design. This page will receive as query string argument the relay state. 0 (zero) disables.
(default: 0)
#define ZXID_NEW_USER_PAGE 0
(default: 0)
#define ZXID_ATSEL_PAGE 0
If the template customization options are not sufficient, you can provide URL to page of your own design. If set, takes priority over AN_TEMPL_FILE. 0 (zero) disables.
(default: 0)
#define ZXID_AN_TEMPL_FILE "an-main.html"
Used if the path does not work. This is really meant to be the last resort.
(default: "
#define ZXID_POST_TEMPL_FILE "post.html"
Used if the path does not work. This is really meant to be the last resort.
(default: "
If the template customization options are not sufficient, you can provide URL to page of your own design. If set, takes priority over ERR_TEMPL_FILE. 0 (zero) disables.
(default: 0)
#define ZXID_ERR_TEMPL_FILE "err.html"
Used if the path does not work. This is really meant to be the last resort.
(default: "
(default: "
(default: "
(default: "
(default: "
(default: "
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.
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).
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.
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.
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
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.
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.
The SP Login, a.k.a. IdP selection, page shows, but SSO does not work
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.
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.
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.
You supplied IdP URL that, in fact, is not the well known location for fetching IdP metadata. Or the IdP does not have well known location enabled. In the latter case you will need to install the IdP metadata manually . See [SAML2meta] section 4.1 "Publication and Resolution via Well-Known Location", p.29, for normative description of this method.
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.
Personal firewall blocks access. Check firewall set up on
browser machine
SP machine
IdP machine
The SP Login, a.k.a. IdP selection, page does not show at all
Connectivity issue at web browser level. Make sure your web browser can resolve both SP and IdP domain names. Edit /etc/hosts as needed.
Personal firewall blocks access. Check firewall set up on
browser machine
SP machine
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.
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.
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.
Writes a user...
tb77f96c0 zxidmeta.c:352 zxid_get_ent_by_sha1_name zxid d Trying sha1_name(cot) open (vopen_fd_from_path): No such file or directory
Did you create the /var/zxid hierarchy (make dir) and make sure your web user (nobody?) has write permission to the log directory? Or did you configure it to use some other directory than /var/zxid?
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
If configuration appears to be prematurely truncated, then see if you need to adjust ZXID_MAX_CONF (default 4KB) in zxidconf.h and recompile.
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=