1<<if: ZXIDBOOK>> 2<<else: >>Configuring ZXID 3################ 4<<author: Sampo Kellom�ki (sampo@iki.fi)>> 5<<cvsid: $Id: zxid-conf.pd,v 1.11 2010-01-08 02:10:09 sampo Exp $>> 6<<class: article!a4paper!!ZXID Conf 02>> 7<<define: ZXDOC=ZXID Configuration>> 8 9<<abstract: 10 11ZXID.org Identity Management toolkit implements standalone SAML 2.0 and 12Liberty ID-WSF 2.0 stacks. This document explains configuration options 13of ZXID. 14 15>> 16 17<<maketoc: 1>> 18 191 Introduction 20============== 21 22ZXID, out-of-box, needs very little configuration. Generally you 23only need to decide the URL and NICE_NAME of your web site. 24 25Compile time configuration, based on Makefile and zxidconf.h is 26explained in separate 27document <<link:zxid-install.html: ZXID Compilation and Installation>>. 28 29In addition to setting runtime configure options, you will need to 30join a Circle of Trust - or create your own. This part of 31set-up is explained in <<link:zxid-cot.html: Building CoT>>. 32 33If you are interested in using mod_auth_saml Apache module, 34you can perform some of the configuration in the Apache httpd.conf 35file as explained in <<link:../mod_auth_saml/mod_auth_saml.html: mod_auth_saml>>. 36 37You should remember that some of the configuration will happen in the 38web server level, see your web server's configuration reference, e.g. httpd.conf 39 401.1 Other documents 41------------------- 42 43<<doc-inc.pd>> 44<<htmlpreamble: <title>Configuring ZXID</title><link type="text/css" rel=stylesheet href="zx.css"><body><h1>Configuring ZXID</h1> >> 45 462 Configuring and Running 47========================= 48<<fi: >> 49 50ZXID ships with working demo configuration so you can run it right 51away and once you are familiar with the concepts, you can return 52to this chapter. 53 54> Tip: You can view current configuration by supplying URL suffix ?o=d, 55> e.g. http://sp1.zxidsp.org:8080/sso?o=d 56 572.1 Overview of Configuration 58----------------------------- 59 60The bare built-in configuration will allow you to test features of 61ZXID, but +should not be used in production+ because it uses default 62certificates and private keys. Obviously the +demo private key is of 63public knowledge+ since it is distributed with the ZXID package, and as 64such +it provides no privacy protection what-so-ever+. For production 65use you MUST obtain or generate your own certificate and private key. 66 67Minimal configuration file /var/zxid/zxid.conf is as follows (see sections "ZXID 68Configuration File Format", "Configuration Parameters", "Full 69Configuration Option Reference", and file zxidconf.h for full 70explanation): 71 72 # Demo /var/zxid/zxid.conf file 73 CPATH=/var/zxid/ 74 BURL=https://sp.mydomain.com:8443/zxid 75 BUTTON_URL=https://sp.mydomain.com:8443/mysp-saml2_icon_150x60.png 76 NICE_NAME=My SP's human%0areadable name. 77 ORG_NAME=My Company, Inc. 78 ORG_URL=http://www.mycompany.be/ 79 LOCALITY=City of Industry 80 STATE=Vlaams 81 COUNTRY=BE 82 #EOF 83 84Usually configuring a system involves the following tasks 85 861. Configure a safe operating environment. In addition to physical 87 security and vetting personnel, this typically involves following 88 sysadmin tasks (be sure to have competent sysadmim understand 89 and implement these): 90 91 a. Install machine (instantiate) from reliable OS media, secure logins and 92 have rigour in issuance of ssh credentials and sudo root rights 93 b. Harden system by eliminating unnecessary services, applying patches, and 94 configuring firewalls (decide which ports you use: typical is 443 for https) 95 c. Implement encrypted filesystem to protect /var/zxid directory (or other 96 ZXID directories depending on your chosen filesystem layout). In implementing 97 encrypted filesystem, pay attention to narrow key distribution and escrow procedures. 98 These need to cater for reboots (manually supply passphrase for the encfs) 99 and disaster recovery scenarios. 100 d. Implement secure log collection, analysis, and storage (encrypt data at rest) 101 e. Implement secure backup. Encrypt data at rest, e.g. using pgp(1). Do not 102 forget key escrow. 103 f. Register domain names and have certificates issued 104 1052. Configure web server (see your web server documentation) 106 107 a. HTTPS operation and TLS certificate. In the minimum you need 108 the main site, but you may want to configure the Common Domain 109 Cookie virtual host as well. 110 111 b. Arrange for ZXID to be invoked. This could mean configuring 112 zxidhlo, zxid-java.sh, or zxidhlo.pl to be recognized as a CGI script, or 113 it could mean setting up your ~mod_perl~ or ~mod_php~ system to call 114 ZXID at the appropriate place. 115 1163. Configure ZXID, including signing certificate and CoT with peer metadata 117 118 a. Edit the configuration options (e.g. in /var/zxid/zxid.conf, but see below). 119 You must set at least BURL and NICE_NAME. 120 121 b. Generate or acquire certificate 122 123 c. Obtain peer metadata (from their well known location) or 124 enable +Auto CoT+ feature (see below). You can also 125 use zxcot(1) command line tool to import their metadata. 126 1274. Configure CoT peers with your metadata. They can download your 128 metadata from your well known location (which is the URL that 129 is your entity ID, usually ending in "?o=B"). For this to happen you 130 need to have a web server and ZXID up and running. Other route 131 is to use zxcot(1) command line tool, e.g. 132 133 zxcot -c BURL=https://example.com/sso -c NICE_NAME='Your SP Brand' -m >your-md.xml 134 135 to generate metadata and then manually transfer it to CoT peers. 136 1375. If you are setting up an IdP (especially with Discovery), you need 138 to address several other points. Please see zxid-idp.pd for 139 further information. 140 1412.2 Sources of Configuration 142---------------------------- 143 144The configuration options of ZXID can be set using various methods, 145with later occurrance of an option overriding the previous value. 146Thus default configuration can (and should) provide most options, 147while you can override the ones that interest your particular 148deployment (you should override at least BURL and NICE_NAME). 149The order, from earliest application to last application, 150of the sources of configuration options is as follows: 151 1521. Compile time default configuration, see zxidconf.h 153 1542. Default configuration file /var/zxid/zxid.conf (n.b. this file 155 need not exist, in which case it does not affect the configuration) 156 1573. VPATH configuration file /var/zxid/<host:port>/zxid.conf (n.b. this file 158 need not exist, in which case it does not affect the configuration). 159 See (10) for full description. 160 1614. ZXID_PRE_CONF environment variable, if supplied 162 1635. Configuration string passed as an argument to one of the 164 API calls, e.g. zxid_new_conf_to_cf() or zxid_simple(). Usually 165 this is a hardwired string that the application programmer 166 provides, but the programmer might provide application dependent 167 mechanism to configure it. 168 1696. ZXID_CONF environment variable, if supplied 170 1717. In case of mod_auth_saml, the ZXIDConf options in the 172 httpd.conf file (in some distributions apache2.conf) 173 1748. In case of command line utilities, like zxcot(1), 175 commandline flags like -c OPT=VAL or -ci (for default IdP config) 176 1779. If CPATH configuration option is changed by any of the above methods (2)-(8), 178 a new configuration file CPATH $ "zxid.conf" (where $ (dollar) denotes 179 string concatenation) is read and evaluated at the spot where 180 the CPATH changed (i.e. such configurations are evaluated in the middle 181 of the other methods). 182 18310. If VPATH configuration option is changed by any of the above methods, 184 a new configuration file CPATH $ fold(HTTP_HOST) $ "zxid.conf", 185 where $ (dollar) denotes string concatenation and fold() denotes function squashing 186 all suspicious characters to underscores, is read and evaluated at the spot where 187 the VPATH is changed (i.e. such configurations are evaluated in the middle 188 of the other methods). 189 190 The VPATH option is meant to implement a virtual hosting feature where 191 the CPATH is automatically determined from apparent host name and port 192 number, and consequently different zxid.conf is read for each virtual 193 host. The feature is on by default, but if no corresponding file 194 is found, no configuration change happens. If the file is found, then 195 CPATH is also changed. Thus unlike in many other cases, for virtual 196 hosting the virtual host specific zxid.conf files are mandatory. 197 This makes sense as NICE_NAME, et al. should be specified anyway. 198 199Interplay of the respecification of CPATH (you can specify even the same path) 200and other configuration methods allow all sorts of *default scenarios* 201to be implemented. For example, specification like 202 203 BURL=http://sp1.zxidsp.org:8080/sso&CPATH=/var/zxid/&PEP_ENA=0 204 205sets the BURL configuration option, then rereads the /var/zxid/zxid.conf 206configuration file which allows BURL to be overridden in the configuration 207file, but finally disables the PEP functionality such that it overrides 208the configuration file (unless some later configuration 209source causes the configuration file to be reread anyway). 210 211> N.B. Avoid recursive speficications of CPATH and/or VPATH. They will be 212> expanded to depth of 5, but are almost always errors. 213 2142.3 Virtual Hosting 215------------------- 216 217As alluded in bullet (10) above, ZXID supports hostname based virtual 218hosting (multihoming). For this setup you would lay out your /var/zxid 219directory as follows 220 221 /var/zxid/ 222 | 223 +-- zxid.conf Main configuration file for generic options 224 +-- pem/ Not used 225 +-- cot/ Not used 226 +-- ses/ Not used 227 +-- log/ Some pid files (but see virtual host specific log dir) 228 | 229 +-- <host1:port> Virtual host specific subdirectory (VPATH) 230 | | 231 | +-- zxid.conf VPATH configuration file 232 | +-- pem/ VPATH certificates 233 | +-- cot/ VPATH metadata of CoT partners 234 | +-- ses/ VPATH sessions 235 | `-- log/ VPATH log and pid files 236 | 237 `-- <host2:port> Virtual host specific subdirectory (VPATH) 238 | 239 +-- zxid.conf VPATH configuration file 240 +-- pem/ VPATH certificates 241 +-- cot/ VPATH metadata of CoT partners 242 +-- ses/ VPATH sessions 243 `-- log/ VPATH log and pid files 244 245For virtual hosting to work, the web server layer must also be 246configured to support virtual hosting. In Apache2 httpd this can be 247done using ~VirtualDocumentRoot~ directive and directory layout where 248each virtual host has a subdirectory named after its hostname 249(preferred and philosphically similar to our approach), or using 250<VirtualHost> directive blocks (more laboursome as you need to 251explicitly include such blocks to your config file). 252 253> N.B. Another way to implement virtual hosting, that only works 254> with mod_auth_saml, is to use Apache2 httpd.conf 255> file where each <VirtualHost> section specifies different 256> CPATH using ZXIDConf directive. 257 258For virtual hosting in Tomcat, there are two cases: if Apache2 httpd 259is a frontend, as it often is to implement https (recommended), then 260above instructions apply. If, however, you want to run Tomcat itself 261directly on virtual host basis, you need to consult Tomcat 262documentation (which the author has not tried, so there is no 263guarantee). 264 265If you use mini_httpd, then you need to run one server per IP address 266+ port number combination. (If https is not involved, you could 267use mini_httpd -v with directory layout, but this is not recommended 268because all identity related services should be https.) 269 2702.4 Important Configuration Options 271----------------------------------- 272 273For full reference of the configuration parameters, see section "Full 274Configuration Option Reference", below, or the file zxidconf.h. 275 2762.4.1 NICE_NAME: SP Nickname for IdP User Interface 277~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 278 279IMPORTANT: You should really configure this option. It is an 280important part of your +branding+ towards customers. 281 282The nice name may be used by IdP user interface to refer to the SP. It 283is usually a short human readable name or description. It will also 284appear in metadata as Organization/OrganizationDisplayName 285 286NICE_NAME:: (default: "ZXID configuration NICE_NAME: Set this to describe your site to humans") 287 2882.4.2 BURL: Web Site URL - root of EntityID 289~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 290 291MUST: Failure to config this option usually blocks zxid from operating. 292 293The URL for most zxid operations. It must end in whatever 294triggers the ZXID functionality in the web server (which depends on 295how you have configured the web server, see httpd.conf). The hostname 296and port number should match the server under which zxid CGI is 297accessible. N.B. There is no explicit way to configure Entity ID 298(Provider ID) for the zxid SP. The Entity ID is always of form 299BURL?o=B .<<footnote: Actually there is: BARE_URL_ENTITYID option, 300but that is an advanced topic and will not be discussed here.>> For 301example 302 303 https://sp1.zxidsp.org:8443/zxid?o=B 304 305BURL:: (default: "https://sp1.zxidconf-you-should-set-URL-conf-variable-to-some-useful-and-site-dependent-value.org:8443/zxid") 306 3072.4.3 zxidroot (CPATH configuration parameter) 308~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 309 310The root directory of ZXID configuration files and directories. By default this 311is /var/zxid and has following directories and files in it 312 313 /var/zxid/ 314 | 315 +-- zxid.conf Main configuration file 316 +-- pem/ Our certificates 317 +-- cot/ Metadata of CoT partners (metadata cache) 318 +-- ses/ Sessions 319 `-- log/ Log files, pid files, and the like 320 321See also zxid-log.pd for detailed description of the filesystem layout. 322 3232.4.4 pem 324~~~~~~~~~ 325 326Directory that holds various certificates. The certificates 327have hardwired names that are not configurable. 328 329ca.pem:: Certification Authority certificates. These are used for 330 validating any certificates received from peers (other sites 331 on the CoT). The CA certificates may also be shipped to the 332 peers to facilitate them validating our signatures. This is 333 especially relevant if the certificate is issued by multilayer CA 334 hierarchy where the peer may not have the intermediate CA certificates. 335sign-nopw-cert.pem:: The signing certificate AND private key (concatenated 336 in one file). The private key MUST NOT be encrypted (there will not 337 be any opportunity to supply decryption password). 338enc-nopw-cert.pem:: The encryption certificate AND private key (concatenated 339 in one file). The private key MUST NOT be encrypted (there will not be 340 any opportunity to supply decryption password). The signing certificate 341 MUST NOT be used as the encryption certificate to avoid key compromise 342 through encryption from compromising the signatures. Attacks that 343 do just this (Backwards Compatibility attacks) are described in 344 http://www.nds.ruhr-uni-bochum.de/research/publications/backwards-compatibility/ 345 346In addition to the above certificates and private keys, you will need 347to configure your web server to use TLS or SSL certificates for the 348main site and the Common Domain site. We suggest the following naming 349 350ssl-nopw-cert.pem:: SSL or TLS certificate for main site. In order to 351 avoid browser warnings, the CN field of this certificate should match 352 the domain name of the site. The SSL certificate can be same as 353 signing or encryption certificate. 354cdc-nopw-cert.pem:: SSL or TLS certificate for Common Domain Cookie 355 introduction site. In order to avoid browser warnings, the CN field 356 of this certificate should match the domain name of the site. The SSL 357 certificate can be same as signing or encryption certificate. 358 3592.4.5 cot 360~~~~~~~~~ 361 362Directory that holds metadata of the Circle of Trust (CoT) 363partners. If +Auto CoT+ is enabled, this directory needs to be 364writable at run time. 365 366Typical metadata file path would be 367 368 /var/zxid/cot/Inkl5fOnhVNa0LbWjHem2Y2UphY 369 370If the metadata file appears in this directory, then the entity is in 371the CoT. 372 373The file name component of the path is safe base64 encoded 374SHA1 hash of the Entity ID, with last character stripped (that 375character would always be an equals sign). 376 3772.5 ZXID Configuration File Format 378---------------------------------- 379 380Most configuration details are kept as comments in 381zxidconf.h, which you should see. 382 383Configuration file is line oriented. Comments can be introduced with 384cardinal ("#") and empty lines are ignored. End of line comments are NOT 385supported at this time. 386 387Each configuration option is a name=value pair. The name is the same 388as in zxidconf.h except that ZXID_ prefix does not appear. Only 389single line values are supported, but you can embed characters using 390URI encoding, e.g. %0a for newline. In fact, the configuration lines 391are treated as CGI variables, thus & can also be used as separator 392instead of newline (and needs to be encoded if not intended as 393separator). 394 395When option is not specified, the default from zxidconf.h 396prevails. Thus in the following the CPATH specification is redundant. 397 398To give some idea consider following /var/zxid/zxid.conf example: 399 400 # Demo /var/zxid/zxid.conf file 401 CPATH=/var/zxid/ 402 BURL=https://sp.mydomain.com:8443/zxid 403 NICE_NAME=My SP's human%0areadable name. 404 #EOF 405 406The configuration is processed in following order, with 407last instance of an option prevailing: 408 4091. Built in default configuration 4102. Configuration file /var/zxid/zxid.conf 4113. Configuration string passed as first argument. 412 413 Configuration string is processed in order and 414 overrides values from compiled in defaults as well 415 as from zxid.conf in the compiled in default path. 416 417 While processing options, if CPATH is found, the 418 (new) config file is read, effectively overriding any 419 options thus far. 420 421 See section "Sources of Configuration", above, for full 422 description. 423 424Essentially this allows you to provide early in configuration string options that 425can then be overridden by the config file ready by virtue of CPATH apprearing 426in the config string. The options in the string that come later in the string 427can then override values in config file. 428 4293 zxid_simple() API Specific Configuration 430=========================================== 431 432For full description of the simple API, plese see 433<<link:html/zxid-simple.html: zxid_simple()>> Easy API for SAML. 434 435 4363.1.1 Configuration Options 437~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 438 439(*** This section also appears in zxid-simple.pd) 440 441The zxid_simple() can be configured by conf string as argument as well 442as by configuration file. In addition a flags argument is accepted, 443see next subsection "AUTO options", to specify simple API specific 444automation options. 445 446Turns out that often the default configuration modified 447by the configurations string is all you need - you do not 448need to prepare a configuration file. 449 450See section "Configuring and Running" for complete list of 451configuration options, but generally it is 452sufficient to specify only a handful: 453 454CPATH:: Where files are kept and configuration file is found. 455NICE_NAME:: Human readable namme of the SP 456BURL:: The URL of the SP 457CDC_URL:: The Common Domain URL (optional, if omitted 458 the Common Domain Cookie processing is disabled) 459 4603.1.2 AUTO options (auto flags) 461~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 462 463(*** This section also appears in zxid-simple.pd) 464 465The ~auto_flags~ argument allows you to control which 466operations should be performed automatically and 467which should be passed to the calling application, 468see "Gaining More Control" section, below, for 469full description of this case. 470 471The auto options can be added together. 472 473<<table: zxid_simple() AUTO options 474Dec Hex Symbol Description 475===== ====== =================== =========================================== 476 1 0x01 ZXID_AUTO_EXIT Call exit(), 0=return "n", even if auto CGI 477 2 0x02 ZXID_AUTO_REDIR Automatic. handle redirects, assume CGI (calls exit(2)) 478 4 0x04 ZXID_AUTO_SOAPC SOAP response handling, content gen 479 8 0x08 ZXID_AUTO_SOAPH SOAP response handling, header gen 480 16 0x10 ZXID_AUTO_METAC Metadata response handling, content gen 481 32 0x20 ZXID_AUTO_METAH Metadata response handling, header gen 482 64 0x40 ZXID_AUTO_LOGINC IdP select / Login page handling, content gen 483 128 0x80 ZXID_AUTO_LOGINH IdP select / Login page handling, header gen 484 256 0x100 ZXID_AUTO_MGMTC Management page handling, content gen 485 512 0x200 ZXID_AUTO_MGMTH Management page handling, header gen 486 1024 0x400 ZXID_AUTO_FORMF In idp list and mgmt screen, generate form fields 487 2048 0x800 ZXID_AUTO_FORMT In idp list & mgmt screen, wrap in <form> tag. 488 4095 0xfff ZXID_AUTO_ALL Enable all automatic CGI behaviour. 489 4096 0x1000 ZXID_AUTO_DEBUG Enable debugging output to stderr. 490 8192 0x2000 ZXID_AUTO_OFMTQ Output Format Query String 49116384 0x4000 ZXID_AUTO_OFMTJ Output Format JSON 492>> 493 494If the AUTO_REDIR flag is true, the LOCATION header is sent to stdout 495and exit(0) may be called, depending on the AUTO_NOEXIT flag. 496 497The SOAP, META, LOGIN, and MGMT flags follow convention: 498 499 HC 500 00 No automation. Only action letter is returned ("e"=login, "b"=meta, etc.) 501 01 Content, not wrapped in headers, is returned as a string 502 10 Headers and content is returned as a string 503 11 Headers and content are sent to stdout, CGI style and 504 exit(0) may be called, depending on AUTO_EXIT. Otherwise "n" is returned. 505 506Whether exit(0) is called in 11 case depends on ZXID_AUTO_NOEXIT flag. 507 508How much HTML is generated for Login page and Mgmt page in 01 (content only) 509mode depends on AUTO_PAGE and AUTO_FORM flags 510 511 TF 512 00 reserved / nothing is generated 513 01 Only form fields (but not form tag itself) are generated. 514 10 Complete form is generated 515 11 Whole page is generated (best support) 516 517The output format in the successful SSO case depends on OFMT bits 518as follows 519 520 JQ 521 00 LDIF (default) 522 01 Query String 523 10 JSON 524 11 empty res, caller is expected to access ses for attributes 525 5263.1.3 Configuration options for customizing HTML 527~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 528 529(*** This section also appears in zxid-simple.pd) 530 531When whole page is generated, some templating information is taken 532from the configuration. 533 534IDP_SEL_TEMPL_FILE:: Path for Template for IdP Selecton Page. Default "idpsel.html". 535 This file, which you can edit for customization, is used as template to 536 render the IdP selection page on the SP side. If the file does not exist, 537 the value of ZXID_IDP_SEL_TEMPL configuration option is used as template. 538 By default idpsel.html uses idpsel.css as stylesheet. You can make many 539 kinds of customization just by editing this stylesheet. 540 541IDP_SEL_TEMPL:: Template for IdP Authentication Page that is used if the 542 path does not work. This is really meant to be the last resort. The default 543 value of this page is the compiled in template "ZXID SP SSO: Choose IdP". 544 545IDP_LIST_METH:: Choose the method for rendeing IdP list. 546 0 = popup menu, 1 = buttons, 547 2 = branded image buttons (not implemented as of 20100922) 548 549IDP_SEL_PAGE:: IdP Selector Page URL 550 If the IDP_SEL_TEMPL_FILE or IDP_SEL_TEMPL, above, is not sufficient for 551 your customization needs, you can provide URL to page of your own design. 552 This page will receive as query string argument the relay state. 553 0 (zero) disables. 554 555You can set several rather technical configuration options by editing 556the IdP selection template and adding (hidden) form fields. You may 557want to hardwire these or allow user to set them 558 559fc:: Create federation (AllowCreate flag) 560fn:: Name ID format 561 prstnt:: Persistent (pseudonym) 562 trnsnt:: Transient, temporary pseudonym 563 564Technical parameters that the site administrator 565should decide and set. Usually hidden form fields in the template: 566 567fq:: Affiliation ID (usually empty) 568fy:: Consent obtained by SP for the federation or SSO 569 empty:: No statement about consent 570 urn:liberty:consent:obtained:: Has been obtained (unspecified way) 571 urn:liberty:consent:obtained:prior:: Obtained prior to present 572 transaction, e.g. user signed terms and conditions of service 573 urn:liberty:consent:obtained:current:implicit:: Consent 574 is implicit in the situation where user came to invoke service 575 urn:liberty:consent:obtained:current:explicit:: Obtained explicitly 576 urn:liberty:consent:unavailable:: Consent can not be obtained 577 urn:liberty:consent:inapplicable:: Obtaining consent is not 578 relevant for the SP or service. 579fa:: Authentication Context (strength of authentication) needed by the SP 580fm:: Matching rule for authentication strength (usually empty, IdP decides) 581fp:: Forbid IdP from interacting with the user (IsPassive flag) 582ff:: Request reauthentication of user (ForceAuthn flag) 583 5844 ZXID Attribute Broker (ZXAB) 585============================== 586 587<<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.>> 588 589As can be seen in the accompanying figure, the provision of attributes 590to the applications in the Apache subprocess environment (CGI, 591mod_perl, mod_php, etc.) is handled as follows: 592 5931. Configure attribute needs and names (this corresponds to CARML declaration) 5942. Configure attribute sources (this corresponds to AAPML declaration) 5953. Configure source or input mappings (INMAP) 5964. Filter for needs (and optional wants) 5975. Map to application domain (OUTMAP) 5986. Provide attributes in to subprocess environment 5997. Comply with obligations (large part of this responsibility rests 600 with the subprocesses and can not be automatically enforced) 601 602> N.B. For an attribute to be available, four conditions must be 603> met: (i) it must actually exist, (ii) it must be specified in NEED 604> (or WANT, if no absolute guarantee of availability is necessary), 605> (iii) it must pass INMAP, and (iv) it must pass OUTMAP or purpose 606> specific map like PEPMAP. 607 6084.1 Attribute Broker Configuration Directives 609--------------------------------------------- 610 611*** This is provisory specification 612 613The Attribute Broker configuration in Apache set-up is per <Location> 614directive. Different Locations within same server can have different needs. 615 616*Example* 617 618 <Location /protected> 619 ZXIDConf "NEED=CN$GUI$40000000$none$ext" 620 ZXIDConf "NEED=age$adult-content$100000$log-upon-sso,report-to-dashboard-if-avail$ext" 621 ZXIDConf "WANT=birthday$horoscope$40000000$log-upon-sso,must-report-to-dashboard$ext" 622 ZXIDConf "WANT=street,l,st,zip,c$ship$40000000$log-upon-sso,report-to-dashboard-if-avail$ext" 623 </Location> 624 6254.1.1 NEED specification 626~~~~~~~~~~~~~~~~~~~~~~~~ 627 628~NEED~ specification expresses attributes that are required for the 629application to work. Attribute names are in the +Common Namespace+ 630(often same as subprocess environment application 631namespace). Inavailability of the attributes aborts application 632processing. 633 634 NEED=A,B$usage$retention$oblig$ext 635 636A,B:: Names of attributes (comma separated list) needed by subprocess 637 environment 638usage:: The promised usage of the attributes (feeds out to CARML 639 declaration). Specific usage enumerators or policy language 640 are +still To Be Defined+. Special value "reset" clears 641 previous +need+ configuration. 642retention:: The data retention policy that will be applied to these attributes 643 if they are received. Specific enumerators or language 644 are +still To Be Defined+. The example illustrates retention in seconds. 645oblig:: The obligations that will be complied to WRT these attributes 646 if they are received. Specific enumerators or language are +still TBD+. 647ext:: Extension fields to describe attribute policies in more detail. 648 6494.1.2 WANT specification 650~~~~~~~~~~~~~~~~~~~~~~~~ 651 652~WANT~ specification expresses attributes that are optional, but useful, 653for the application. Inavailability of the attributes may cause 654reduced application functionality or the application querying the 655missing attributes directly from the user. ~WANT~ specification 656has same syntax as ~NEED~ specification. Inavailability of the attribute 657has no consequence or may cause default to be supplied. 658 659 WANT=A,B$usage$retention$oblig$ext$default 660 661A,B:: Names of attributes (comma separated list) needed by subprocess 662 environment. If star (*) is specified, all available attributes 663 are requested.<<footnote: This 664 should not be used light heartedly. Much better to spell out explicitly the 665 attribute requirements so that proper CARML description can be made.>> 666usage:: The promised usage of the attributes (feeds out to CARML 667 declaration). Specific usage enumerators or policy language 668 are +still To Be Defined+. 669retention:: The data retention policy that will be applied to these 670 attributes if they are received. Specific enumerators or language 671 are +still To Be Defined+. 672oblig:: The obligations that will be complied to WRT these attributes 673 if they are received. Specific enumerators or language are +still TBD+. 674ext:: Extension fields to describe attribute policies in more detail. 675default:: Optional default value to use in case the attribute is not available. 676 6774.1.3 ATTRSRC specification 678~~~~~~~~~~~~~~~~~~~~~~~~~~~ 679 680The Single Sign-On is an implicit Attribute Source and need not 681be specifically listed. The attribute namespace will be 682IdP's Entity ID. 683 684> N.B. As of Sept 2009, the SSO source is the only one implemented. 685 686Attribute Source (~ATTRSRC~ for short) specification indicates a 687potential source of attribute data and the mechanics for retreiving 688them. Each attribute originating from a determined source is in 689namespace of that source (+source namespace+). This avoids attribute 690naming conflicts and provides for clean attribute renaming 691framework. If an attribute is not renamed, then it is passed to the 692+common namespace+ by just dropping the namespace prefix. 693 694 ATTRSRC=namespace$A,B$weight$accessparamURL$AAPMLref$otherLim$ext 695 696namespace:: Namespace string assigned to this attribute source. 697A,B:: List of attributes available from this source 698weight:: Weighting factor (integer) determining the prioirity of this 699 source. Less indicates higher preference. 700accessparam:: Typically URL for contacting the source, or special 701 value "reset" to clear the list and start building anew. 702AAPMLref:: Reference to AAPML declaration about policies applying 703 to this attribute source 704otherLim:: Description of additional policies applying to this attribute source 705ext:: Extensions 706 707In a Web Service call, on Web Service Provider's side, the implicit 708attribute sources include 709 710* Requester token (assertion). This attribute source will 711 use as namespace the issuer's entity ID. Essentially this is 712 similar to the Single Sign-On assertion treatment. 713* Target Identity token (assertion). This attribute source will 714 use as namespace the issuer's entity ID. Further, the actual 715 attributes are prefixed with "tgt_". 716* Attributes passed in SOL (Simple Obligations Language) formatted 717 UsageDirective. This attribute source will use as namespace the 718 entity ID of the message signer, i.e. the WSC that pledges 719 to respect the obligations. 720 7214.1.4 INMAP specification 722~~~~~~~~~~~~~~~~~~~~~~~~~ 723 724~INMAP~ specification provides for various input attribute renaming and 725input attribute value decoding operations. It is a semicolon separated 726list of stanzas, where stanza components are separated by dollar signs. 727Multiple ~INMAP~ specifications are additive, but the ~INMAP~ list can 728be cleared with special stanza with ~reset~ rule. 729 730 INMAP=ns$A$rule$b$ext 731 732ns:: Source namespace of the attribute 733A:: Attribute name in the source namespace 734b:: Attribute name in common namespace (if omitted, same as +A+) 735rule:: transformation rule: 736 rename:: Just renames the attribute. Value is passed intact. Default. 737 del:: Deletes the attribute. 738 feidedec:: Decode the attribute value accoring to Feide (Norway) rules. 739 Also rename if +b+ provided. 740 feideenc:: Encode the attribute value accoring to Feide (Norway) rules. 741 Also rename if +b+ provided. 742 unsb64-inf:: Decode the attribute value accoring to safebase64-inflate 743 rules ([RFC3548], [RFC1951]). Also rename if +b+ provided. 744 def-sb64:: Encode the attribute value accoring to deflate-safebase64 745 rules ([RFC1951], [RFC3548]). Also rename if +b+ provided. 746 unsb64:: Decode the attribute value according to safebase64 [RFC3548] 747 rule (NZ). Also rename if +b+ provided. 748 sb64:: Encode the attribute value according to safebase64 [RFC3548] 749 rule (NZ). Also rename if +b+ provided. 750 a7n:: Wrap the attribute in a SAML2 assertion 751 x509:: Wrap the attribute in a X509 AC attribute certificate 752 file:: Obtain the value of the attribute from file specified in the +ext+ field 753 a7n-feideenc:: Combination of ~a7n~ and ~feideenc~ 754 a7n-def-sb64:: Combination of ~a7n~ and ~def-sb64~ 755 a7n-sb64:: Combination of ~a7n~ and ~sb64~ 756 x509-feideenc:: Combination of ~x509~ and ~feideenc~ 757 x509-def-sb64:: Combination of ~x509~ and ~def-sb64~ 758 x509-sb64:: Combination of ~x509~ and ~sb64~ 759 file-feideenc:: Combination of ~file~ and ~fedieenc~ 760 file-def-sb64:: Combination of ~file~ and ~def-sb64~ 761 file-sb64:: Combination of ~file~ and ~sb64~ 762 reset:: Special pseudo rule that clears previous map configuration. (e.g. $$reset$$) 763ext:: Extended argument that may be used by some rules. 764 765The order of evaluation of ~INMAP~ stanzas is not defined, therefore it is 766not avisable to include same attribute in two stanzas as only one 767would fire. 768 769*SSO derived attributes* 770 771nameid:: Concatenation of +affid+ and +idpnid+ like: "affid$idpnid". (*** problem with dollar sep) 772 7734.1.5 OUTMAP specification 774~~~~~~~~~~~~~~~~~~~~~~~~~~ 775 776~OUTMAP~ specification provides for various attribute renaming and 777value encoding operations just before passing attributes to the 778subprocess environment (i.e. what CGI scripts see). Syntax and 779available operations are the same as for ~INMAP~. 780 781 OUTMAP=src$A$rule$b$ext 782 7834.1.6 AAMAP specification 784~~~~~~~~~~~~~~~~~~~~~~~~~ 785 786~AAMAP~ specification is used by IdP Attribute Authority feature to 787decide whinc attributes from the .at files to include in the 788assertion. Unlike other MAP directives, AAMAP can not be placed in 789regular configuration. Instead it is looked for in .cf file in 790following paths (first found will be used): 791 792 /var/zxid/idpuid/.all/SP_SHA1_NAME/.cf 793 /var/zxid/idpuid/.all/.bs/.cf 794 795The first allows per SP tweaking of what attributes are sent. The 796latter allows global policy to be set. In absence of either .cf file, 797the default is 798 799 AAMAP=$*$$$;$idpsesid$del$$ 800 801which passes all attributes excapt for ~idpsesid~ (passing ~idpsesid~ would 802cause privacy loss as it can be used as correlation handle). 803 804<<ignore: 8054.1.6 Additional Filtering 806~~~~~~~~~~~~~~~~~~~~~~~~~~ 807 808*** The del rules in INMAP and OUTMAP achive same purpose. 809 810NOT IMPLEMENTED YET! 811 812By default only attributes listed in +NEED+ and +WANT+ specifications are 813passed thru, and even then only if the available usage policies are acceptable. 814However, if additional attributes are available, they can be accepted using 815+WANT+ specification with "*". In this case, some attributes can be filtered 816out using +SUPPRESS+ directive (in fact +SUPPRESS+ applies inconditionally 817to all attributes just before +out-map+ stage): 818 819 SUPPRESS=A,B,C 820>> 821 8225 ZXID XACML PEP (and local PDP) 823================================ 824 825> *Terminology*: PEP = Policy Enforcement Point, PDP = Policy Decision 826> Point, XACML = XML Access Control Markup Language, an OASIS standard 827> architecture and protocol for making authorization decision. 828 829> *Important*: You need a functioning XACML PDP (Policy Decision Point 830> to use this functionality. zxididp includes a PDP that always 831> returns "Permit", unless ~role~ is "deny" - you need to acquire 832> and configure a real PDP, such as commercial (e.g. Axiomatics or 833> Symlabs XACML PDP) or a third party open source PDP (e.g. PERMIS or Sun). 834 835The attributes gathered by the Attribute Broker phase are available 836for authorization decisions. The local authorization is applied before, 837and after, the XACML authorization, if any. 838 839* Explicit Deny stops processing 840* Explicit Allow moves to next phase 841* Lack of Allow or Deny at end of phase moves to next phase 842* Lack of Allow after all phases is Deny 843 8445.1 Local PDP Authorization Functionality 845----------------------------------------- 846 847The authorization module can authorize access locally based on 848 849* List of approved user names or forbidden user names 850* Role attribute having a value or not having a value 851* Authorization token (NI 20090904) (***) 852 853Local PDP specifications have format as follows 854 855 LOCALPDP_ROLE_PERMIT=role,role # Whitelist of roles 856 LOCALPDP_ROLE_DENY=role,role # Blacklist of roles 857 LOCALPDP_IDPNID_PERMIT=idpnid,idpnid # Whitelist of permitted users 858 LOCALPDP_IDPNID_DENY=idpnid,idpnid # Blacklist of denied users 859 860If whitelist exists, anyone not listed is denied. If blacklist 861exists, anyone listed is denied. If both lists exist, then white 862is applied first and black then, i.e. blacklist overrides whitelist. 863 864The lists accumulate over default configuration and repeated instances 865of the configuration directive. The special value "reset" can be used 866to reset any of the lists. 867 868The local PDP authority is consulted at all PEPs, i.e. at SSO, RQOUT1, 869RQIN2, RSOUT3, and RSIN4. 870 871> N.B. It is expected that local PDP will grow in ritchness to address 872> additional common cases, but if you have complex requirements, 873> you should be using an external PDP. 874 8755.2 Configuring XACML PEP for Single Sign-On 876-------------------------------------------- 877 878XACML2 PEP (client) functionality allows an external XACML2 PDP 879(server) to be queried for the authorization decision, permitting 880Single Sign-On to happen. The attributes gathered by the Attribute 881Broker phase are available for formulating the XACML request. 882 883Since the XACML PDP may expect attributes names differently from the 884+Common Namespace+, an additional mapping directive, ~PEPMAP~, is provided. 885It works in a manner similar to ~OUTMAP~ in that it extracts and 886filters attributes from the common pool. The source namespace field 887is used for indicating whether the attribute is 888 889* "subj": Subject Attributes (default: idpnid and role=guest) 890* "rsrc": Resource Attributes (default: URL=url of page) 891* "act": Action Attributes (default: Action=access) 892* "env": Environment Attributes (default: ZXID_PEPvers) 893 894Multiple ~PEPMAP~ stanzas can appear as separate ~PEPMAP~ 895declarations, which are cumulative, or they can be put on single 896~PEPMAP~ separated by semicolon. Within stanzas the fields 897are separated by semicolons: 898 899 ns$srcattr$rule$dstattr$ext 900 901The fields, such as +rule+ are discussed in detail in description of ~INMAP~, above. 902 9035.3 Configuring XACML PEPs for Web Service Calls 904------------------------------------------------ 905 906ZXID implements a four points of control PEP model for 907web service calls. This is adopted from the TAS3 project. 908 909<<dia: stackable-filter-master-pdp:bg,rules,pdp: Four PEP Control Points on the Web Service call path.>> 910 911Each control point extracts the attributes from the common namespace 912of the pool using directives similar to ~PEPMAP~ as follows: 913 914PEPMAP_RQOUT:: Request outbound enforement point on Web 915 Service Client (WSC) side, see (1) in the diagram. 916 Typically this enforcement point can be used to control whether 917 WSC is allowed to talk to the Web Service 918 Provider (WSP). It can also be used to control whether the 919 data whose submission to WSP is contemplated, is allwed 920 to leave the WSC, and if so, under which obligations 921 or usage directives. Finally, this control point can be 922 used to formulate pledges about which obligations the WSC 923 is willing to honour. Again, such pledges are passed 924 as a usage directive on the wire. 925 926PEPMAP_RQIN:: Request inbound enforcement point on WSP side, 927 see (2) in the diagram. This is the main PEP that filters 928 the requests "at the gate" before they get in. When 929 most people think about a PEP, they think about this type 930 of PEP. The ~PEPMAP_RQIN~ can implement tests on 931 requesting identity attributes, target identity (resource 932 owner) attributes, obligations requirements and 933 obligations pledges conveyed in the usage directives, 934 as well as the actual operation contemplated and data 935 in the operation. 936 937PEPMAP_RSOUT:: Response outbound enforcement point on WSP side, 938 see (3) in the diagram. This PEP is in position to 939 filter outbound data before it is returned to the WSC. 940 It can also attach obligations to this data, as usage 941 directives. 942 943PEPMAP_RSIN:: Response inbound enforcement point on WSC side, 944 see (4) in the diagram. This PEP is mainly useful for 945 checking whether the usage directives and obligations 946 attached to the data are acceptable. If not, the 947 data can be rejected at this point. 948 9495.4 Configuring UsageDirectives, including obligations pledges and requests 950--------------------------------------------------------------------------- 951 952All ID-WSF messages, requests and responses, are able to carry 953a UsageDirectives SOAP header, but unfortunately the content and meaning 954of this header is not well specified (as of 2010). In essence, the header can 955carry obligations imposed on the sent data, or it can carry 956a pledge to respect obligations if data is returned. While 957Liberty ID-WSF UsageDirective has no way of separating between 958the two cases, we can make the distinction at the level of the 959XACML <xa:Oblication> tag's ~FullfillOn~ XML attribute. (*** specify values) 960 9615.5 Unix Group Authorization, UNIX_GRP_AZ_MAP 962--------------------------------------------- 963 964Unix Group Authorization is a special authorization mode available 965only on zxid_httpd. The idea is to map SSO attribute, typically role 966or o (organization), to a Unix group and then check if the file, 967that is accessed, gives group read permission to the Unix group. 968World readable files will always be permitted. 969 970To use Unix Group Authorization, first you need to arrange the httpd to 971belong to all Unix groups that you want to use. 972Then you need to organize the IdP to 973send suitable attributes (or configure local attribute store 974to provide the attribute for the user) and finally specify, in 975SP zxid.conf, UNIX_GRP_AZ_MAP, which has the following syntax: 976 977 UNIX_GRP_AZ_MAP=affil$attr$val$group$ext 978 979where 980 981affil:: Specifies who is allowed to supply the attribute. Typically 982 the IdP EntityID. Specifying '**' accepts any IdP, but this 983 is problematic if different IdPs use same attribute name to 984 mean different things. Suffix and prefix matching can be 985 performed using "**" and "*". 986attr:: The name of the SSO attribute, e.g "role" or "o" (organization). 987 Can also be specified as "*", which is interpretted as any 988 user from the IdP specified in affil. No other wild carding 989 is supported. 990val:: The value of the attribute that needs to match. Prefix and 991 suffix matching using "*" is supported. Use | to 992 supply alternatives. 993group:: The Unix group name. 994ext:: Extension field. 995 9966 Full Configuration Option Reference 997===================================== 998 999This section is generated based on comments in zxidconf.h and is 1000updated periodically. See zxidconf.h for authorative definitions. 1001See also zxid.h for ~struct zxid_conf~ which is the internal 1002runtime structure capturing these options. 1003 1004Most of the configuration options can be set via configuration 1005file /var/zxid/zxid.conf or using -O command line flag(s). In 1006config file or on command line you should omit the ZXID_ prefix 1007and use attribute=value syntax separated by newlines or & characters 1008(the parser implements CGI query string syntax with extension that 1009also \n is accepted as separator). 1010 1011N.B. The options marked as "(compile)" can not be set on command line 1012or configuration file. They require a recompile. 1013 1014<<ignore: ./gen-conf-ref.pl <zxidconf.h >foo.pd >> 1015 10166.1 Configuration Options 1017------------------------- 1018 10196.1.1 Compile time configuration enforcement 1020~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1021 1022Whether configuration is entirely determined at compile time by this file 1023or whether it is possible to use a config file or provide options on 1024command line using -c flags (such as via shell script wrapper) or via ZXID_CONF 1025environment variable. When zxid is used as a library, it depends on application to 1026call zxid_parse_conf(). 1027 1028See also ZXID_CONF_PATH compile time macro. 1029 1030Generally we recommend you leave these turned on (1). 1031 1032CONF_FILE_ENA:: (compile) (default: 1) 1033 1034CONF_FLAG:: (compile) ZXID_CONF environment variable and -c flag enable. (default: 1) 1035 1036SHOW_CONF:: Whether configuration is viewable from URL?o=d (default: 1) 1037 1038PATH_MAX_RECURS_EXPAND_DEPTH:: (compile) Max no of includes, nested PATH or VPATH (default: 5) 1039 1040 10416.1.2 VPATH - PATH for a virtual server 1042~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1043 1044The VPATH allows different configuration PATH for different 1045virtual servers (multihoming) to exist, thus allowing 1046different zxid.conf files and different /var/zxid/ subdirectory. 1047If the config file <PATH><VPATH>zxid.conf exists (i.e. /var/zxid/<VPATH>zxid.conf 1048when using default PATH), then the PATH configuration variable is changed 1049to point to the VPATH, and the virtual host specific config file is read. 1050 1051VPATH is rendered by first inserting current PATH, unless VPATH starts by '/', 1052and then rendering each ordinary letter as is, but expanding the 1053following % (percent) specifications, inline: 1054 1055 %% expands as single percent sign 1056 %a access protocol prefix, e.g. "https://" or "http://" 1057 %h the contents of environment variable HTTP_HOST (see CGI spec) This 1058 usually ends in :port if the port is nonstandard (thus usually 1059 you do not need %p or %P). 1060 %p the contents of environment variable SERVER_PORT (see CGI spec) 1061 %s the contents of environment variable SCRIPT_NAME (see CGI spec) 1062 1063> N.B. All other %-specs are reserved for future expansion 1064 1065After % expansion, the values are squashed to file path safe character set. In 1066particular, the / (slash) characters are converted to _ (underscore). 1067 1068VPATH is not really a configuration option on its own right (there is 1069no corresponding entry in struct zxid_conf), but rather a directive 1070that instructs on point of occurrance of the PATH variable (see zxid.h) 1071to change and configuration file to be read. 1072 1073Default value: "%h/" (see definition of PATH for example). 1074See also: VURL, INCLUDE 1075 1076 1077VPATH:: (default: "%h/") 1078 10796.1.3 Configuration file inclusion 1080~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1081 1082 INCLUDE=file - Include a file into configuration. 1083 OPT_INCLUDE=file - Like INCLUDE but does not fail if the file is missing 1084 1085This is an alternative to VPATH and inheritance for implementing multiple 1086entities that share some common configutation, e.g. CONTACT metadata items. 1087 10886.1.4 SP Nickname for IdP User Interface 1089~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1090 1091IMPORTANT: You should really configure this option. 1092The nice name may be used by IdP user interface to refer to the SP. It 1093is usually a short human readable name or description. It will also 1094appear in metadata as Organization/OrganizationDisplayName 1095 1096NICE_NAME:: (default: "Configuration NICE_NAME: Set this to describe your site to humans, see " ZXID_CONF_PATH) 1097 1098 10996.1.5 Branding button image URL for user interfaces 1100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1101 1102IdP BUTTON_URL is (may be) shown in SP IdP selection screens as 1103a button (provided that IDP_LIST_METH=2 (IDP_LIST_BRAND)) that 1104user can click to login using that IdP. 1105 1106SP BUTTON_URL is shown by IdP login screen so user understands which SP 1107requested the SSO. In this use, the "button" is not (usually?) clickable. 1108 1109BUTTON_URL will also appear in metadata as Organization/OrganizationURL, 1110see symlabs-saml-displayname-2008.pdf (submitted to OASIS SSTC) for 1111specification. 1112 1113The BUTTON_URL MUST contain substring "saml2_icon" and size designator (see spec), 1114to distinguish it from other uses of SAML2 MD Organization/OrganizationURL (which 1115are unspecified, but presumably include home page URL; original SAML2 MD spec 1116was too loose). ZXID only supports the usage as button image URL (as of 20111210). 1117BUTTON_URL is typically absolute URL (relative would not make sense as it 1118is referenced from other web site referring to your web site). 1119 1120Typical value:: https://your-site.com/YOUR_BRAND_saml2_icon_150x60.png 1121 1122Other possible values:: Depending on SP user interface, you may 1123 use any of 1124 1125 https://your-site.com/your_brand_saml2_icon_468x60.png 1126 https://your-site.com/your_brand_saml2_icon_150x60.png 1127 https://your-site.com/your_brand_saml2_icon_16x16.png 1128 1129 This allows different types of user interfaces to be rendered, see 1130 PREF_BUTTON_SIZE config option. Check with your Trust Operator 1131 organization to understand the convention they use. 1132 1133 > N.B. As of 20111210, you can only specify one in configuration and 1134 > your own metadata, but any number are tolerated in foreign metadata. 1135 1136If BUTTON_URL is not supplied (the default (0)), the NICE_NAME, and 1137possibly EntityID, is displayed instead. 1138 1139Changing BUTTON_URL requires new metadata export to CoT partners. 1140 1141BUTTON_URL:: By default no button URL is supplied. (default: 0) 1142 1143 11446.1.6 Preferred branding button size (squash or ignore others) 1145~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1146 1147See description of BUTTON_URL, above, for general notion of branding button. 1148 1149Since different user interfaces may require different sizes of branding button, 1150many SAML2 metadata provide several. PREF_BUTTON_SIZE must be a substring 1151of the OrganizationURL for it to be considered as preferred branding button. 1152Branding button will also have "saml2_icon" as substring. Lacking correct size, 1153any other branding button may be squashed to fit the right size, or textual 1154NICE_NAME and possibly EntityID may be displayed instead. Value SHOULD be 1155one of "468x60" (banners only mode, typically one per row), "150x60" (default, 1156multicolumn mode), "16x16" (detailed listing mode, typically with 1157OreanizationDisplayName and EntityID displayed as well). 1158 1159Changing PREF_BUTTON_SIZE requires new metadata export to CoT partners. 1160 1161PREF_BUTTON_SIZE:: (default: "150x60") 1162 1163 11646.1.7 Web Site Base URL - root of EntityID 1165~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1166 1167IMPORTANT: Failure to config this option may block zxid from operating. 1168BURL is the stem for EntityID and most zxid SSO operations. It must end 1169in whatever triggers the ZXID functionality in the web server. The hostname 1170and port number should match the server under which zxid CGI is accessible. 1171The BURL config option may be set dynamically by VURL, see below, or from 1172program code. 1173 1174N.B. There is no explicit way to configure EntityID (ProviderID) for 1175the zxid SP. The EntityID is always of form BURL?o=B, for example 1176https://sp1.zxidsp.org:8443/zxid?o=B 1177 1178Changing BURL may require regenerating certificates (if domain name changed) and 1179requires new metadata export to CoT partners. 1180 1181BURL:: (default: "https://sp1.please-set-BURL-conf-variable-to-some-useful-site-dep-value.org:8443/zxidhlo") 1182 1183 11846.1.8 VURL - BURL for a virtual server 1185~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1186 1187The VURL allows different BURL for different 1188virtual servers (multihoming) to be generated automatically based 1189on the (CGI) environment variables. However, often you would 1190override the BURL in /var/zxid/zxid.conf 1191 1192In VURL each ordinary letter is rendered as is, but the 1193following % (percent) specifications are expanded inline: 1194 1195 %% expands as single percent sign 1196 %a access protocol prefix, e.g. "https://" or "http://" 1197 %h the contents of environment variable HTTP_HOST (see CGI spec). This 1198 usually ends in :port if the port is nonstandard (thus usually 1199 you do not need %p or %P). 1200 %p the contents of environment variable SERVER_PORT (see CGI spec). 1201 %P Similar to %p, but renders a colon before the portnumber, unless 1202 the SERVER_PORT is 443 or 80, in which case nothing is rendered. 1203 This deals with default ports of the https and http protocols. 1204 %s the contents of environment variable SCRIPT_NAME (see CGI spec) 1205 1206> N.B. All other %-specs are reserved for future expansion 1207 1208VURL is not really a configuration option on its own right (there is 1209no corresponding entry in struct zxid_conf), but rather a directive 1210that instructs, on point of its occurrance, the BURL variable (see zxid.h) 1211to be computed. It will not have any effect unless evaluted at run time, 1212thus this "default value" is rather moot. You really need to specify 1213VURL in your own configuration. 1214 1215Default value: "%a%h%s" 1216See also: VPATH 1217 1218Changing VURL may change BURL which requires new metadata export to CoT partners. 1219 1220VURL:: (default: "%a%h%s") 1221 1222 12236.1.9 Override standard EntityID Construction 1224~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1225 1226The best practise is that SP Entity ID is chosen by the SP (and not 1227forced upon SP by IdP). In ZXID this is done by setting BURL, 1228see above. However, should you have to work with an obstinate IdP 1229that refuses to follow this best practise, you can use this option 1230to manually set the Entity ID string. Not following the best practise 1231breaks automatic metadata exchange (Auto-CoT). Recommended 1232value: leave as 0 so that Entity ID is formed from BURL 1233 1234Changing NON_STANDARD_ENTITYID requires new metadata export to CoT partners. 1235 1236NON_STANDARD_ENTITYID:: (default: 0) 1237 1238 12396.1.10 Bare URL EntityID 1240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1241 1242Omit o=B from entity ID, i.e. make the BURL be the entity ID. Values: 0 or 1. 1243 1244Changing BARE_URL_ENTITYID requires new metadata export to CoT partners. 1245 1246BARE_URL_ENTITYID:: (default: 0) 1247 1248 12496.1.11 Illadviced ACS URL Hack 1250~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1251 1252Sometimes an illadvised authority may impose to you Assertion 1253Consumer Service URL, this URL happens to be different than 1254ZXID uses, and you do not have political leverage to change 1255these decisions. In those times you can use this hack to 1256try to map the imposed URL to the one that works in ZXID. 1257Normally you should register at IdP to use the ZXID default 1258URLs (the easiest way to do this is to use metadata). This 1259config option only works in mod_auth_saml. 1260 1261Changing REDIRECT_HACK_IMPOSED_URL or REDIRECT_HACK_ZXID_URL requires 1262new metadata export to CoT partners. 1263 1264REDIRECT_HACK_IMPOSED_URL:: (default: 0) 1265 1266REDIRECT_HACK_ZXID_URL:: (default: 0) 1267 1268 12696.1.12 Additional Metadata Fields 1270~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1271 1272Safe to leave all as NULL. 1273 1274The LOCALITY, STATE, and COUNTRY will appear in certificates 1275so you may want to set them to sensible values. 1276 1277Changing any of the organization or contact details requires 1278regenerating certificates and new metadata export to CoT partners. 1279 1280ORG_NAME:: (default: "Unspecified ORG_NAME conf variable") 1281 1282LOCALITY:: (default: "Lisboa") 1283 1284STATE:: (default: "Lisboa") 1285 1286COUNTRY:: (default: "PT") 1287 1288CONTACT_ORG:: (default: 0) 1289 1290CONTACT_NAME:: (default: 0) 1291 1292CONTACT_EMAIL:: (default: 0) 1293 1294CONTACT_TEL:: (default: 0) 1295 1296 12976.1.13 Federated Username Suffix 1298~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1299 1300If set (by default this is always set when BURL is set, you have to 1301explicitly unset it if you do not want it), causes IdP to include 1302fedusername attribute in the assertion. The value of this attribute 1303will be the (persistent) nameid followed by @ sign and this suffix, 1304for example: FXyysxhM4F6d3DIwrtoiFdi0i@zxidp.org 1305 1306The fedusername attribute is a helper for the SP web sites that 1307are fixated on the notion of needing a username and/or requiring 1308the username to look like an email. By packaging the psedonym this 1309way it is easy to get them to work with minimal modification. 1310N.B. Although it looks like an email address, it is not. Do not try 1311sending mail to it (unless you hack your mailserver to understand it). 1312 1313Does not affect metadata. 1314 1315 1316FEDUSERNAME_SUFFIX:: (default: "set-this-or-url-to-site-dependent-value") 1317 1318 13196.1.14 IdP Attribute Generation Options 1320~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1321 13220x01:: If fedusername is generated, also generate 1323 urn:oid:1.3.6.1.6.1.5923.1.1.1.6 (aka ~eduPersonPrincipalName~) 1324 1325Does not affect metadata. 1326 1327 1328IDPATOPT:: (default: 0x01) 1329 1330 13316.1.15 Common Domain Cookie URL 1332~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1333 1334URL for reading Common Domain Cookie. It must end in "zxid". The hostname 1335and port number should match the server under which zxid CGI is accessible. 1336Specifying empty CDC_URL disables CDC check in zxid_simple() API. 1337 1338Does not affect metadata. 1339 1340CDC_URL:: CDC disabled (default: "") 1341 1342 13436.1.16 CDC designated IdP Handling 1344~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1345 1346How to handle CDC designated IdP. See zxid.h for explanation of constants. 1347 1348Does not affect metadata. 1349 1350CDC_CHOICE:: (default: ZXID_CDC_CHOICE_UI_PREF) 1351 1352 13536.1.17 Metadata Fetching Options (Auto-CoT) 1354~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1355 1356Following four boolean configuration options control how metadata 1357is obtained. It can be in a cache (by default directory /var/zxid/cot) 1358or it can be fetched "on the fly" using the well known location (WKL) 1359method. 1360 1361MD_FETCH:: controls whether fetching is performed. This necessitates 1362 that ZXID was linked with libcurl. If you do not enable fetching, you 1363 will need to populate the cache manually, perhaps by using a web browser 1364 to fetch the meta data xml files from well known location URLs (or other 1365 URLs if you know better) and then running on commandline zxcot -a. 1366 Or you could use zxidcot.pl?op=md or zxcot(1) tool. 1367 1368 N.B. Even if fetching is enabled, the fetch can still fail due to 1369 network connectivity issues or due to other end not supporting it. 1370 1371 MD_FETCH=1:: Fetch from WKL (Auto-CoT) 1372 MD_FETCH=2:: Fetch from metadata authority, see MD_AUTHORITY, below. 1373 1374MD_POPULATE_CACHE:: controls whether ZXID will write the metadata to 1375 the on-disk cache. This requires ZXID_MD_FETCH to be enabled 1376 and the file system permissions of the cache directory 1377 (e.g. /var/zxid/cot) to allow writing. 1378 1379MD_CACHE_FIRST:: controls whether cache will be checked before fetching 1380 is attempted. If cache misses, ZXID_MD_FETCH governs whether fetch 1381 is tried. 1382 1383MD_CACHE_LAST:: If true, metadata is obtained from cache 1384 if fetch was disabled or failed. 1385 1386If you want to control manually your CoT (e.g. because human process is 1387needed to verify that all the paperwork is in place), set MD_FETCH to 0. 1388 1389If you want as automatic operation as possible, set all four to 1. 1390 1391Does not affect metadata of the entity itself (no new exchange needed). 1392 1393 1394MD_FETCH:: The Auto-CoT ena option (default: 1) 1395 1396MD_POPULATE_CACHE:: (default: 1) 1397 1398MD_CACHE_FIRST:: (default: 1) 1399 1400MD_CACHE_LAST:: (default: 1) 1401 1402 14036.1.18 Metadata Authority EntityID 1404~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1405 1406If MD_FETCH=2 and this is set to an EntityID (whose metadata MUST already 1407be in the CoT cache, typically manually populated using zxcot -a) 1408then in situations where metadata is missing, the authority is queried 1409for the missing metadata. The returned metadata 3rd party should be 1410signed by the authority and the authority's own metadata is used 1411in validating the signature. 1412 1413The URL from where the metadata is fetched is formed by looking at 1414<md:AdditionalMetadataLocation> element in the authority's metadata 1415and concatenating the succinct ID of the entity. 1416 1417Usually the authority is the IdP that the SP trusts. This allows 1418centralized management of a Circle of Trust. Such IdP will know 1419to produce the AdditionalMetadataLocation in its own metadata. 1420See also: MD_AUTHORITY_ENA in IdP configuration. 1421 1422Does not affect metadata of the entity itself. 1423 1424 1425MD_AUTHORITY:: (default: 0) 1426 1427 14286.1.19 Load Initial CoT Cache 1429~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1430 1431Whether to load CoT cache from a file containing the concatenated 1432metadata of the Circle of Trust. Some real world federations distribute 1433their metadata this way. Setting this to 0 disables the feature (default). 1434Setting this to file name or path enables this feature. 1435 1436Does not affect metadata of the entity itself. 1437 1438 1439LOAD_COT_CACHE:: (default: 0) 1440 1441 14426.1.20 Automatic Self-signed Cert Generation (Auto-Cert) 1443~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1444 1445If ZXID does not find one of the certificate plus private key pairs 1446it needs to operate, it will generate automatically a self-signed 1447certificate and private key and populate it to the assigned 1448place. The certificate will be valid until the end of the Unix 1449epoch (2037). If you do not want this to happen, you should 1450disable this option and install the certificate - private key pairs 1451manually to 1452 1453 /var/zxid/pem/enc-nopw-cert.pem 1454 /var/zxid/pem/sign-nopw-cert.pem 1455 /var/zxid/pem/logenc-nopw-cert.pem 1456 /var/zxid/pem/logsign-nopw-cert.pem 1457 /var/zxid/pem/ssl-nopw-cert.pem 1458 1459Hint: you can use same certificate - private key pair for 1460all purposes. Just copy the file. 1461 1462Does not affect metadata when correctly used, but beware that if you change 1463certificates, you will need to perform new metadata export to your CoT partners. 1464 1465 1466AUTO_CERT:: (default: 1) 1467 1468 14696.1.21 Authentication Request Signing 1470~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1471 1472Whether AuthnReq is signed by SP (controls both metadata and actual behavior). 1473 1474Changing AUTHN_REQ_SIGN requires new metadata export to CoT partners. 1475 1476AUTHN_REQ_SIGN:: (default: 1) 1477 1478 14796.1.22 IdP Insitence on Signed AuthnReq 1480~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1481 1482Must AuthnReq be signed (controls both IdP metadata and actual behavior, i.e. the check). 1483 1484Changing WANT_AUTHN_REQ_SIGNED requires new metadata export to CoT partners. 1485 1486WANT_AUTHN_REQ_SIGNED:: (default: 1) 1487 1488 14896.1.23 Assertion Signing 1490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1491 1492Whether SP insists that SSO assertions are signed. Affects metadata. The 1493actual insistence on signing is controlled by ZXID_NOSIG_FATAL, far below. 1494Boolean. Recommended value: 1. 1495 1496Changing WANT_SSO_A7N_SIGNED requires new metadata export to CoT partners. 1497 1498WANT_SSO_A7N_SIGNED:: (default: 1) 1499 1500 15016.1.24 SSO SOAP Message Signing 1502~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1503 1504Whether SOAP messages for ArtifactResolution, SLO, and MNI are signed. Whether 1505responses are signed as well. (*** doc) 1506 1507Does not affect metadata. 1508 1509SSO_SOAP_SIGN:: (default: 1) 1510 1511SSO_SOAP_RESP_SIGN:: (default: 1) 1512 1513 15146.1.25 IdP Signing Options 1515~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1516 1517Which components should be signed by IdP in SSO Response and Assertion. 1518Bit mask: 1519 1520 0x01 Assertion should be signed (default and highly recommended) 1521 0x02 The surrounding Response element should be signed 1522 0x03 Both Assertion and Response are signed. 1523 1524Does not affect metadata. 1525 1526SSO_SIGN:: (default: 0x01) 1527 1528 15296.1.26 NameID Encryption 1530~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1531 1532Whether SLO and MNI requests emitted by ZXID will encrypt the 1533NameID (on received requests ZXID accepts either plain or encrypted 1534automatically and without configuration). (*** doc) 1535 1536Does not affect metadata. 1537 1538NAMEID_ENC:: (default: 0x0f) 1539 1540 15416.1.27 Assertion Encryption in POST 1542~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1543 1544Whether to encrypt assertions when using POST bindings. This 1545is enabled by default as it protects against Man-in-the-Middle 1546attack by compromised web browser. Do not disable unless you know 1547what you are doing. 1548 1549Does not affect metadata. 1550 1551POST_A7N_ENC:: (default: 1) 1552 1553 15546.1.28 Position of EncryptedKey relative to EncryptedData 1555~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1556 1557When producing EncryptedID, EncruptedAssertion, or EncryptedAttribute, 1558how is the EncryptedKey stored relative to EncryptedData 1559 15600x00:: Sibling, without Recipient hint (interops with many commercial implementations and Shibboleth Sept 2010) 15610x01:: Sibling, with Recipient hint (interops with many commercial implementations and Shibboleth as of August 2010) 15620x20:: Nested method, i.e. EncryptedData/KeyInfo/EncryptedKey (interops with all versions of Shibboleth and many others) 1563 1564N.B:: SAML2 specs fail to say which approach is preferred, therefore both 1565 approaches are valid. In reading messages ZXID automatically understands both. 1566 This option only controls how outbound messages are generated so that others 1567 can understand them (ideally they would autodetect so we would not need this option). 1568 1569Does not affect metadata. 1570 1571 1572ENCKEY_OPT:: (default: 0x20) 1573 1574 15756.1.29 Controls whether new fedarations can be created during discovery 1576~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1577 1578Does not affect metadata. 1579 1580DI_ALLOW_CREATE:: (default: '1') 1581 1582 15836.1.30 Controls the default NameID Format for discovery 1584~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1585 1586p=persistent, t=transient 1587 1588Does not affect metadata. 1589 1590DI_NID_FMT:: (default: 'p') 1591 1592 15936.1.31 Controls whether assertions emitted by discovery are encrypted 1594~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1595 1596It is highly recommended to encrypt the assertions to avoid man-in-the-middle 1597attacks. 1598 1599Does not affect metadata. 1600 1601DI_A7N_ENC:: (default: 1) 1602 1603 16046.1.32 Control how many levels of bootstraps are added to assertions 1605~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1606 1607Normally 1608only first level is added, i.e. all available bootstraps are embedded in 1609the assertion, but the assertions of the embedded bootstraps only 1610get discovery bootstrap. 2 would cause the assertions of the first order 1611bootstraps to have further bootstraps embedded, etc. Since bootstrap 1612generation tends to be expensive and wasteful, you should use discovery 1613instead and leave BOOTSTRAP_LEVEL set to 1. 1614 1615Does not affect metadata. 1616 1617BOOTSTRAP_LEVEL:: (default: 1) 1618 1619 16206.1.33 WSC Content-Type header generation 1621~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1622 1623For SOAP 1.1 (SOAP11) that TAS3 and IF-WSF2 use, 1624the value should be "Content-Type: text/xml" (n.b. even 1625the header name has to be included) per 1626http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ section 6.1.1 1627If WSP asks this to be anything else, the chances are 1628it is misconfigured, not standards compliant, or using SOAP 1.2. 1629This should be fixed in WSP end. Changing the value in WSC end 1630should only be desperate last resort as it will cause WSC 1631to be incompatible with standards compliant WSPs. 1632 1633Does not affect metadata. 1634 1635WSC_SOAP_CONTENT_TYPE:: (default: "Content-Type: text/xml") 1636 1637 16386.1.34 WSC <a:To> header generation 1639~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1640 1641The default is not to 1642generate which, according to http://www.w3.org/TR/ws-addr-core/ section 3.2 1643produces same semantics as http://www.w3.org/2005/08/addressing/anonymous, 1644i.e. responding end of HTTP connection. Special values: 1645 16460 (null):: No To header generated 1647"#inhibit":: No To header generated 1648"#url":: To header has same value as end point URL (this is the default, see below). 1649Other values:: The value to supply as To header. 1650 1651N.B. Although WS-Addressing states that this header is optional, as it is 1652one of the signed headers, it may have significance in showing the 1653intended recipient of the message (the Audience for the Assertion is 1654an other place where intended recipient is expressed, albeit as 1655entity ID rather than end point URL). 1656 1657Does not affect metadata. 1658 1659WSC_TO_HDR:: (default: "#url") 1660 1661 16626.1.35 WSC <a:ReplyTo> header generation 1663~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1664 1665The default is not to 1666generate which, according to http://www.w3.org/TR/ws-addr-core/ section 3.2 1667produces same semantics as http://www.w3.org/2005/08/addressing/anonymous, 1668i.e. reply to the requesting end of HTTP connection. In 1669liberty-idwsf-soap-binding-2.0-errata-v1.0.pdf value 1670http://www.w3.org/2005/03/addressing/role/anonymous is 1671illustrated, but this is in violation of http://www.w3.org/2005/08/addressing 1672namespace. The Liberty specification also hints that ReplyTo can be 1673omitted to get the default semantics. Special values: 1674 16750 (null):: No ReplyTo header generated 1676"#inhibit":: No ReplyTo header generated 1677"#anon":: http://www.w3.org/2005/08/addressing/anonymous 1678"#anon_2005_03":: http://www.w3.org/2005/03/addressing/role/anonymous 1679Other values:: The value to supply as To header. 1680 1681Does not affect metadata. 1682 1683WSC_REPLYTO_HDR:: (default: 0) 1684 1685 16866.1.36 WSC <a:Action> header generation 1687~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1688 1689The most reliable way 1690to dispatch SOAP web services is to simply look at the first 1691child element of <e:Body>. If, however, you are cursed with 1692having to interoperate with WSP that insists on seeing some 1693specific Action header, this option gives you some control 1694as to what it should be. 1695 1696First method of generating Action header is to pass it in as 1697input to zxid_call(), e.g. 1698 1699 ret = zxid_call(cf, ses, svctype, url, 0, 0, 1700 "<e:Envelope xmlns:e=\"http://schemas.xmlsoap.org/soap/envelope/\">" 1701 "<e:Header>"" 1702 "<a:Action xmlns:a=\"http://www.w3.org/2005/08/addressing\" " 1703 "actor=\"http://schemas.xmlsoap.org/soap/actor/next\" " 1704 "mustUnderstand=\"1\">toimikaa</a:Action>" 1705 "</e:Header>" 1706 "<e:Body><r:Req xmlns:r=\"urn:test\"/></e:Body></e:Envelope>"); 1707 1708This method overrides any other, i.e. if WSC code sees an already existing 1709Action header, it will not replace it. 1710 1711Other methods depend on the WSC_ACTION_HDR option with following special values: 1712 17130 (null):: No Action header will be generated, 1714"#ses":: Look for key "Action" in session attribute pool 1715"#body1st":: Special value that will use the name of the first child element 1716 of the <e:Body> tag. 1717"#body1stns":: Same as #body1st, but will prefix by namespace URI 1718Other values:: cause the Action header to be set to the given value. 1719 1720Does not affect metadata. 1721 1722WSC_ACTION_HDR:: (default: "#body1stns") 1723 1724 17256.1.37 Like WSC_ACTION_HDR, but deals with the HTTP level SOAPAction header 1726~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1727 1728Dependence on HTTP layer header to say what is inside <e:Body> is poor 1729programming and architecture. WSPs should be coded to ignore the 1730SOAPAction http header. 1731 1732The ID-WSF2 default value for this is empty string "", which generally 1733does not cause indigestion to the buggy softwares and causes them to 1734route the request to default place. For semantics of "" and omitting, see 1735http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ section 6.1.1 1736 1737Possible values: 1738 17390 (null):: Do not generate SOAPAction 1740"#inhibit":: Do not generate SOAPAction (use this in configuration) 1741"#same":: Same as <a:Action> SOAP header. This is often the #body1stns, i.e. the namespace 1742 qualified name of the 1st child element of <e:Body> 1743"" (empty string):: the default for ID-WSF 1744Other values:: use the value of this config option as SOAPAction HTTP header. 1745 1746Does not affect metadata. 1747 1748SOAP_ACTION_HDR:: (default: "#same") 1749 1750 17516.1.38 WSC Signing Options 1752~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1753 1754Which components of a web service request should be signed by WSC. 1755Bit mask: 1756 1757 0x01 SOAP Headers 1758 0x02 SOAP Body 1759 0x03 Both Headers and Body are signed. 1760 1761Does not affect metadata. 1762 1763WSC_SIGN:: (default: 0x03) 1764 1765 17666.1.39 WSP Signing Options 1767~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1768 1769Which components of a web service response should be signed by WSP. 1770Bit mask: 1771 1772 0x01 SOAP Headers 1773 0x02 SOAP Body 1774 0x03 Both Headers and Body are signed. 1775 1776Does not affect metadata. 1777 1778WSP_SIGN:: (default: 0x03) 1779 1780 17816.1.40 OAUTH2 / OpenID-Connect1 id_token signing and encryption options 1782~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1783 1784- 'n': alg=none 1785- 'h': alg=HS256 (HMAC using SHA256) 1786- 'r': alg=RS256 (RSA using SHA256) 1787 1788Does not affect metadata. 1789 1790OAZ_JWT_SIGENC_ALG:: (default: 'n') 1791 1792 17936.1.41 JSON client Content-Type header generation 1794~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1795 1796Various styles exist. 1797 1798Does not affect metadata. 1799 1800JSON_CONTENT_TYPE:: (default: "Content-Type: application/json") 1801 18026.1.42 Bit length of identifiers, unguessability 1803~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1804 1805How many random bits to use in an ID. It would be useful if this was 1806such that it produces nice unpadded base64 string, i.e. multiple of 24 bits. 1807Longer IDs reduce chances of random collision (most code does not 1808check uniqueness of ID) and may increase security. For security purposes 1809144 bits is probably good enough. The unguessability of ID has security 1810implications, among others, in session IDs. You may want to use less than 1811144 bits if your application could benefit from shorter IDs (e.g. you target 1812browsers with length constrained URLs) and does not need to be 1813secure against attacks with government level resources. 1814 1815 E.g: 24 bits == 3 bytes == 4 safe_base64 chars, 1816 48 bits == 6 bytes == 8 safe_base64 chars, 1817 120 bits == 15 bytes == 20 safe_base64 chars, 1818 144 bits == 18 bytes == 24 safe_base64 chars 1819 1820Does not affect metadata. 1821 1822ID_BITS:: (compile) (default: 144) 1823 1824ID_MAX_BITS:: used for static buffer allocation (compile) (default: 168) 1825 1826 18276.1.43 True randomness vs. pseudorandom source 1828~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1829 1830Whether true randomness is obtained. 18310=use OpenSSL RAND_pseudo_bytes(), which usually uses /dev/urandom 18321=use OpenSSL RAND_bytes(), which usually uses /dev/random 1833 1834Although true randomness may be more secure, it is operationally 1835problematic because if not enough randomness is available, the 1836system will block (stop) until enough randomness arrives. Generally 1837true randomness is not feasible in a server environment unless 1838you have a hardware random number generator. 1839 1840Does not affect metadata. 1841 1842TRUE_RAND:: (compile) (default: 0) 1843 1844 18456.1.44 Session Archival Directory 1846~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1847 1848If set to a string, indicates a file system directory to which 1849dead sessions are moved (sessions are files). This directory 1850must be on the same file system as active session directory, 1851usually /var/zxid/ses, for example /var/zxid/oldses. 1852You may want to archive old sessions because they contain 1853the SSO assertions that allowed the users to log in. This 1854may have legal value for your application, you may even be required 1855by law to keep this audit trail. On the other hand, other 1856jurisdictions will require you to delete this information. 1857 1858If set to 0, causes old sessions to be unlink(2)'d. 1859 1860Does not affect metadata. 1861 1862SES_ARCH_DIR:: 0=Remove dead sessions. (default: 0) 1863 1864 18656.1.45 Session cookies 1866~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1867 1868For original Netscape cookie spec see: http://curl.haxx.se/rfc/cookie_spec.html (Oct2007) 1869 1870If SES_COOKIE_NAME is nonempty string, then 1871zxid_simple() will look for said cookie and use it as session ID. 1872It will also attempt to set a cookie by that name when new session 1873is created (but this may rely on some support in the calling app, 1874generally the need to set a cookie is expressed by presence of 1875setcookie attribute in the LDIF entry. setcookie specifies what 1876should appear in the Set-Cookie HTTP header of HTTP response). 1877 1878Does not affect metadata. 1879 1880SES_COOKIE_NAME:: (default: "ZXIDSES") 1881 1882 18836.1.46 PTM hint cookie 1884~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1885 1886If PTM_COOKIE_NAME is nonempty string, then 1887zxid_simple() will attempt to set a cookie by that name when new session 1888is created (but this may rely on some support in the calling app, 1889generally the need to set a cookie is expressed by presence of 1890setcookie attribute in the LDIF entry. setcookie specifies what 1891should appear in the Set-Cookie HTTP header of HTTP response). 1892 1893Does not affect metadata. 1894 1895PTM_COOKIE_NAME:: (default: "ZXIDPTM") 1896 1897 18986.1.47 Local user account management 1899~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1900 1901Local user database in filesystem. 1902 1903This is optional unless you require IdP 1904initiated ManageNameID requests to work. Local user account management 1905may be useful on its own right if your application does not yet have 1906such system. If it already has, you probably want to continue to use 1907the application's own system. Local accounts are stored under 1908/var/zxid/user/SHA1 1909 1910Does not affect metadata. 1911 1912USER_LOCAL:: (default: 1) 1913 1914 19156.1.48 Mini IdP 1916~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1917 1918Whether limited IdP functionality is enabled. Affects generated metadata. 1919 1920Affects metadata. 1921 1922IDP_ENA:: (default: 0) 1923 1924 19256.1.49 IdP Proxying, i.e. IdP can be SP towards another IdP. 1926~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1927 1928Affects metadata. 1929 1930IDP_PXY_ENA:: (default: 0) 1931 1932 19336.1.50 Identity Mapper and People Service 1934~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1935 1936Whether limited Identity Mapper and People Service functionality is enabled. 1937For this to work, IDP_ENA=1 is needed. 1938 1939Does not affect metadata. 1940 1941IMPS_ENA:: (default: 0) 1942 1943 19446.1.51 Mini Authentication Service 1945~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1946 1947Whether limited Authentication Service functionality is enabled. 1948Please note that the AuthenticationService implementation at present (2010) 1949is incomplete and fails to properly authenticate and authorize the caller 1950system entity, i.e. anyone who knows a username and password can call it 1951 1952Does not affect metadata. 1953 1954AS_ENA:: (default: 0) 1955 1956 19576.1.52 Metadata Authority 1958~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1959 1960Whether IdP will serve as Metadata Authority (see also MD_AUTHORITY and MD_FETCH=2). 1961Enables generation of <md:AdditionalMetadataLocation namespace="#md-authority"> 1962element in the metadata of the IdP. 1963 1964Changing MD_AUTHORITY_ENA requires new metadata export to CoT partners. 1965 1966MD_AUTHORITY_ENA:: (default: 1) 1967 1968 19696.1.53 Dummy PDP 1970~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1971 1972Whether limited PDP functionality is enabled. 1973Does not affect metadata. 1974 1975PDP_ENA:: (default: 1) 1976 1977MAX_BUF:: (compile) (default: 1024) 1978 1979 19806.1.54 Logging Options 1981~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1982 1983See zxid-log.pd for further explanation. Generally you 1984need error and activity logs to know yourself what is going on. 1985You need the issue logs to know whether other's claims towards you are 1986justified. You need the rely logs to hold others responsible. 1987 1988> N.B. In addition to act, err, rely, and issue logging, there is also 1989> debug logging to stderr, typically found in your web server error.log 1990> or in /var/tmp/zxid.stderr or log/xml.dbg. The debugging logs are 1991> not conteolled by these options - they are controlled by the debug flag. 1992> A production site should not enable debugging logs, as they may cause 1993> exposure of sensitive material, unless there is a problem to investigate. 1994 1995The bits of the value are as follows 1996 1997 0x00 Do not log. 1998 0x01 Log enable 1999 0x06 Signing options 2000 0:: no signing (Px) 2001 2:: sha1 MD only (Sx) 2002 4:: RSA-SHA1 (Rx) 2003 6:: DSA-SHA1 (Dx) 2004 0x08 reserved 2005 0x70 Encryption options 2006 0x00:: no encryption (xP) 2007 0x10:: zip-base64 (xZ) 2008 0x20:: RSA-AES (xA) 2009 0x30:: RSA-3DES (xT) 2010 0x40:: Symmetric AES (xB) 2011 0x50:: Symmetric 3DES (xU) 2012 0x60:: reserved 2013 0x70:: reserved 2014 0x80 reserved 2015 2016N.B. Every encryption and signature has computational cost so be 2017sure to factor this in when doing benchmarks - or disable log enc 2018and sign when performance is at premium. 2019 2020Log signing may help you to argue that log evidence was (not) tampered with. 2021The private key for signing must be available 2022in /var/zxid/pem/logsign-nopw-cert.pem 2023Often this is just a copy of sign-nopw-cert.pem 2024 2025Log encryption may help to keep the logs confidential. 2026For RSA modes the public key for encryption must be available 2027in /var/zxid/pem/logenc-nopw-cert.pem. For symmetric encryption the key 2028is the sha1 hash of file /var/zxid/pem/logenc.key 2029All modes, except 0x01, also RFC1951 zip compress the log line and 2030safe-base64 encode the result of the encryption. 2031 2032None of the logging options affect metadata. 2033 2034LOG_OP_NOLOG:: (default: 0x00) 2035 2036LOG_OP_LOG:: (default: 0x01) 2037 2038LOG_OP_LOG_SIGN:: (default: 0x05) 2039 2040LOG_OP_LOG_ENC:: (default: 0x21) 2041 2042LOG_OP_LOG_SIGN_ENC:: RSA-AES enc + RSA-SAH1 sign (default: 0x25) 2043 2044LOG_ERR:: Log errors to /var/zxid/log/err (default: 0x01) 2045 2046LOG_ACT:: Log activity to /var/zxid/log/act (default: 0x01) 2047 2048LOG_ISSUE_A7N:: Log each issued assertion to /var/zxid/log/issue/SHA1/a7n/asn (default: 0x01) 2049 2050LOG_ISSUE_MSG:: Log each issued PDU to /var/zxid/log/issue/SHA1/msg/asn (default: 0x01) 2051 2052LOG_RELY_A7N:: Log each received assertion to /var/zxid/log/rely/SHA1/a7n/asn (default: 0x01) 2053 2054LOG_RELY_MSG:: Log each received PDU to /var/zxid/log/rely/SHA1/msg/MSGID (default: 0x01) 2055 2056LOG_ERR:: (default: 0x00) 2057 2058LOG_ACT:: (default: 0x25) 2059 2060LOG_ISSUE_A7N:: (default: 0x23) 2061 2062LOG_ISSUE_MSG:: (default: 0x45) 2063 2064LOG_RELY_A7N:: (default: 0x41) 2065 2066LOG_RELY_MSG:: (default: 0x11) 2067 2068 20696.1.55 Choice of log given Error or Action 2070~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2071 2072Each operation has its status code and generally those lines that indicate 2073successful status (or intermediate status like "continue" or "redirect") 2074are considered normal activity. However, you may want to consider 2075carefully whether signature failure in assertion or message disqualifies 2076an operation as "activity". One approach is to simply log everything (errors and all) to 2077activity log and rely on some log analysis software to flag the errors. 2078 2079Does not affect metadata. 2080 2081LOG_ERR_IN_ACT:: Log errors to /var/zxid/log/act (in addition to err) (default: 1) 2082 2083LOG_ACT_IN_ERR:: Log actions to /var/zxid/log/err (in addition to act) (default: 1) 2084 2085LOG_SIGFAIL_IS_ERR:: Log line with signature validation error to /var/zxid/log/err (default: 1) 2086 2087 20886.1.56 Log level for activity log 2089~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2090 2091- 0 = Only essential audit relevant events are logged. Note that 2092 there is no way to turn off logging audit relevant events. 2093- 1 = Audit and external interactions 2094- 2 = Audit, external interactions, and significant internal events 2095- 3 and higher: reserved for future definition and debugging 2096 2097Does not affect metadata. 2098 2099LOG_LEVEL:: (default: 2) 2100 2101 21026.1.57 Per user activity logging 2103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2104 2105This option enables logging in /var/zxid/idpuid/UID/.log some key 2106events such as authentication, SSO, and SLO. 2107 2108Does not affect metadata. 2109 2110LOGUSER:: (default: 1) 2111 2112 21136.1.58 Set debug option 2114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2115 2116You can also set this via zxid_set_opt(). 2117 2118- 0 = debug output off 2119- 3 = debug on 2120 2121other values are reserved, experimental, or otherwise undocumented. 2122Setting debug option will enable numerous, sometimes copious, debugging 2123messages to stderr, which often ends in web server's error.log file. 2124This option may also create log/xml.dbg file. 2125 2126Does not affect metadata. 2127 2128DEBUG:: (default: 0) 2129 2130 21316.1.59 Send debug output to a file 2132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2133 2134You can also set this via zxid_set_opt_cstr(). 2135 2136By default the debug output goes to stderr, which often goes to 2137web server's error.log. 2138 2139Does not affect metadata. 2140 2141DEBUG_LOG:: (default: 0) 2142 2143 21446.1.60 Audit Bus servers 2145~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2146 2147Multiple, comma separated, URLs may be 2148specified (audit bus servers are instances of zxbusd, which see). 2149If no BUS_URL is configured, no audit bus logging is performed. 2150 2151Does not affect metadata. 2152 2153BUS_URL:: (default: 0) 2154 2155 21566.1.61 Audit bus password if not using ClientTLS 2157~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2158 2159Generally using ClientTLS is RECOMMENDED and the certificate is taken 2160from metadata encryption certificate field so there is nothing 2161special to configure here. However, if for some reason you 2162need to run plain TLS, with STOMP 1.1 passcode filed for authentication, 2163the set this option to the passcode. Note that using passcode is much 2164less secure than using ClientTLS. Another limitation of BUS_PW 2165approach is that it is shared across all audit bus servers. 2166 2167Does not affect metadata. 2168 2169BUS_PW:: (default: 0) 2170 2171 21726.1.62 How Audit Bus receipts are issued. 0x00 = no receipt, 0x01 = plain, 0x05 = RSA-SHA1. 2173~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2174 2175Does not affect metadata. 2176 2177BUS_RCPT:: (default: 0x05) 2178 2179 21806.1.63 Assertion validation options. 2181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2182 2183These MUST all be turned on (and assertions signed) 2184if you want to rely on assertions to hold the other party liable. 2185 2186Do not affect metadata. 2187 2188SIG_FATAL:: Signature validation error is fatal (prevents SSO) (default: 1) 2189 2190NOSIG_FATAL:: Missing signature is fatal (prevents SSO) (default: 1) 2191 2192MSG_SIG_OK:: Message layer signature (e.g. SimpleSign) is sufficeint when assertion signature is missing. (default: 1) 2193 2194AUDIENCE_FATAL:: Whether AudienceRestriction is checked. (default: 1) 2195 2196TIMEOUT_FATAL:: Whether NotBefore and NotOnOrAfter are checked (default: 1) 2197 2198DUP_A7N_FATAL:: Whether duplicate AssertionID is considered fatal. (default: 1) 2199 2200DUP_MSG_FATAL:: Whether duplicate MessageID or message is considered fatal. (default: 1) 2201 2202RELTO_FATAL:: Whether failure to correlate RelatesTo to MessageID, or total lack of RelatesTo, is considered fatal. (default: 1) 2203 2204 22056.1.64 Web service request and response validation options 2206~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2207 2208For the token in the request, the assertion validation options apply. 2209 2210Do not affect metadata. 2211 2212WSP_NOSIG_FATAL:: Missing Security/Signature is fatal. (default: 1) 2213 2214NOTIMESTAMP_FATAL:: Missing Security/Timestamp is fatal. (default: 1) 2215 2216 22176.1.65 XML canonicalization compatibility kludges 2218~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2219 2220Shibboleth 2.1.5 IdP miscanonicalizes by 2221ignoring InclusiveNamespaces/@PrefixList, yet 2222it still supplies such list. The miscanonicalization 2223leads namespaces missing. This has been reported to Scott Cantor as of 20101005 2224 2225Set this option to 0x01 to avvoid the trouble. 2226 2227Does not affect metadata. 2228 2229CANON_INOPT:: default 0 2230 2231 22326.1.66 XML encoding optimizations. 2233~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2234 22351 = optimize close tag of empty elements as <ns:foo/> 2236 2237Does not affect metadata. 2238 2239ENC_TAIL_OPT:: (default: 1) 2240 2241 22426.1.67 SOAP Envelope validation options. In well configured and 2243~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2244 2245bug free environment, you should not need any of these options. 2246Turning them on will reduce security as validations are not made. 2247 22480x01 Skip response header validation entirely, see zxid_wsc_valid_re_env() 2249 2250Does not affect metadata. 2251 2252VALID_OPT:: (default: 0x00) 2253 2254VALID_OPT_SKIP_RESP_HDR:: (default: 0x01) 2255 2256 22576.1.68 Time Slop 2258~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2259 2260Because clock sychronization amoung the servers in the CoT is unlikely 2261to be perfect, not to speak of timezone misconfigurations and the 2262dreaded officially introduced time errors (e.g. daylight "savings" time), 2263you can configure some slop in how the timeout is evaluated. For production 2264use something like 60 seconds could be a good value. 3600 = 1 hour, 86400 = 1 day. 2265All servers of CoT MUST use GMT (aka UTC), not local timezones. You can synchronize 2266clocks with ntpdate pool.ntp.org (see man ntpdate). 2267 2268Slop is used in assessing validity of assertions as well as message timestamps. 2269 2270Time skew allows our end to lie about the time, e.g. if we are in GMT, but 2271the other end is not and therefore we are rejected. Note that the time skew 2272is same for all other ends, therefore this is not really a good solution. 2273Only good solution is to have all servers synchronized to GMT (UTC) as the specs say. 2274 2275While flexibility is nice, there is enough rope here to hang yourself so don't do that. :-) 2276 2277Does not affect metadata. 2278 2279 2280BEFORE_SLOP:: Number of seconds before that is acceptable. (default: 39600) 2281 2282AFTER_SLOP:: Number of seconds after that is acceptable. (default: 7300) 2283 2284TIMESKEW:: Timeskew, in seconds, for timestamps we emit. (default: 0) 2285 2286A7NTTL:: Time To Live for IdP issued Assertions (default: 3600) 2287 2288 22896.1.69 Redirect to Content 2290~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2291 2292Should explicit redirect to content be used (vs. internal redir). With 2293internal redirect there is one over-the-wire transaction less, but 2294the URL appears as whatever was sent by the IdP. With explicit (302) 2295redirect the URL will appear as the true content URL, without the SAML SSO goo. 2296 2297Does not affect metadata. 2298 2299REDIR_TO_CONTENT:: (default: 1) 2300 2301 23026.1.70 ID-WSF SOAP Call parameters 2303~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2304 2305Does not affect metadata. 2306 2307MAX_SOAP_RETRY:: Maximum retries due, e.g., EndpointMoved (default: 5) 2308 2309 23106.1.71 Session Management Trigger Suffix 2311~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2312 2313In mod_auth_saml the URL ending that triggers session management (e.g. SLO MNI). 2314 2315Does not affect metadata. 2316 2317 23186.1.72 Attribute Prefix 2319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2320 2321In mod_auth_saml the prefix (potentially empty) for attributes brought into environment. 2322 2323Does not affect metadata. 2324 2325MOD_SAML_ATTR_PREFIX:: (default: "SAML_") 2326 2327 23286.1.73 Fake Basic Auth by generating REMOTE_USER 2329~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2330 2331In mod_auth_saml generate REMOTE_USER subprocess environment variable. 2332 2333Does not affect metadata. 2334 2335REMOTE_USER_ENA:: (default: 1) 2336 2337 23386.1.74 Query String if None Given 2339~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2340 2341Does not affect metadata. 2342 2343DEFAULTQS:: "" Default Query String used by mod_auth_saml for protected page 2344 2345 23466.1.75 WSP Pattern 2347~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2348 2349Any URL matching this pattern is treated as web service call rather 2350than SSO attempt. Understood by mod_auth_saml, zxid_httpd and mini_httpd_zxid. 2351WSP_PAT is matched before UMA_PAT and SSO_PAT. 2352Does not affect metadata. 2353 2354WSP_PAT:: (default: "*.wsp") 2355 2356 23576.1.76 UMA Pattern 2358~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2359 2360Any URL matching this pattern is treated as web service call protected by UMA rather 2361than SSO attempt. Understood by mod_auth_saml, zxid_httpd and mini_httpd_zxid. 2362UMA_PAT is matched after WSP_PAT but before SSO_PAT. 2363Does not affect metadata. 2364 2365UMA_PAT:: (default: "*/uma/*") 2366 2367 23686.1.77 Single Sign-On URL Pattern 2369~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2370 2371Any URL matching this pattern requires SSO. However 2372WSP_PAT is matched first. Understood by mod_auth_saml (additional 2373Apache configuration needed), zxid_httpd and mini_httpd_zxid. 2374Does not affect metadata. 2375 2376SSO_PAT:: (default: "**") 2377 2378 23796.1.78 Anonymous can see protected content 2380~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2381 2382If ANON_OK is set and matches the local URL - see zx_match(), SSO failure 2383does not block protected content from being 2384shown. While this usually is a security problem, in some circumstances 2385you may want to show error message or nonpersonalized content from the 2386application layer. If application checks that the SSO really happened, 2387then there is no security problem - the responsibility is application's. 2388Typically ANON_OK=/dir/ is used with IsPassive (fp=1) to implement personalization 2389if user already has session, but allow the user to access page anonymously 2390without logging in if he does not have session. 2391 2392*** This option does not prevent the SSO from being tried in the 2393*** first place and consequently, IdP selection will be invoked in any 2394*** case - even if user has no meaningful IdP in mind. This option only 2395*** controls what happens after IdP redirects back without having 2396*** authenticated the user. By clever manupulation of DEFAULTQS and fp=1 2397*** this could be made to work, if there is only one IdP. 2398 2399Does not affect metadata. 2400 2401ANON_OK:: (default: 0) 2402 2403 24046.1.79 Optional Login URL Pattern 2405~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2406 2407If a page matching OPTIONAL_LOGIN_PAT is accessed, then 2408 2409a. If session is already active, session is used and attributes of session 2410 are visible to the page. 2411b. If no session is active, then no login is requested, unless the 2412 URL matches BURL. 2413 2414N.B. This option tries to do what many people try to use ANON_OK for. 2415 2416Does not affect metadata. 2417 2418OPTIONAL_LOGIN_PAT:: (default: 0) 2419 2420 24216.1.80 Required Authentication Context Class Ref. 2422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2423 2424This can be used 2425to ensure that the IdP has authenticated user sufficiently. 2426In some cases this can trigger step-up authentication. 2427Value should be dollar separated string of acceptable authn context 2428class refs, e.g. "" 2429 2430If step-up authentication is triggered, you need to ensure the fa query 2431string argument of the IdP selection page also requests the desired 2432authentication contrext class reference. 2433If not specified, then any authentication context is acceptable. 2434 2435Does not affect metadata. 2436 2437REQUIRED_AUTHNCTX:: (default: 0) 2438 2439 24406.1.81 IdP: Authentication Context Class Ref for Passwords 2441~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2442 2443What authentication context IdP issues for password authentication. The 2444problem here is that ZXID does not know whether transport layer is TLS (assumed). 2445If it is not, you should configure this to be 2446"urn:oasis:names:tc:SAML:2.0:ac:classes:Password" 2447or you can configure this according to your IdP operational policies. 2448 2449Does not affect metadata. 2450 2451ISSUE_AUTHNCTX_PW:: (default: "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport") 2452 2453 24546.1.82 IdP preference for ACS 2455~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2456 2457If SP does not manifest preference regarding the binding for Assertion Consumer Service, 2458then this IdP preference is used, unless SP metadata indicates it can not 2459support this binding, in which case the first ACS from metadata is used. 2460 2461Does not affect metadata. 2462 2463IDP_PREF_ACS_BINDING:: (default: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST") 2464 2465 24666.1.83 List of unsuppressible attributes 2467~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2468 2469Every SSO and discovery will include 2470these attributes, if they are defined for the user. Comma separated list. 2471 2472Does not affect metadata. 2473 2474MANDATORY_ATTR:: (default: "zxidvers,zxidloa") 2475 2476 24776.1.84 Attribute Broker definitions 2478~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2479 2480Do not affect metadata. 2481 2482NEED:: "idpnid,affid,role$undisclosed,log$400000$$" 2483WANT:: "*,authnctxlevel,sesid,setcookie,cookie,rs,cn$undisclosed,log$400000$$" 2484ATTRSRC:: "" 2485INMAP:: "" 2486OUTMAP:: "rsrc$rs$unsb64-inf$$" 2487 2488 24896.1.85 Policy Decision Point (PDP) URLs 2490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2491 2492If PDP_URL is set, then the indicated PDP will be consulted in 2493the end of SSO, i.e. by zxid_simple(). 2494PDP_CALL_URL is used if zxid_az() family of functions 2495are called. If PDP_CALL_URL is not set, but PDP_URL is 2496set, the PDP_URL value will be used by zxid_az(). If you 2497always want to explicitly call zxid_az() and do not want 2498zxid_simple() to make implicit calls to PDP, just set 2499PDP_CALL_URL and leave PDP_URL as 0. 2500 2501Does not affect metadata. 2502 2503PDP_URL:: (default: 0) 2504 2505PDP_CALL_URL:: (default: 0) 2506 2507 25086.1.86 Trust Policy Decision Point (PDP) URL 2509~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2510 2511If TRUSTPDP_URL is set and 2512appropriate discovery options are passed, then the indicated PDP 2513will be consulted during discovery processing to determine if a 2514service should be returned. Default value 0 prevents such processing. 2515 2516Does not affect metadata. 2517 2518TRUSTPDP_URL:: (default: 0) 2519 2520 25216.1.87 Enable CPN 2522~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2523 2524Enable discovery and web service call to perform TAS3 Credentials 2525and Privacy Negotiation call. For this to work, there must be discovery registration 2526for service type urn:tas3:cpn-agent as well. 2527 2528Does not affect metadata. 2529 2530CPN_ENA:: (default: 0) 2531 2532 25336.1.88 Kludgy options for AZ debugging 2534~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2535 2536Also work-around bugs of others. 2537 25380x01:: prevent WS-Security header in SOAP XACML requests. 2539 2540Does not affect metadata. 2541 2542AZ_OPT:: (default: 0) 2543 2544 25456.1.89 Authorization failure mode 2546~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2547 25480x00:: Any failure is Deny (sane default) 25490x01:: Missing PDP_URL or PDP_CALL_URL is Permit (allows you to 2550 run code that makes explicit az calls even if you do not have PDP) 25510x02:: Network connectivity error is Permit (emergency panic 2552 option - do not enable unless you are willing to assume 2553 the liability: that failure to contact PDP is interpretted as Permit 2554 may be the express objective of the attack you are under) 25550x03:: Combine the two above: Missing URL or no connectivity is Permit 25560x04:: Always return Permit (only for development use) 2557 2558Does not affect metadata. 2559 2560AZ_FAIL_MODE:: (default: 0) 2561 2562AZ_FAIL_MODE0_DENY:: (default: 0) 2563 2564AZ_FAIL_MODE1_MISSING_URL:: (default: 1) 2565 2566AZ_FAIL_MODE2_NET_FAIL:: (default: 2) 2567 2568AZ_FAIL_MODE4_PERMIT_ALWAYS:: (default: 4) 2569 2570 25716.1.90 Which version of XACML to speak 2572~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2573 2574E.g. "2.0" or "2.0-cd1" or "xac-soap" 2575 2576Does not affect metadata. 2577 2578XASP_VERS:: (default: "2.0") 2579 2580 25816.1.91 What to pass in XACML PolicySetIdReference when calling PDP 2582~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2583 2584Empty means not to pass PolicySetIdReference. 2585 2586Does not affect metadata. 2587 2588XA_POLICY_SET_ID_REF:: *** implement (default: "") 2589 2590 25916.1.92 Common XACML Attributes for PEPs (compile) 2592~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2593 2594Format ns$A$rule$b$ext 2595 2596The ZXID_COMMAP can only be specified at compile time. At run time 2597each map has to be specified separately, sorry. 2598The order of processing rules has not been fixed yet, but 2599currently (Feb2011/R0.76) the first rule is processed last, e.g. 2600the "env$*$$$" stanza that appears as first, below, causes 2601all other attributes to be considered environment attributes. 2602See documentation for INMAP for syntax of the stanzas. 2603 2604Does not affect metadata. 2605 2606COMMAP:: (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.6.1.5923.1.1.1.1$$$;subj$urn:oid:1.3.6.1.6.1.5923.1.1.1.7$$$;subj$eduPersonAffiliation$$$;subj$eduPersonEntitlement$$$;subj$role$$$;rsrc$rs$unsb64-inf$urn:oasis:names:tc:xacml:1.0:resource:resource-id$;rsrc$urn:oasis:names:tc:xacml:1.0:resource:resource-id$$$;rsrc$Resource$rename$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$$;$setptmcookie$del$$") 2607 2608 26096.1.93 Specify XACML Attributes for SSO / frontchannel request in PEP 2610~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2611 2612Format ns$A$rule$b$ext 2613 2614Does not affect metadata. 2615 2616PEPMAP:: (default: ZXID_COMMAP) 2617 2618 26196.1.94 Specify XACML Attributes for Request Outbound PEP at WSC (1) 2620~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2621 2622Format ns$A$rule$b$ext 2623 2624Does not affect metadata. 2625 2626PEPMAP_RQOUT:: (default: ZXID_COMMAP) 2627 2628 26296.1.95 Specify XACML Attributes for Request Inbound PEP at WSP (2) 2630~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2631 2632Format ns$A$rule$b$ext 2633 2634Does not affect metadata. 2635 2636PEPMAP_RQIN:: (default: ZXID_COMMAP) 2637 2638 26396.1.96 Specify XACML Attributes for Response Outbound PEP at WSP (3) 2640~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2641 2642Format ns$A$rule$b$ext 2643 2644Does not affect metadata. 2645 2646PEPMAP_RSOUT:: (default: ZXID_COMMAP) 2647 2648 26496.1.97 Specify XACML Attributes for Response Inbound PEP at WSC (4) 2650~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2651 2652Format ns$A$rule$b$ext 2653 2654Does not affect metadata. 2655 2656PEPMAP_RSIN:: (default: ZXID_COMMAP) 2657 2658 26596.1.98 Default AAMAP 2660~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2661 2662Pass all attributes (except dangerous ones) through. 2663 2664idpsesid is blocked on grounds of being a sessionwide correlation handle. 2665 2666Does not affect metadata. 2667 2668DEFAULT_IDP_AAMAP:: (compile) (default: "$*$$$;$idpsesid$del$$") 2669 2670 26716.1.99 Whitelists and blacklists for the primitive SSO local PDP 2672~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2673 2674Comma separated lists. 2675 2676Do not affect metadata. 2677 2678LOCALPDP_ROLE_PERMIT:: Whitelist of roles, comma separated (empty: anything goes) (default: 0) 2679 2680LOCALPDP_ROLE_DENY:: Blacklist of roles, comma separated (default: "local_deny") 2681 2682LOCALPDP_IDPNID_PERMIT:: Whitelist of permitted users, comma separated (empty: anything goes) (default: 0) 2683 2684LOCALPDP_IDPNID_DENY:: Blacklist of denied users, comma separated (default: "denynid") 2685 2686 26876.1.100 Obligations 2688~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2689 2690Obligations we are willing to respect (unless an explicit UsageDirectives header 2691is specified by caller), require, generate, and accept. Examples: 2692 2693 WSC_LOCALPDP_OBL_PLEDGE=urn:tas3:sol1:contract-fwk=urn:syn-trust:obl:base-contract:2012-11 2694 WSC_LOCALPDP_OBL_PLEDGE=urn:tas3:sol1:contract-fwk=urn:syn-trust:obl:base-contract:2012-11%26urn:tas3:sol1:xborder=urn:tas3:sol1:xdom:eu 2695 WSC_LOCALPDP_OBL_PLEDGE=urn:tas3:sol1:contract-fwk=urn:syn-trust:obl:base-contract:2012-11$urn:tas3:sol1:xborder=urn:tas3:sol1:xdom:eu 2696 2697Since SOL expressions are parsed according to URL query string 2698rules and since the configuration directives are also parsed 2699according to query string rules, a problem arises with multipart SOL 2700expressions. The second expression shows how to use URL quoting 2701(%26) to protect the SOL ampersand from being processed by the 2702configuration file. Since this is such a common situation, a 2703special separator dollar ($, 0x24) may be used instead, as 2704illustrated in third example. 2705 2706Multiple WSP_LOCALPDP_OBL_REQ and WSP_LOCALPDP_OBL_EMIT directives 2707accumulate. Special pledge name "reset" can be used to reset the 2708list. 2709 2710See further discussion in tas3-proto.pd section 2.12 Simple Obligations Language (SOL). 2711 2712Does not affect metadata. 2713 2714WSC_LOCALPDP_OBL_PLEDGE:: String: WSC pledged obligations in SOL notation (default: 0) 2715 2716WSP_LOCALPDP_OBL_REQ:: String: WSP required obligations in SOL notation (default: 0) 2717 2718WSP_LOCALPDP_OBL_EMIT:: String: WSP obligations emitted on resp (default: 0) 2719 2720WSC_LOCALPDP_OBL_ACCEPT:: String: WSC acceptable obligations in SOL notation (default: 0) 2721 2722 27236.1.101 Unix Group Authorization 2724~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2725 2726 UNIX_GRP_AZ_MAP=affil$attr$val$group$ext 2727 2728where 2729 2730affil:: Specifies who is allowed to supply the attribute. Typically 2731 the IdP EntityID. Specifying '**' accepts any IdP, but this 2732 is problematic if different IdPs use same attribute name to 2733 mean different things. Suffix and prefix matching can be 2734 performed using "**" and "*". 2735attr:: The name of the SSO attribute, e.g "role" or "o" (organization). 2736 Can also be specified as "*", which is interpretted as any 2737 user from the IdP specified in affil. No other wildcarding. 2738val:: The value of the attribute that needs to match. Prefix and 2739 suffix matching using "*" and "**" is supported. Use | to 2740 supply alternatives. 2741group:: The Unix group name. 2742ext:: Extension field. 2743 2744Leave as empty (null) to disable the feature. 2745 2746Does not affect metadata. 2747 2748UNIX_GRP_AZ_MAP:: (default: 0) 2749 2750 27516.1.102 Enable Obsolete Ciphers 2752~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2753 2754Enable CBC (instead of GCM) and PKCS#1 v1.5 padding, both of which 2755are vulnearable and can compromise modern crypto through Backwards 2756Compatibility Attacks. 2757See paper: Tibor Jager, Kenneth G. Paterson, Juraj Somorovsky: "One Bad Apple: Backwards Compatibility Attacks on State-of-the-Art Cryptography", 2013 http://www.nds.ruhr-uni-bochum.de/research/publications/backwards-compatibility/ /t/BackwardsCompatibilityAttacks.pdf 2758 2759Does not affect metadata. 2760 2761BACKWARDS_COMPAT_ENA:: safe default (default: 0) 2762 2763 27646.1.103 Change Current Working Directory 2765~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2766 2767Apache httpd sometimes changes working directory unpredictably 2768(usually to /). This is in violation of Apache httpd documentation, 2769but apparently the bug has not gotten fixed as of 2013. This seems 2770to be related to mod_rewrite. Use this option to change working 2771directory back to whatever you desire, such as document root of a 2772virtual host so that relative paths to templates, etc. work. 0 means 2773not to change (i.e. leave working directory as-is, even if unpredictably 2774changed to wrong value). 2775 2776Does not affect metadata. 2777 2778WD:: (default: 0) 2779 2780 27816.2 Simple API HTML customization 2782--------------------------------- 2783 2784These allow simple branding and customization. 2785If these options are not enough for you, consider simply rendering your own forms. 2786 2787 27886.2.105 Whether to show more technical fields in the GUI 2789~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2790 2791Normally they are hidden and POST profile is used. 2792Does not affect metadata. 2793 2794SHOW_TECH:: (default: 0) 2795 2796 27976.2.106 Body tag for some old ZXID generated pages 2798~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2799 2800Edit this to change the colors. But usually 2801you should be editing stylesheet or template. 2802Does not affect metadata. 2803 2804BODY_TAG:: (compile) (default: "<body bgcolor=white>") 2805 2806 28076.2.107 IdP Selector Page URL 2808~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2809 2810If the IDP_SEL_TEMPL_FILE or IDP_SEL_TEMPL, above, is not sufficient for 2811your customization needs, you can provide URL to page of your own design. 2812This page will receive as query string argument the relay state. 28130 (zero) disables. 2814 2815Does not affect metadata. 2816 2817IDP_SEL_PAGE:: (default: 0) 2818 2819 28206.2.108 Path for Template for IdP Selector Page 2821~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2822 2823This template is used 2824by Service Provider to render the SP "login" screen which really 2825is the IdP selection screen (as the authentication login is done 2826on IdP side). 2827 2828Does not affect metadata. 2829 2830IDP_SEL_TEMPL_FILE:: (default: "idpsel.html") 2831 2832 28336.2.109 Template for IdP Selector Page 2834~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2835 2836Used if the path does not work. This is really meant to be the last resort. 2837 2838Does not affect metadata. 2839 2840IDP_SEL_TEMPL:: (default: "<title>SP SSO: Choose IdP</title>"\) 2841 2842 28436.2.110 Choose the method for rendeing IdP list. 2844~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2845 2846- 0 = popup menu 2847- 1 = buttons 2848- 2 = branded image buttons (a la "nascar") 2849 2850This configuration option is effective if !!IDP_LIST variable 2851is used in template. The variables !!IDP_POPUP, !!IDP_BUTTON, and !!IDP_BRAND 2852in template override this option. 2853 2854Do not affect metadata. 2855 2856IDP_LIST_METH:: (default: 0) 2857 2858IDP_LIST_POPUP:: (default: 0) 2859 2860IDP_LIST_BUTTON:: (default: 1) 2861 2862IDP_LIST_BRAND:: (default: 2) 2863 2864 28656.2.111 Create New User Page 2866~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2867 2868If user clicks "Create New User" he is redirected to this page. 2869E.g. "zxidnewuser.pl" 2870 2871Does not affect metadata. 2872 2873NEW_USER_PAGE:: (default: 0) 2874 2875 28766.2.112 Recover Password Page 2877~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2878 2879If user clicks on recover password, redirect to this page. 2880E.g. "zxidrecoverpw.pl" 2881 2882Does not affect metadata. 2883 2884RECOVER_PASSWD:: (default: 0) 2885 2886 28876.2.113 Attribute Selection Page 2888~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2889 2890If attribute selection is desired during SSO, redirect to this page. 2891E.g. "zxidatsel.pl" 2892 2893Does not affect metadata. 2894 2895ATSEL_PAGE:: (default: 0) 2896 2897 28986.2.114 Authentication Page URL 2899~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2900 2901If the template customization options are not sufficient, you can 2902provide URL to page of your own design. If set, takes priority over AN_TEMPL_FILE. 29030 (zero) disables. 2904 2905Does not affect metadata. 2906 2907AN_PAGE:: (default: 0) 2908 2909 29106.2.115 Path for Template for IdP Authentication Page 2911~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2912 2913* 2914Does not affect metadata. 2915 2916AN_TEMPL_FILE:: (default: "an-main.html") 2917 2918 29196.2.116 Template for IdP Authentication Page 2920~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2921 2922Used if the path does not work. This is really meant to be the last resort. 2923 2924Does not affect metadata. 2925 2926AN_TEMPL:: (default: "<title>IdP: Authentication</title>"\) 2927 2928 29296.2.117 Path for Template for POST profile page 2930~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2931 2932* 2933Does not affect metadata. 2934 2935POST_TEMPL_FILE:: (default: "post.html") 2936 2937 29386.2.118 Template for POST profile page 2939~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2940 2941Used if the path does not work. This is really meant to be the last resort. 2942 2943Does not affect metadata. 2944 2945POST_TEMPL:: (default: "<title>Post Profile</title>"\) 2946 2947 29486.2.119 Error Page URL 2949~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2950 2951If the template customization options are not sufficient, you can 2952provide URL to page of your own design. If set, takes priority over ERR_TEMPL_FILE. 29530 (zero) disables. 2954 2955Does not affect metadata. 2956 2957ERR_PAGE:: (default: 0) 2958 2959 29606.2.120 Path for Template for Error Page 2961~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2962 2963Does not affect metadata. 2964 2965ERR_TEMPL_FILE:: (default: "err.html") 2966 2967 29686.2.121 Template for Error Page 2969~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2970 2971Used if the path does not work. This is really meant to be the last resort. 2972 2973Does not affect metadata. 2974 2975ERR_TEMPL:: (default: "<title>ZXID: Error</title>"\) 2976 2977MGMT_START:: (default: "<title>ZXID SP Mgmt</title><link type=\"text/css\" rel=stylesheet href=\"idpsel.css\"><body bgcolor=white><h1 class=zxtop>ZXID SP Management (user logged in, session active)</h1>\n") 2978 2979MGMT_LOGOUT:: (default: "<input type=submit name=gl value=\" Local Logout \">\n<input type=submit name=gr value=\" Single Logout (R) \">\n<input type=submit name=gs value=\" Single Logout (S) \">\n") 2980 2981MGMT_DEFED:: (default: "<input type=submit name=gt value=\" Defederate (R) \">\n<input type=submit name=gu value=\" Defederate (S) \">\n") 2982 2983MGMT_FOOTER:: (default: "<div class=zxbot>") 2984 2985MGMT_END:: (default: "</div>") 2986 2987 29884.1.122 Directives for debugging configuration 2989~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2990 2991ECHO:: Print to debug out that given line in configuration has been reached. 2992 Used for debugging complex sequences of VPATH and INCLUDE. 2993 2994 2995INFO:: Like ECHO, but prints at debug level INFO. 2996 2997WARN:: Like ECHO, but prints at debug level WARN 2998 2999 3000DIE:: Like ECHO, but prints at debug level ERR and the aborts (exits) the process. 3001 3002REM:: Remark. A comment that is not printed anywhere. Alternate mechanism 3003 when compated to using hash sign ("#") in configuration files. 3004 3005 3006PRAGMA:: Implementation dependent config parsing time option. Ignore if not understood. 3007 3008<<if: ZXIDBOOK>> 3009<<else: >> 3010 301196 License 3012========== 3013 3014Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved. 3015Copyright (c) 2010-2011 Sampo Kellom�ki (sampo@iki.fi), All Rights Reserved. 3016Copyright (c) 2012-2015 Synergetics (sampo@synergetics.be), All Rights Reserved. 3017 3018Author: Sampo Kellom�ki (sampo@iki.fi) 3019 3020Licensed under the Apache License, Version 2.0 (the "License"); 3021you may not use this file except in compliance with the License. 3022You may obtain a copy of the License at 3023http://www.apache.org/licenses/LICENSE-2.0 3024 3025Unless required by applicable law or agreed to in writing, software 3026distributed under the License is distributed on an "AS IS" BASIS, 3027WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 3028See the License for the specific language governing permissions and 3029limitations under the License. 3030 303197 FAQ 3032====== 3033 3034 303597.3 Configuration Questions 3036---------------------------- 3037 30381. Q: In mod_auth_saml, what is the relation between ZXIDConf and httpd.conf? 3039 3040 A:�httpd.conf can contain ZXIDConf directives. Those directives are 3041 processed as if they came from /var/zxid/zxid.conf file (which is 3042 processed first, before and ZXIDConf directives), except that if you 3043 specify ZXIDConf "CPATH=/your/path", this triggers reprocessing of 3044 the zxid.conf (from the new path). 3045 30462. Q: In mod_auth_saml, what is the relation between the +port+ in ZXIDConf 3047 and the +port+ in the httpd.conf? 3048 3049 A: The ports must agree. ZXID configuration must match the way the 3050 Apache layer is configured. 3051 30523. Q: Multiple roles of same entity, acting as SP, WSC, and WSP for 3053 different services 3054 3055 Asa: 3056 > Part of what you are saying is that the service 3057 > registration is WSC. This is rather confusing since the case is a WSP 3058 > acting as a WSC of the Discovery Service. For the ClientLib thus far, 3059 > I have chosen to think of service registration as a WSP to WSP. What is 3060 > the downside to this approach? 3061 3062 Conor: 3063 > Service registrations can't be done WSP to WSP with any Liberty protocol 3064 > (in fact, we don't define any such method of invocation as the invoking 3065 > party is always a WSC for the intent of that message - there's no 3066 > problem with a WSP in turn being a WSC of another service instance, just 3067 3068 Right. You can don WSC role whenever convenient. There is nothing confusing 3069 about WSP of one service being WSC of another service. Perhaps the 3070 confusion would be avoided if everybody fully qualified their descriptions 3071 until common convention about less than fully qualified roles emerges. 3072 3073 Entity E1, an ID-DAP WSP (primary role), will act as Discovery WSC 3074 (secondary role) to perform metadata registration. This same entity E1 3075 will also have SP interface (another secondary role) which allows 3076 the user to trigger discovery association, again E1 acting in secondary 3077 role of Discovery WSC. 3078 3079 No confusion as far as I can see. 3080 308197.3 Common Mistakes 3082-------------------- 3083 30841. When I try accessing https://sp1.zxidsp.org:8443/zxidtest.sh nothing happens! 3085 3086 Assuming you have the web server correctly running, the most common 3087 gotcha is that zxidhlo has dynamic linking problem. 3088 See <<see: ZXID-Installing-CannedTutorialRunningZXIDasCGIundermini_httpd-AccessingZXID>> 3089 subsection "Dynamic Linking Problems", for explanation and resolution. 3090 30912. Single Logout does not end the IdP session (i.e. IdP does 3092 not force you to supply password when you do SSO next time). 3093 3094 Usual cause is that the management form (the one with the SLO buttons) 3095 does not have correct or any session ID. Do a view source on the 3096 the page and look for field called "s". The session ID is 3097 supposed to be extracted from the Single Sign-On result. For 3098 zxid_simple() you need to parse the returned LDIF and 3099 take the sesid. Pass that to zxid_fed_mgmt() as second argument. 3100 31013. Login buttons do nothing. 3102 3103 A possible cause is that the entity ID is not passed from 3104 the IdP selection form. If the form is using POST method, 3105 you must make sure you actually read the HTTP body and 3106 pass its contents to the zxid_simple() as the ~qs~ argument. 3107 31084. The SP Login, a.k.a. IdP selection, page shows, but SSO does not work 3109 3110 a. Your configuration does not match actual URL used to 3111 access the zxid system. For the zxidhlo family of 3112 examples you MUST edit the configuration string 3113 to match your situation. Watch out for domain name 3114 and port number. 3115 3116 b. Connectivity issue prevents IdP from fetching metadata. 3117 Make sure your domain name is resolvable at IdP (e.g. 3118 add it to /etc/hosts). See also next point. 3119 3120 c. IdP is not configured to get your metadata automatically. 3121 You have to configure your metadata to the IdP manually. 3122 How to do this depends on IdP product. Do not ask us. 3123 3124 d. You supplied IdP URL that, in fact, is not the well known 3125 location for fetching IdP metadata. Or the IdP does 3126 not have well known location enabled. In the latter 3127 case you will need to install the IdP metadata 3128 manually (*** procedure to be documented). See [SAML2meta] 3129 section 4.1 "Publication and Resolution via Well-Known Location", 3130 p.29, for normative description of this method. 3131 3132 e. Connectivity issue at web browser level. Make sure your 3133 web browser can resolve both SP and IdP domain names. 3134 Edit /etc/hosts as needed on the machine where the browser runs. 3135 3136 f. Personal firewall blocks access. Check firewall set up on 3137 * browser machine 3138 * SP machine 3139 * IdP machine 3140 31415. The SP Login, a.k.a. IdP selection, page does not show at all 3142 3143 a. Connectivity issue at web browser level. Make sure your 3144 web browser can resolve both SP and IdP domain names. 3145 Edit /etc/hosts as needed. 3146 3147 b. Personal firewall blocks access. Check firewall set up on 3148 * browser machine 3149 * SP machine 3150 3151 c. You deployed the zxid in some other URL than you thought. 3152 Double check your webserver or servlet container 3153 configuration and be sure you understand where 3154 zxid is supposed to appear. Be sure you are editing 3155 the right configuration - some people run multiple 3156 web servers in their machine and get confused about 3157 which one actually is active on which port and where 3158 the configuration files are located. 3159 3160 d. ZXID lacks execute permissions, dynamic link libraries 3161 are missing (use "ldd zxid" to check), or CGI permission 3162 setup prevents it from running. See previous bullet. 3163 31646. Mystery configuration problems. Double check /var/zxid/zxid.conf 3165 or consider removing it if you do not understand what it does. 3166 Double check the conf string if using zxid_simple() interface. 3167 31687. Writes a user... 3169 3170 > Once it has been compiled, I copied the files zxidhlo.php and zxid.php 3171 > to /var/www/zxid (my webroot). I accessed zxidhlo.php?o=E with my browser 3172 > and I saw a page asking for IDP metadata. But when I looked at 3173 > the /var/log/apache2/error.log, I found these: 3174 > 3175 > tb77f96c0 zxidmeta.c:352 zxid_get_ent_by_sha1_name zxid d Trying 3176 > sha1_name(cot) open (vopen_fd_from_path): No such file or directory 3177 3178 Did you create the /var/zxid hierarchy (make dir) and make sure your 3179 web user (nobody?) has write permission to the ~log~ directory? Or did 3180 you configure it to use some other directory than /var/zxid? 3181 31828. What is this /var/zxidcot directory? 3183 3184 It is supposed to be /var/zxid/cot 3185 3186 When configuring CPATH, did you forget trailing slash? E.g. 3187 3188 "CPATH=/var/zxid&BURL=..." # WRONG! 3189 "CPATH=/var/zxid/&BURL=..." # Right 3190 3191<<references: 3192 3193[SAML2core] "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-core-2.0-os 3194 3195[SAML2prof] "Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-profiles-2.0-os 3196 3197[SAML2bind] "Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-bindings-2.0-os 3198 3199[SAML2context] "Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-authn-context-2.0-os 3200 3201[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 3202 3203[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 3204 3205[SAML2conf] "Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-conformance-2.0-os 3206 3207<<doc-end.pd>> 3208<<notapath: TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>> 3209<<EOF: >> 3210 3211<<fi: >>
