1<<if: ZXIDBOOK>> 2<<else: >>ZXID IdP and Discovery 3################################ 4<<author: Sampo Kellom�ki (sampo@iki.fi)>> 5<<cvsid: $Id: zxid-log.pd,v 1.9 2009-10-16 13:36:33 sampo Exp $>> 6<<class: article!a4paper!!ZXID-IDP 01>> 7<<define: ZXDOC=ZXID IdP and Discovery>> 8 9<<abstract: 10 11ZXID.org Identity Management toolkit implements standalone SAML 2.0 and 12Liberty ID-WSF 2.0 stacks. The IdP provides Single Sign-On capability 13and the Discovery provides ability to issue credentials to web services 14as well as to locate suitable services. 15 16>> 17 18<<maketoc: 1>> 19 201 Introduction 21============== 22 23ZXID IdP and Discovery configuration and databases are filesystem 24based and consists mainly of text files to which lines are 25appended. After describing the filesystem based configuration, 26we introduce some IdP administration topics and how to accomplish 27them. 28 291.1 Other documents 30------------------- 31 32<<doc-inc.pd>> 33 344 IdP and Discovery 35=================== 36<<fi: >> 37 38~zxididp~ implements, in a bare-bones way, SAML 2.0 IdP, ID-WSF 2.0 39Authentication Service, and ID-WSF 2.0 Discovery Service. It is one 40of the cornerstones of a federated identity architecture. 41 424.1 IdP Install Tutorial 43------------------------ 44 45First you need the following binaries 46 47* zxididp 48* zxcot 49* zxpasswd 50* ./zxmkdirs.sh 51 52You can get all of these from the ZXID package by compiling it. Just say `make' 53 54You also need a web server that can run CGI scripts. For 55simplicity, I recommend mini_httpd. 56 57You need to decide what URL the IdP will live on. Typically the URL 58will end in zxididp, but you can change this by renaming the zxididp 59binary. You need to register the domain name and obtain certificate 60for it, unless you are willing to use the self signed certificates 61that ZXID generates. This tutorial assumes you chose following URL 62 63 https://idp.example.com/zxididp 64 65> N.B. Prior to version 1.10 (early 2012) zxididp would 66> use /var/zxid/idp as default ~CPATH~ and /var/zxid/idpzxid/conf 67> as default configuration file. Since implementation of ~VPATH~ 68> and ~VURL~ this is no longer supported. We recommend either using 69> virtual hosting - with ~CPATH~ ending up something like 70> /var/zxid/idp.example.com:8443/ and configuration file in 71> /var/zxid/idp.example.com:8443/zxid.conf - or deploying the 72> IdP as sole application on its server and using nonvirtual 73> PATH=/var/zxid/ and configuration file at /var/zxid/zxid.conf. 74> The rest of this chapter assumes the latter approach. 75 764.1.1 Directories and Config File for IdP 77~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79 sudo ./zxmkdirs.sh /var/zxid/ 80 sudoedit /var/zxid/zxid.conf 81 NICE_NAME=Your IdP Name for End Users to See 82 ORG_NAME=Your org 83 ORG_URL=http://example.com/ 84 BUTTON_URL=http://example.com/example-saml2_icon_150x60.png 85 BURL=https://idp.example.com/zxididp 86 IDP_ENA=1 87 AS_ENA=1 88 894.1.2 Install Certificates and Private Keys 90~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 91 92Assuming you have obtained a certificate, here's how you would install 93it. We assume you have the certificate in file cert.pem and the 94private key in priv.pem. 95 96 sudo su 97 cat cert.pem priv.pem >/var/zxid/pem/ssl-nopw-cert.pem # put both in one file 98 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/sign-nopw-cert.pem 99 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/enc-nopw-cert.pem 100 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/logenc-nopw-cert.pem 101 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/logsign-nopw-cert.pem 102 chmod 600 /var/zxid/pem/* 103 # end su 104 1054.1.3 Install GUI templates and stylesheets 106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 107 108 cd zxid-1.10 109 sudo mkdir /var/zxid/webroot 110 sudo mv *.html *.css /var/zxid/webroot 111 sudo cp zxididp /var/zxid/webroot 112 1134.1.4 Exchange Metadata 114~~~~~~~~~~~~~~~~~~~~~~~ 115 116Metadata exchange introduces SAML SP to SAML IdP. Among other 117things, the certificates are exchaged and trust relationship 118is formed. ZXID supports fully automatic metadata exchage ("Auto-Cot"), 119see MD_FETCH=1 config option. Here we show how to exchange metadata manually. 120 121Generate our own metadata for exporting to SP 122 123 sudo zxcot -ci -m >idp-meta.xml 124 125Alternately the SP can access the metadata at URL https://idp.your-org.com/zxididp?o=B 126 127For each SP metadata needs to be obtained and imported. If the SP 128supports well known location method, then accessing SP's entity ID as 129a URL will return the metadata. ZXID based SPs support this 130method. Typically the URL ends in "?o=B". If SP metadata is available 131from a URL, you would import it like this: 132 133 zxcot -ci -g https://sp.example.com/saml?o=B 134 135Alternately you can obtain the metadata as a file and transfer it to 136the IdP machine. If SP is ZXID based, you can create its metadata with 137command 138 139 zxcot -m >sp-meta.xml 140 141Then to import it to IdP, run 142 143 sudo /usr/local/bin/zxcot -ci -a <sp-meta.xml 144 1454.1.5 Add users to the IdP 146~~~~~~~~~~~~~~~~~~~~~~~~~~ 147 148 head /dev/urandom | sudo /usr/local/bin/zxpasswd -n .all # dummy user to represent commonality 149 sudo /usr/local/bin/zxpasswd -at 'cn: Nomen Nescitur$email: nn@your-org.com$o: Your Org' -n nn 150 # Password will be asked on console 151 1524.1.6 Add Discovery Bootstrap 153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 154 155 zxcot -e https://idp.example.com/zxididp?o=S 'TAS3 Default Discovery Service (ID-WSF 2.0)' https://idp.example.com/zxididp?o=B urn:liberty:disco:2006-08 | zxcot -bs 156 1574.1.7 Add Other Web Services 158~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 159 160 zxcot -e https://sp.example.com/saml?o=S 'Your service human readable description' https://sp.example.com/saml?o=B urn:yoursvc:2011-08 | zxcot -b 161 1624.1.8 Trying out using mini_httpd 163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 164 165 cd /var/zxid/webroot 166 mini_httpd -u root -p 443 -c 'zxid*' -S -E /var/zxid/idppem/enc-nopw-cert.pem 167 1684.1.9 ZXID startup after boot 169~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 170 171By design the idp will not start automatically after reboot. Operator 172intervention is required to supply the password for the encrypted 173filesystem. 174 175 sudoedit /etc/idp-start 176 #!/bin/sh 177 # 20110618, sampo@zxid.org 178 modprobe fuse 179 /usr/local/bin/encfs /var/.zxid /var/zxid # you will need to supply password manually 180 cd /var/zxid/webroot 181 /usr/local/bin/mini_httpd -u root -p 443 -c 'zxid*' -S -E /var/zxid/idppem/enc-nopw-cert.pem -l /var/zxid/log/mini_443.log & 182 #EOF 183 184 sudo chmod a+x /etc/idp-start 185 186Then just run 187 188 sudo /etc/idp-start # you will be asked for encfs password, which you must know 189 190 1914.2 IdP Use of Local UID Directory (idpuid/) 192-------------------------------------------- 193 194zxididp uses local idpuid/ directory to implement the IdP logins and 195to store users federations, bootstraps, and attributes. 196 197 /var/zxid/ 198 | 199 +-- idpzxid.conf Main configuration file 200 +-- idppem/ Our certificates 201 +-- idpcot/ Metadata of CoT partners (metadata cache) 202 +-- idpses/ Sessions 203 | | 204 | +-- SESID/ Each session has its own directory 205 | | 206 | +-- .ses The session file 207 | `-- SVC,SHA1 (Each bootstrap is kept in its own file) 208 | 209 +-- idpuid/ Local user ID (local login name) to SHA1 mapping 210 | | 211 | +-- JOE/ Local user has directory whose name is the login uid 212 | | | 213 | | +-- .log Log of operations regarding the user 214 | | +-- .pw User's local password 215 | | +-- .yk User's yubikey shared aes128 secret in hex 216 | | +-- .ykspent/ Cache of already used One Time Passwords 217 | | | | 218 | | | `-- OTP File name is the spent Yubikey ticket (w/o uid) 219 | | | 220 | | +-- .bs/ Directory of bootstraps to be included 221 | | | | 222 | | | +-- .at Attributes to be included in each SSO 223 | | | `-- SVC,SHA1 Bootstrap for a service 224 | | | 225 | | `-- SP,SHA1/ One directory for each SP user is federated with 226 | | | 227 | | +-- .mni Federated name id to be used with this SP 228 | | +-- .at Attributes to be included for this SP 229 | | `-- SVC,SHA1 Bootstrap to be included for this SP 230 | | 231 | `-- .all/ Template used for all users 232 | | 233 | +-- .bs/ Directory of default bootstraps to be included 234 | | | 235 | | +-- .at Attributes to be included in each SSO 236 | | `-- SVC,SHA1 Bootstrap for a service 237 | | 238 | `-- SP,SHA1/ One directory for each SP 239 | | 240 | +-- .at Attributes to be included for this SP 241 | `-- SVC,SHA1 Bootstrap to be included for this SP 242 | 243 +-- idpnid/ Index of federated NameIDs, to map to uid 244 | | 245 | `-- SVC,SHA1 Bootstrap to be included for this SP 246 | | 247 | `-- NID Content of the file is uid 248 | 249 +-- idpdimd/ Discovery Metadata registrations 250 | | 251 | `-- SVC,SHA1 Discovery MD registration for a service (an EPR) 252 | 253 +-- grant/ Grant Manifests and Grant Token management 254 | | 255 | +-- GRANTTOK Grant Manifest file's name is the grant token 256 | `-- .spent/ Directory where spent grant tokens are moved 257 | 258 `-- idplog/ Log files, pid files, and the like 259 260<<ignore: 261 | | | 262 | | +-- .di/ Directory of discovery registrations for user 263 | | | | 264 | | | `-- SVC,SHA1 Discovery asso registration for a service 265>> 266 267zxpasswd(8) is a user provisioning tool that allows creation of 268new accounts as well as manipulation of .pw and .yk files. 269 2704.2.1 Attaching Attributes to Assertions 271~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 272 273When generating a SSO assertion, the attributes are collected as follows: 274 2751. LDIF at /var/zxid/idpuid/JOE/.bs/.at 2762. LDIF at ~/var/zxid/idpuid/JOE/SP,SHA/.at~ 2773. LDIF at /var/zxid/idpuid/.all/.bs/.at 2784. LDIF at ~/var/zxid/idpuid/.all/SP,SHA/.at~ 279 280As of version 0.33 (20090904) the attributes are rendered 281single valued. If multiple occurrances of an attribute happen, 282the first instance is used and others ignored. However, in 283a future version, we expect to support multivalued attributes. 284 2854.2.2 New Design for Attribute Selection 286~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 287 288Keep attributes, that are not shared by default, in .optat file. 289 290Support personas using files like .at-persona and .optat-persona 291where +persona+ is an alias that user has chosen to assign. 292 293Choice of persona is remembered at session level in file 294/var/zxid/idpses/.persona. The attributes of .at are 295augmented and overridden by the attributes in .at-persona 296file. .at-persona can also deny release of an attribute 297that would have been released by virtue of .at. 298 299For each SP, the user can specify .at, .optat, .at-persona, and 300.optat-persona files. The SP specific files can deny attributes 301that would otherwise have been released by virtue of global .at 302and .at-persona files. 303 304Finally, the user can choose to suppress or override the value 305of an attribute just for a specific transaction. The overriding 306value is not saved to SP specific, persona, or global layer 307unless user expressly requests so. 308 309For each attribute the authority is determined. Default is 310self asserted. If attribute has other authority, this will 311be indicated. If user chooses to override the attribute, either 312for transaction or for a persona, its authority reverts 313to self asserted. Attributes from a given authority are 314provided in files of type .at,authority or .optat,authority. 315 316Some attributes are reserved: user does not have the option of setting 317their value (i.e. self asserted is not an option), and depending on 318the case the user may or may not be able to suppress their supply. The 319unsuppressible attributes are listed in configuration option 320MANDATORY_ATTR, which is global (not per user or not per SP). 321 322*Attribute Release Algorithm* 323 3241. Initialize attribute set from internal defaults 3252. Apply /var/zxid/idpuid/JOE/.bs/.optat 3263. Apply /var/zxid/idpuid/JOE/.bs/.at 327 328Attribute Selection screen is displayed whenever 329 330a. User has checked the Adjust attribute sharing -checkbox 331 prior to authentication. 332b. SP requests more attributes than default or SP specific 333 attribute sharing policy permits. If SP does not specify 334 which attributes it wants, then SP specific and default 335 attribute sharing policy determine the attributes to release. 336c. User has requested as a global preference (and this 337 preference has not been overridden in a session) that 338 all attribute releases be displayed. 339d. User has requested at session level that 340 all attribute releases be displayed. 341e. User has requested for the SP that 342 all attribute releases be displayed (similar to specifying 343 an empty, but defined release policy towards SP, see 344 point (b); difference is that the sharing defaults 345 still tick the share boxes, providing convenience to the 346 user. 347 348Attribute release at discovery or web service call time is governed 349first by SP specific attribute sharing policy and then by the default 350sharing policy. If WSP needs more attributes, it will have to submit a 351web service request for them. Eventually, we may support using 352interaction service to query user about release of the extra 353attributes. 354 3554.2.3 Attaching Bootstrap Attributes to Assertions 356~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 357 358The bootstrap attributes (ID-WSF 2.0 EPRs with credentials) are 359attached to the SSO assertions to facilitate frontend web sites 360making backend web services calls. 361 362The bootstraps are generated by scanning /var/zxid/idpuid/JOE/.bs 363directory and for each corresponding file looking up the service EPR 364in the /var/zxid/idpdimd directory. If metadata for the service is 365found there, an access credential for accessing the service is 366generated (unless disallowed by the configuration). The access credential 367is based on existing federation, or if that is lacking and auto federation 368is allowed, on newly generated (IdP unilateral) federation. 369 370Future versions (as of 2009) may allow more granular approach to the 371bootstraps generated, but the strategic direction is to technically 372enable communications automatically and then to rely on explicit 373authorization services (XACML PDP) to make a policy based decision 374about what is allowed to happen. 375 376After user's .bs directory, the global /var/zxid/idpuid/.all/.bs is 377scanned. This allows common bootstraps, such as discovery, that occur 378for all users to be specified only once at the .all level, while 379additional bootstraps can be added for the individual users. 380 381> N.B. As of 0.41 (20091120), the .di directories are unused. In 382> case of discovery, all matching entries in /var/zxid/idpdimd 383> will be considered and federations automatically created, 384> irrespective of user's .di or .all/.di. 385 3864.2.4 Yubikey Authentication Support 387~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 388 389Yubikey support works by using the initial part of the ticket (passed 390in as user field) as uid and the latter as the ticket proper. The uid 391part is used to locate correct directory. Mapping from yubikey modhex 392to real UID is done by creating a symlink. The AES128 shared (between 393yubikey token and IdP) key is kept in the .yk file. As this is not a 394password has, but rather directly the shared secret, it requires 395rigorous approach to the filesystem security. The fact that .pw and 396.yk are separate files caters for the possibility of user 397authenticating either by yubikey or by password. By default yubikey 398is one factor authentication (in fairly secure and very convenient 399form). If two factor authentication is desired, the password component 400should be prefixed to the UID component, i.e. first user types PIN 401and then presses yubikey to add UID and ticket. 402 403To program yubikeys with the shared secrets, you need ykpersonalize(8) 404tool, available from Yubico as open source. 405 4064.2.5 Client Certificate Authetication of the User 407~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 408 409TLS Client Certificate authentication of users has not been 410implemented yet, but in any case would be mainly implemented by 411configuration of web server to request such certificate and verify 412it. By the time zxid gets called, the client cert authentication will 413already have happened. HTTP Basic authentication works in similar way 414and we make no attempt to cater for it, although it can be used of 415configured separately (in the traditional way). 416 4174.3 Installing zxididp 418---------------------- 419 420First you need to obtain ~zxididp~ either by downloading a binary 421package (and installing it) or by compiling from source. See 422zxid-install.pd for further details. 423 4244.3.1 Configuring CGI Script in Web Server 425~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 426 427zxididp(8) is a CGI script (written in C) that you can install under 428any web server that supports CGI scripts (e.g. Apache httpd, IIS, 429or mini_httpd). You must configure your web server to execute 430zxididp(8) as a CGI script. The specifics vary from web server 431to web server - consult your server documentation. 432 433For *Apache* this would mean in httpd.conf a stanza like 434 435 <Location "/zxididp"> 436 Options All 437 SetHandler cgi-script 438 </Location> 439 440You would then copy the ~zxididp~ binary to the root of your document 441tree and make sure it is executable. See apache.pd for full scoop. 442 443For *mini_httpd* this could mean something like 444 445 mini_httpd -p 8443 -c zxididp -S -E zxid.pem 446 447For *IIS* this could mean something like 448 449* In Microsoft IIS 7 "Handler Mappings" use "Add Script Map" 450 and associate Request Path: "zxididp" to 451 452 C:/var/zxid/bin/zxididp.exe # Or what your path is 453 454 This is saved in file web.config 455 456* In IIS 6 add mapping for zxididp to run as CGI. Go to 457 webroot -> Properties -> Virtual Directory -> Configuration -> 458 Application Configuration 459 460 zxididp C:\var\zxid\bin\zxididp GET,... 461 462 Remember to add ~zxididp~ to Web Services Extensions 463 New Web Service Extension, Add Required files 464 465 C:\var\zxid\bin\zxididp 466 467* In IIS3 and earlier it was necessary 468 469 regedt32.exe 470 HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/W3SVC/Parameters/ScriptMap 471 Create new value name "zxididp" and value "c:/var/zxid/bin/zxididp.exe" 472 473 4744.3.2 Creating Directory Hirearchy 475~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 476 477You must choose location for the configuration and logging hierachy 478of the zxididp(8) and then populate it. See earlier section in this 479document for details. By default the hierarchy will live in 480/var/zxid. 481 482 /var/zxid/ 483 | 484 +-- zxid.conf Main configuration file 485 +-- pem/ Our certificates 486 +-- cot/ Metadata of CoT partners (metadata cache) 487 +-- ses/ Sessions 488 +-- uid/ Local user ID (local login name) to SHA1 mapping 489 +-- nid/ Index of federated NameIDs, to map to uid 490 +-- dimd/ Discovery Metadata registrations 491 +-- inv/ Invitations 492 `-- log/ Log files, pid files, and the lik 493 494You can create this hierarchy by running 495 496 zxcot -dirs 497 4984.4 Adding Service Providers to Circle of Trust (CoT) of zxididp 499---------------------------------------------------------------- 500 501See zxid-cot.pd for full scoop. 502 503If Auto-CoT is enabled, and SP and IdP can communicate over the 504internet (n.b. problems with DNS, firewalls, other party not 505supporting WKL, etc.), the Service Providers can join the CoT 506automatically upon first use. 507 508Otherwise, metadata exchange may need to be arranged manually using 509zxcot(8) tool. Typically you would receive sp-metadata.xml by mail 510from the SP administrator, or by instant messaging file transfer. You 511could even fetch it yourself using a web browser, saving the metadata 512page. Metadata is a XML blob. 513 514 zxcot -a /var/zxid/idpcot <sp-metadata.xml 515 zxcot -g https://site.com/meta.xml /var/zxid/idpcot # Assumes connectivity 516 zxcot /var/zxid/idpcot # Lists the SPs in the CoT 517 518When all else fails, you can just manipulate the filesystem 519manually, creating the necessary files and directories. 520 5214.4.1 Sending zxididp Metadata to SP 522~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 523 524If SP and IdP can communicate over the internet (n.b. problems with 525DNS, firewalls, other party not supporting WKL, etc.), the Service 526Providers can just request the zxididp metadata on the fly, based on 527Well Known Location (WKL). 528 529The EntityID and WKL of the zxididp(8) are of the form: 530 531 https://you.com/zxididp?o=B 532 533where the "o=B" part is the ZXID general way of triggering 534metadata response. 535 536If you need to perform the metadata exchange manually, your best bet is 537to download the metadata with your web browser (see WKL above) 538and send it to the other party. 539 5404.4.2 zxidcot.pl Web GUI 541~~~~~~~~~~~~~~~~~~~~~~~~ 542 543One way to facilitate adding new SPs to the Circle of Trust is 544to deploy the zxidcot.pl Web GUI. This allows the administrators 545of SPs and WSPs to add their metadata and discovery registrations 546as well as view the existing registrations. This self help method 547is suitable if you want to run very open CoT, i.e. anyone 548can join. It may not be appropriate if you want to control 549who enters your CoT. 550 551To install zxidcot.pl, just copy it to suitable location 552in your web root and make sure it can be executed as a CGI 553script. If you keep your zxididp configuration in any place 554other than the default /var/zxid/idp, you will need to 555edit zxidcot.pl to correspond to your configuration. The 556visual aspects of zxidcot.pl can be controlled to some 557extent by editing the an.css cascading stylesheet, but if you 558need big changes, you will need to edit the script itself. 559 560To access zxidcot.pl point your web browser to 561https://idp.example.com/zxidcot.pl?op=md for metadata 562registration or https://idp.example.com/zxidcot.pl?op=direg 563for discovery registration. 564 565The underlying implementation uses the ~zxcot~ command 566line tool. 567 5684.5 Configuring Users into zxididp 569---------------------------------- 570 571User provisioning and administration: Currently all this is manual 572and commandline or filesystem based. Contribution in form of fancy user 573self provisioning web GUIs would be appreciated by the zxid.org project. 574 575Generally you should be able to administer the users using 576zxpasswd(8), but when all else fails, you can just manipulate the 577filesystem manually, creating the necessary files and directories. 578 5794.5.1 Adding New User 580~~~~~~~~~~~~~~~~~~~~~ 581 582Adding a new user consist of creating a directory corresponding 583to the user ID under /var/zxid/idpuid hierarchy. Typically this 584directory will contain the .pw file for password authentication 585and possibly a .yk file for Yubikey authentication. The directory 586will also contain .bs/.at file for specifying user's attributes. 587 588Easiest way to create a new user is using -new option: 589 590 zxpasswd -new user /var/zxid/idpuid <passwd 591 5924.5.2 Setting or Changing Password 593~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 594 595 zxpasswd user /var/zxid/idpuid <newpasswd 596 597N.B. By default the password is stored as MD5 hash. Use -t X command 598line option to choose other hashing algorithm. 599 6004.5.3 Adding Yubikey Authentication 601~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 602 603Yubikeys are One Time Password (OTP) hardware tokens that connect to 604the USB port and act as keyboard emulators. They are sold by yubico.com 605 606 zxpasswd -t y -s user yubikeyalias /var/zxid/idpuid <yk_aes128_secret 607 608N.B. To program a Yubikey and agree to a AES 128 bit shared secret, you 609need ~ykpersonalize~ program, available from Yubico. 610 6114.5.4 Adding Attributes to User 612~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 613 614There is no command line interface for adding the attributes currently 615(20091120). You simply have to edit the UID/.bs/.at, UID/SP,SHA1/.at, 616 .all/.bs/.at, or .all/SP,SHA1/.at files. The files are in (relaxed) LDIF 617format. E.g. 618 619 dn: cn=Koerkki,o=Labra 620 permisRole: teacher 621 cn: Koerkki 622 o: Labra 623 624N.B.: The LDIF format is essentially an attribute name separated from 625an attribute value by colon and one space, and name-value pairs 626separated from each other by a newline. This is very similar 627to mail header format. The "dn:" line is required in LDIF, but 628can be omitted in zxididp .at files. 629 630If you want to add a complex binary or XML attribute, such as a x509v3 631attribute certificate or a SAML assertion, we recommend that you 632safebase64 [RFC3548] encode the attribute value to prevent it from 633being mangled by SP SSO processing. To unravel such safebase64 634encoding you can use in mod_auth_saml, or other zxid based SP, the 635~INMAP~ specification with +rule+ as ~unsb64-inf~ or ~unsb64~. See 636zxid-conf.pd, section "INMAP specification", for further information. 637 638The attributes from all the available sources are accumulated. If same 639attribute is available from multiple sources, behaviour is undefined 640(currenlty attribute becomes multivalued). 641 6424.5.5 zxidnewuser.pl web GUI 643~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 644 645If you are willing to accept new users on self asserted basis, 646you can set up zxidnewuser.pl script so that anonymous users 647can register themselves. If you do not want anonymous users, 648you should not be setting this script up. To control the 649visual appearance of the new user registration, you can edit 650an.css stylesheet or newuser-main.html template. To control 651which attributes are collected, you need to edit both the 652template and the zxidnewuser.pl script. 653 654<<img: newuser: New user registration screen for self asserted users.>> 655 656To install zxidnewuser.pl, simply place it somewhere in the 657web root of your website and make it executable as a CGI 658script. Then you need to add to /var/zxid/idpzxid.conf 659 660 NEW_USER_PAGE=zxidnewuser.pl 661 662You may also want to edit the an-main.html template to control 663how the new user button will appear. 664 665If new user registration is called in middle of a SSO flow, 666zxidnewuser.pl will preserve the ar= CGI variable (as a hidden 667field) so that when new user has been created, the flow returns 668to the login screen and the new user can login. zxidnewuser.pl 669can also be invoked outside login sequence: just provide a link 670to it from the first page of the IdP. In this case after the 671registration, the user is returned to the top level index page 672of the web site. 673 674The underlying implementation uses the zxpasswd command 675line tool. 676 6774.5.6 Provisioning Using Grant Tokens 678~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 679 680In Grant Token provisioning, a user administrator pre-generates 681a +grant token+ and URL that points to zxidgrant.pl. When user 682clicks on the grant token link, he is taken to the GUI and 683asked if he already has an account (if user is already logged 684in, no question is put to the user). If user does not yet 685have an account, he is offered an opportunity to create one, 686see previous section. 687 688Once the user has logged in, he is asked to confirm that he 689wishes to obtain the attributes granted in the grant 690token. If he accepts, he gets the attributes and the 691grant token is consumed and can not be used again. Multi use 692grant token can be generated by adding zx_g_multiuse: inf 693to the grant manifest (values other than inf are reserved). 694 695Typically the grant token is used to give user attributes, 696like role or permission, that affect access control decisions 697at the SPs. The attributes can be global or local to a number of 698specific SPs. 699 700Basically grant token is just a pointer (sha1 hash of the contents) to 701a +grant manifest+ stored at the IdP, preceded by the URL pointing 702to zxidgrant.pl. 703 704*Grant Manifest Syntax* 705 706<<ignore: 707 bs * attr=value&attr=value 708 bs sp.zxidp.org_8080_zxidservlet_sso_o_B,I7fbXL2KNXOTk6YpjR3pQ4awVzY attr=value&attr=value 709 710where first line specifies global attribute and the second line specifies 711attributed granted wrt specific SP. On each line the first field, "bs", 712specifies that the attribute is to be pushed as part of the bootstrap 713on every SSO. The second field specifies the SP and third field specifies 714the attributes in Query String format. 715>> 716 717LDIF style multiline syntax is denoted by "dn:", e.g: 718 719 dn: op=bs,share=at,eid=* # 1 720 attr1: value1 721 attr2: value2 722 723 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 2 724 attr1: value1 725 attr2: value2 726 727 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 3 728 zx_g_email: foo@bar.com 729 attr1: value1 730 attr2: value2 731 732 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 4 733 zx_g_idpnid: F32rcq2 734 attr1: value1 735 attr2: value2 736 737 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 5 738 zx_g_challenge: Meeting pincode? 739 zx_g_response: 2098 740 attr1: value1 741 attr2: value2 742 743 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 6 744 zx_g_question: Your employee number? 745 zx_g_answer_attr: answer 746 attr1: value1 747 attr2: value2 748 749 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 7 750 zx_g_idpnid: P32rcq2 751 zx_g_notbefore: YYYYMMDD-HHMMSS 752 zx_g_expires: YYYYMMDD-HHMMSS 753 attr1: value1 754 attr2: value2 755 756 dn: op=bs,share=at,eid=https://sp.zxid.org/saml?o=B # 8 757 zx_g_idpnid: P32rcq2 758 grantvalidator: VVNXO9Tk6YpjR 759 attr1: value1 760 attr2: value2 761 762where records are separated by empty line. 763 764The "dn:" line specifies +op+, which is always "bs", the attribute 765sharing status +share+, which can be "at" for attributes to be sent 766always and "optat" to provision attributes but not send them to 767SPs. "at" should normally be chosen. The +eid+ specifies to which SP 768the attributes apply - special value "*" means to all. 769 770Generally all attributes that start by "zx_g_" are special and reserved 771for use by the grant token software. These are explained below. 772 773When a grant token is used, it is moved to .spent/ directory and may be appended 774with information indicating who spent it and when: 775 776 zx_g_spend: grant=24rfeqwrv141A, uid=user-who-spent, ts: yyyymmdd-hhmmss # in Zulu time (GMT/UTC) 777 778Documentation about attributes can be provided with syntax 779 780 dn: op=bs,share=at,ent=* # 1 781 attr1: value1 782 zx_g_doc_attr1: Documentation about attribute 1 783 784*Grant Token Generation and Distribution* 785 786As is obvious, issuance of grant tokens is of vital interest to access 787controls of the SP and SP is trusting the IdP to do the right thing. 788The SP promoter formulates grant manifest with desired attributes and 789requests from the IdP administrator generation of the grant token. 790 791The IdP administrator validates the grant manifest (and that it came 792from authentic source) and generates the grant tokens and passes them 793back to the SP promoter for distribution to the authorized people. 794Alternatively, the manifest may contain distribution instructions so 795that the IdP administrator can send the tokens directly - see 796example 3. 797 798It is important to note that grant tokens are bearer tokens, 799i.e. whoever gets their hands on them is able to acquire the attribute 800and corresponding access rights. Therefore the distribution should be 801limited and well controlled. 802 803In the SP specific access token case, the SP promoter can make 804a restriction that the grant token can be consumed only by 805holder of a specific pseudonym by specifying ~idpnid~ field 806on the "dn:" line, see example 4. 807 808As a second factor of authentication, the manifest may specify a challenge 809question and answer to be supplied by the user of the token. Presumably 810the grant token would be sent by email, where it could be intercepted, 811but the answer to the challenge is shared securely or is otherwise known 812to the user, see example 5. 813 814Manifest may specify a freeform question to be answered by the user. The 815answer, without validation, will be set as value of specified attribute, 816see example 6. 817 818If specified, see example 7, the grant token must be used in given 819time range (specified in Zulu aka GMT aka UTC timezone). 820 821To further ensure authenticity of granted attributes, the SP can pass 822a validation attribute that somehow summarizes and signs the grant 823such that the IdP can not falsify it, see example 8. Such 824grantvalidator might for example contain grant number and time range 825and be encrypted by shared secret only known to the SP. 826 8274.6 Configuring Bootstraps and Discovery 828---------------------------------------- 829 830> N.B. Before this step you should check that the SAML metadata of the 831> WSP is registered at the IdP, see ~zxcot -a~, etc. Or make 832> sure the auto cot feature is enabled. 833 834The principal step in configuring bootstraps and discovery is to 835register service's EPR in /var/zxid/idpdimd directory. This 836can usually be done on command line as follows: 837 838 zxcot -e http://sp.tas3.pt/mysvc?o=S 'My Service' \ 839 http://sp.tas3.pt/mysvc?o=B urn:x-mysvc \ 840 | zxcot -b /var/zxid/idpdimd 841 842Or if we analyze by parts 843 844 zxcot -e SOAP-Endpoint Description EntityID ServiceType > epr.xml 845 846This invocation is a mere utility for generating an EPR, without credential, 847that can be used as the registration. This might look like 848 849 <wsa:EndpointReference notOnOrAfter="2037-01-05T23:03:59.001Z" 850 wsu:Id="EPRID92lFPo3ZNEt_3rHtJFoU" 851 xmlns:wsa="http://www.w3.org/2005/08/addressing" 852 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> 853 <wsa:Address>http://sp.tas3.pt/mysvc?o=S</wsa:Address> 854 <wsa:Metadata> 855 <di:Abstract xmlns:di="urn:liberty:disco:2006-08">My Service</di:Abstract> 856 <di:ProviderID xmlns:di="urn:liberty:disco:2006-08">http://sp.tas3.pt/mysvc?o=B</di:ProviderID> 857 <di:ServiceType xmlns:di="urn:liberty:disco:2006-08">urn:x-mysvc</di:ServiceType> 858 <sbf:Framework version="2.0" xmlns:sbf="urn:liberty:sb" /> 859 </wsa:Metadata> 860 </wsa:EndpointReference> 861 862The next step is to provide this as "discovery metadata": 863 864 zxcot -b /var/zxid/idpdimd < epr.xml 865 866which will create an entry in the /var/zxid/idpdimd directory (n.b. specifying 867the directory explicitly is necessary because the default directory corresponds 868to the SP directory layout, now we want the IdP directory). 869 870Once the service's EPR (Metadata) exists in the system, any 871user can discover the service, with federations being created 872automatically (unless disabled in the configuration, see MD_FETCH 873and MD_POPULATE_CACHE config options). 874 875If you want the service to be included as a bootstrap, you need 876to mention it either in global /var/zxid/idpuid/.all/.bs directory 877or in user's .bs directory. The file in .bs directory has to have 878the same name as in /var/zxid/idpdimd directory. Contents of the 879file do not matter. You can either touch(1) the file in existence 880or supply -bs flag to zxcot(1): 881 882 zxcot -bs /var/zxid/idpdimd < epr.xml 883 884This registers the bootstrap under .all user. 885 886When all else fails, you can just manipulate the filesystem 887manually, creating the necessary files and directories. 888 8894.6.1 Creating Discovery Bootstrap 890~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 891 892By far the most common type of bootstrap is a discovery bootstrap: 893 894 zxcot -e http://idp.tas3.pt:8081/zxididp?o=S 'Discovery Svc' \ 895 http://idp.tas3.pt:8081/zxididp?o=B urn:liberty:disco:2006-08 \ 896 | zxcot -bs /var/zxid/idpdimd 897 8984.6.2 Creating Identity Mapping and People Service Registrations 899~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 900 901If you want zxididp to support delegation, you would usually 902configure following registrations as well: 903 904 zxcot -e http://idp.tas3.pt:8081/zxididp?o=S 'IDMap Svc' \ 905 http://idp.tas3.pt:8081/zxididp?o=B urn:liberty:ims:2006-08 \ 906 | zxcot -b /var/zxid/idpdimd 907 908 zxcot -e http://idp.tas3.pt:8081/zxididp?o=S 'People Svc' \ 909 http://idp.tas3.pt:8081/zxididp?o=B urn:liberty:ps:2006-08 \ 910 | zxcot -b /var/zxid/idpdimd 911 9124.6.3 Bootstrap Recursiveness 913~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 914 915A problem that arises with the bootstraps is the support for recursive 916or multilevel web service calls. The called service, which receives 917the bootstrap credential, may legitimately call other services in 918turn. If it receives the discovery bootstrap as part of its own 919credential (which may have been a bootstrap in its own right), 920then it can go and discover further services. The discovery bootstrap 921does not have to contain any further bootstraps because the 922discovery service itself knowns about the other services even 923without receiving a bootstrap for each of them individually. 924 925Now consider attempting to operate without discovery: service bootstraps 926for first level services need to contain the bootstraps for second level 927services, which needs to contain bootstraps for third level services. There 928is no easy way to know how many levels deep the call structure may be. 929This effectively leads to infinite recursion in bootstrap generation. 930 931Clearly we need some criteria to cap it. In lack of good and logical 932criteria, we adopt arbitrary one: all bootstraps, except discovery, 933will only propagate one level, i.e. they will be supplied in SSO assertion, 934but only the discovery bootstrap will be supplied in the further 935token assertions. 936 937<<dot: recursive-bootstrap,,1: Recursive bootstrap generation call graph 938rankdir=LR; 939 940{ 941rank=source; 942idp_sso [shape=box]; 943di_query [shape=box]; 944}; 945 946di_query -> add_fed_tok_to_epr; 947add_fed_tok_to_epr -> mk_user_a7n_to_sp; 948mk_user_a7n_to_sp -> gen_boots; 949mk_user_a7n_to_sp -> add_ldif_attrs; 950gen_boots -> add_fed_tok_to_epr; 951idp_sso -> mk_user_a7n_to_sp; 952 953>> 954 9554.6.4 Using zxidcot.pl Web GUI to Register Web Service Providers 956~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 957 958As described in the metadata registration section, zxidcot.pl 959web GUI can be used to create discovery registrations. Just 960point your browser to https://idp.example.com/zxidcot.pl?op=direg 961and fill in the form fields: 962 963Endpoint:: URL for sending SOAP messages 964Abstract:: Human readable description of the service 965EntityID:: aka ProviderID 966ServiceType:: a URN to identify the kind of service offered 967 by the WSP. 968 969The underlying implementation uses the ~zxcot -e | zxcot -b~ command 970line technique. 971 9724.7 Attribute Selection and Privacy Manager 973------------------------------------------- 974 975zxidatsel.pl CGI script provides a web GUI for attribute release 976consent and selection by the users. This interface can be enabled 977by setting 978 979 ATSEL_PAGE=zxidatsel.pl 980 981in /var/zxid/idpzxid.conf 982 983You can control the look of Attribute Selection by editing an.css 984stylesheet and atsel-main.html template. 985 986Usually Attribute Selection is accessed as part of the SSO flow right 987after authentication step, but it is also possible to access it 988directly to manage User's attribute sharing preferences. In this 989respect it serves as a Privacy Manager. 990 9914.8 User Specific Logging 992------------------------- 993 994In addition to the official audit trail logging, zxididp logs 995certain basic events on per user basis. This serves to allow 996easily displaying to the user recents events about him, raising 997awareness and allowing user to spot anomalous transactions. 998The log is kept in file /var/zxid/idpuid/UID/.log 999 10004.9 Proxy IdP Support 1001--------------------- 1002 1003To adapt non-!!TAS3 IdPs to !!TAS3 environment, the strategy of using 1004SAML2 Proxy IdP profile is recommended. The !!TAS3 SP redirects the 1005use to a !!TAS3 enabled +proxy IdP+ (aka "middle IdP"), which then 1006offers the user a choice of actual (non-!!TAS3) IdP to use and 1007plays the SAML SP role towards that IdP. When the user has been 1008authenticated, the assertion is returned to the middle IdP, which 1009will use information in it to mint an assertion that is returned 1010to the !!TAS3 enabled SP. The !!TAS3 assertion SHOULD contain the 1011attributes of the original assertion. It MAY contain the original 1012assertion as well, if audience restriction permits this. 1013 1014The Proxy IdP Profile can also used for facilitation of interoperation 1015across trust networks. SPs in one trust network use the IdP in their 1016home trust network, which then contacts the foreign IdP. This way only 1017the home trust network's IdP needs to have trust relationship with 1018the foreign IdP. This is much more scalable than each SP having to 1019trust directly the foreing IdPs. See [LibertyInterFed] for further 1020discussion. 1021 1022The Proxy IdP Profile is described in [SAML2core] section 3.4.1.5 1023"Proxying" (pp.54-55) and also in [SAML2iop] section 3.3.1 IdP Proxy 1024Feature (pp.11-12), as well as in [SAML2iopDGI] Step D (p.17-19) 1025associated with "IdP Extended" and "SP Extended" conformance modes. 1026 10274.10 Supported Specifications 1028----------------------------- 1029 1030As of version 0.47 (20100114) zxididp supports the following specifications 1031 1032* SAML 2.0 IdP Lite [SAML2core], [SAML2conf] 1033 - SSO and SLO [SAML2prof] 1034 - attributes 1035 - bootstraps 1036 - redirect and post bindings [SAML2bind] 1037 - Well Known Location (WKL) Metadata Exchange [SAML2meta] 1038 - Shibboleth2 [Shibboleth] 1039 - Password authentication 1040 - Yubikey authentication 1041 - eID card and client certificate authentication 1042* ID-WSF 2.0 Discovery [Disco2] 1043* ID-WSF 2.0 Authentication Service [SOAPAuthn2] 1044* TAS3 Architecture Core 1045 10464.10.1 Imminently Planned Specifications (TODO) 1047~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1048 1049* TAS3 Trust and Privacy Negotiation 1050* Master and TAS3 audit busses 1051* SAWS over SOAP logging (with OpenXDAS events) 1052* OpenXDAS log format 1053* AMQP logging (with OpenXDAS events) 1054* MASTER project event modelling 1055* AAPML (and CARML) support 1056 10574.10.2 Nice to Have Specifications (TBD) 1058~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1059 1060* SAML 1.1 1061* Infocard (Cardspace) and WS-Federation [MS-MWBF] 1062* Simple Web Token (SWT) support [Hardt09] 1063* OAuth-WRAP support [Tom09] 1064* XACML Authorization Decision Query for SSO 1065 10664.11 Cleaning Up Old Sessions 1067~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1068 1069Old session files will accumulate in the filesystem. You should use 1070a cron job to clean them up 1071 1072 touch /var/zxid/ses; find /var/zxid/ses -atime +30 | xargs rm -rf 1073 1074N.B. the ~touch~ is needed in the above command line to ensure that 1075the entire directory is not deleted. 1076 10775 People Service and Delegation Support 1078======================================= 1079 1080zxididp can be configured to support delegation using Identity Mapping 1081Service and People Service. As of 20100922 the People Service implementation 1082is not complete, but is sufficient to support delegation use cases (we are 1083mainly missing the buddy list manipulation). 1084 10855.1 People Service Use of Local UID Directory (idpuid/) 1086------------------------------------------------------- 1087 1088Invitations and object IDs have separate namespaces. Invitation 1089can be for known object or it can be open. In the open case 1090it can be accepted by existing object, or a new object can 1091be created. 1092 1093 1094 1095zxididp uses local idpuid/ directory to implement the IdP logins and 1096to store users federations, bootstraps, and attributes. 1097 1098 /var/zxid/ 1099 | 1100 +-- idpuid/ Local user ID (local login name) to SHA1 mapping 1101 | | 1102 | +-- JOE/ Local user has directory whose name is the login uid 1103 | | | 1104 | | +-- .log Log of operations regarding the user 1105 | | +-- .ps/ User's People Service Objects and Inviations (i.e. buddy list) 1106 | | | | 1107 | | | +-- objid 1108 | 1109 +-- idpinv/ Invitations 1110 | | 1111 | `-- INVID Invitation object as LDIF 1112 11135.1.1 Invitation 1114~~~~~~~~~~~~~~~~ 1115 1116Invitation (identified by SPtoPSRedirectURL) needs to remember 1117 1118* Corresponding user (or object if invitation is directed to specific object) 1119* PStoSPRedirectURL 1120* Permissions, i.e. which sites and web services the delegatee is allowed to access 1121 by virtue of invitation. In effect, invitation becomes a permissions bundle 1122 that can be revoked without revoking other invitations. 1123* Max usage 1124* Usage count (when usage >= max usage, invitation is no longer accepted 1125* Start time 1126* Expiry time 1127 1128Invitation is stored in LDIF file at path 1129 1130 /var/zxid/idpinv/INVID 1131 1132*Syntax is similar to LDIF (as is the syntax of .at files)* 1133 1134 dn: invid=i341343122 1135 invid: i341343122 1136 uid: joedoe 1137 psobj: o12321 1138 ps2spredir: https://sp1.tas3.pt/foto/1234 1139 perm: # See below 1140 maxusage: 1 1141 usage: 0 1142 starts: 2010-09-22T23:08:55Z 1143 expires: 2010-09-29T23:08:56Z 1144 1145<<ignore: zx_date_time_to_secs() >> 1146 11475.1.2 People Service Object 1148~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1149 1150Object needs to remember 1151 1152* Display names 1153* Tags 1154* federated id of the invitee (filled in once invitee dereferences invite URL) 1155* Permissions, i.e. which sites and web services the delegatee is allowed to access 1156 by virtue of his own identity 1157* Invitation IDs that apply 1158 1159*Syntax is similar to LDIF (as is the syntax of .at files)* 1160 1161 dn: psobj=o12321,uid=joedoe 1162 psobj: o12321 1163 uid: joedoe 1164 nodetype: 0 1165 idpnid: F13432 1166 tag: #golden 1167 tag: #friend 1168 psobjref: o3232 1169 psobjref: o3233 1170 invid: i341343122 1171 invid: i341343123 1172 perm: # See below 1173 1174ObjectID (psobj) has particlar privacy threat in that several WSCs may 1175see them and be able to correlate about the user that the object refers 1176to (see brief discussion in sec 2.1.4 "<ObjectID> Element", ll.278-281, 1177of [PeopleSvc]. 1178 1179We adopt solution where each psobj id issued towards an entity (SP, WSC) is 1180the psobj encrypted (AES-128-CBC) with key consisting of concatenation 1181of secret (/var/zxid/pem/psobj-enc.key) known to ps server only (i.e. the 1182zxididp) and the Entity ID of the entity. See zxid_psobj_enc() and 1183zxid_psobj_dec() in zxidps.c. 1184 11855.1.3 Delegated Permissions 1186~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1187 1188Permissions are already in context of delegator and delegatee and need to capture 1189 1190* Whitelist of site EIDs allowed to delegatee 1191* For each site a list of attribute value pairs (in cgi query string syntax). 1192 As of 20100922 all of the name value pairs are for future expansion. For 1193 example the illustrated ~localpath~ will not be intrpreted or enforced. 1194 1195*Syntax (LDIF attribute with dollar separation)* 1196 1197 perm: https://sp1.tas3.pt/sp?o=B$localpath=/protected 1198 perm: https://sp2.tas3.eu/sp?o=B 1199 perm: *$desc=This+is+wild+card+permission.+Use+with+care. 1200 1201The permissions lines from both invitation and object are used 1202by the discovery and identity mapping services to determine 1203if delegated operations should be permitted. 1204 12055.2 SP Side Support for Delegation 1206---------------------------------- 1207 1208When an SP starts delegation sequence, it establishes a delegation 1209record in delegator's (Alice's) user directory, identifying delegated resource, 1210and then calls AddEntity() embedding the id of the delegation record 1211in the ~PStoSPRedirectURL~. It is also possible for the SP to simply 1212encode Alice and the resource in the ~PStoSPRedirectURL~ (in symmetrically 1213encrypted with key only known to SP). The AddEntity() returns <ObjectID> 1214that eventually allows delegatee (Bob) to be identified at PSa. The Object ID 1215is remembered in the delegation record. AddEntity() also returns in ~SPtoPSRedirectURL~ 1216an invitation, which Alice passes to Bob. 1217 1218When delegatee (Bob) clicks the invite URL, he lands on PSa and 1219federates by performing SSO using IdPb. He gets redirected to SP using 1220~PStoSPRedirectURL~. This allows SP to understand which resource is 1221being accessed in delegated way. Bob will usually perform SSO to SP 1222using IdPb. This allows Bob to be permanetly added to white list of 1223delegation record of Alice's resource, so that in future visits Bob 1224can access Alice's resource directly without having to go through 1225the invitation. A record of accessible resource may also be kept on 1226Bob's account. This facilitates Bob's navigation, but the access control 1227decisions must always be based on delegation record on Alice's side. 1228 1229 /var/zxid/ 1230 | 1231 +-- ses/ Sessions 1232 | | 1233 | +-- SESID/ Each session has its own directory 1234 | 1235 +-- user/ Local user accounts (if enabled) 1236 | | 1237 | +-- SHA1/ Each local user has a directory whose name is SHA1 1238 | | | of the user's NameID (idpnid) and IdP Entity ID 1239 | | +-- .mni Information needed by Name ID management 1240 | | +-- PS,SHA1 Long term People Service EPR, kept in its own file 1241 | | +-- .deleg/ Delegations (invitations) user has issued 1242 | | | | 1243 | | | +-- DELEG 1244 | | | `-- DELEG 1245 | | | 1246 | | +-- .access/ Invitations user has received (delegations to access other's resources) 1247 | | | | 1248 | | | +-- ACCESS 1249 | | | `-- ACCESS 1250 | | | 1251 | | `-- .pw User's local password if any (usually none) 1252 | | 1253 | `-- SHA1b -> ../uid/Sue SHA1 can also be symlink to local account 1254 | 1255 +-- uid/ Local user ID (local login name) to SHA1 mapping 1256 | | 1257 | +-- joe -> ../user/SHA1 Symlink points to the real user directory 1258 1259Alice's delegation records are held in her .deleg subdirectory: 1260 1261 dn: deleg=d122413,idpnid=FAliceatSP 1262 deleg: d122413 1263 idpnid: FAliceatSP 1264 rsrc: /protected 1265 pseid: https://ps.tas3.pt/ps?o=B # Entity ID of Alice's PS (for future membership queries) 1266 psepr: ... # Hold long term EPR for PSa for making membership queries 1267 diepr: ... # Hold long term EPR for DIa for making web service calls 1268 whitelist: FBobatSP 1269 whitelist: FCecilatSP 1270 psobj: o123 # PS Object IDs of yet unresolved invitations 1271 1272Bob's delegation hint record (similar to real delegation record, but 1273interpretted differently) are held in his .access subdirectory: 1274 1275 dn: access=d122413,idpnid=FofBobatSP 1276 idpnid: FofAliceatSP 1277 rsrc: /protected 1278 1279Since multiple IdPs can be involved, the user directory structure must 1280account for the possibility that Federated ID assigned by one IdP for 1281one user can be assigned by another IdP for different user. This is 1282arranged by hashing together idpnid and the Entity ID of the IdP (see 1283zxid_user_sha1_name()). 1284 12855.3 Accessing Alice's Discovery EPR 1286----------------------------------- 1287 1288There are three methods for Bob to obtain Alice's Discovery EPR (DIa-EPR) 1289 12901. Using PSb, which will ask from IMa (the Liberty Alliance documented way) 12912. Using PSa, which may ask IMa. PSa-EPR is passed from Alice to Bob by the inviting SP 12923. DIa-EPR is passed from Alice to Bob directly by the inviting SP 1293 1294[IDWSF2Overview] section 2.4 "Cross-principal Identity Service 1295Access", pp.19-31, describes how Bob can call Alice's service 1296(n.b. their description has the roles reversed). In that description, 1297the crucial step of obtaining Alice's Discovery EPR is facilitated by 1298Bob's People Service (+NOT Alice's People Service!+) using 1299<ResolveIdentifierRequest> (SP to PSb) that makes 1300<IdentityMappingRequest> (PSb to IMa) and returns the DItokA all the 1301way through call chain. 1302 1303Here the assumption was that Bob can discover his own PSb and that PSb 1304knows where IMa is. This latter knowledge is only possible if Alice 1305had been federated to PSb, which would presume bidirectional 1306friendship relationship. Such flow is indeed possible within the 1307PeopleService specification, using <CreatePSObject> option of 1308<AddEntityRequest>. Advantage of this flow is that Bob can access 1309WSPa even from SPs other than the inviting SP. 1310 1311However, if no bidirectional relationship is desired, then the flow 1312does not work. We need a way for Bob to get Alice's discovery EPR with 1313facilitation only by Alice's resources. 1314 1315Bob will have federated with Alice's PS during invitation, so it 1316should be possible to direct <ResolveIdentifierRequest> to PSa, if 1317only we knew where PSa is. In the case of Bob visiting the SP that 1318Alice used for starting the invitation, it is possible to arrange for 1319the delegation object to remember Alice's PSa-EPR so that we get the 1320ball rolling. Problem is that for this to work, we need to be able to 1321express Alice's "self" identity: we adopt the policy of passing 1322<Token> from PSa-EPR (i.e. Alice's token) and specifying <TokenPolicy> 1323where type XML attribute specifies the intended use as delegation. 1324By adopting a convention where <Token> is just a reference to 1325the Target Identity (Alice) of the call and the security token 1326identifies the delegatee (Bob), the PSa can manufacture appropriate 1327DIa(deleg B)-EPR whose Token is an Assertion with Alice as subject 1328and Bob's token or identity in advice or attribute field (the exact 1329place where this is expressed need to be standardized and documented). 1330 1331In fact, the delegation object could even remember Alice's DIa-EPR for 1332Bob to use. In this sense the resource at SP that Alice delegates 1333access to is in fact the DIa-EPR. While this is simple, there is 1334certain lack of central control. For example, the SP could decide 1335to pass DIa-EPR to Mallory. Basically the model (2) is preferred 1336as it results in special DIa-EPR that expresses the delegation to Bob. 1337Model (3) uses bare DIa-EPR, in effect impersonating Alice rather 1338than conveying genuine delegation relationship. 1339 1340<<if: ZXIDBOOK>> 1341<<else: >> 1342 134396 License 1344========== 1345 1346Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved. 1347Copyright (c) 2009-2011 Sampo Kellom�ki (sampo@iki.fi), All Rights Reserved. 1348Copyright (c) 2012-2015 Synergetics (sampo@synergetics.be), All Rights Reserved. 1349Author: Sampo Kellom�ki (sampo@iki.fi) 1350 1351Licensed under the Apache License, Version 2.0 (the "License"); 1352you may not use this file except in compliance with the License. 1353You may obtain a copy of the License at 1354http://www.apache.org/licenses/LICENSE-2.0 1355 1356Unless required by applicable law or agreed to in writing, software 1357distributed under the License is distributed on an "AS IS" BASIS, 1358WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1359See the License for the specific language governing permissions and 1360limitations under the License. 1361 1362<<zxid-ref.pd>> 1363 1364<<doc-end.pd>> 1365<<notapath: E.g TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>> 1366<<EOF: >> 1367 1368To: ZXID.User@lists.unh.edu 1369Date: 20140129 1370Subject: Re: ZXID as SAML SP and IDP proxy IPD 1371 1372Stefan Rasmusson <rasmusson.stefan@gmail.com> said: 1373> I have tried to read about ZXID but I have a hard time, understanding what 1374> it acctaully is, a product? som libraries? So I'll just ask based on what 1375> my needs are. 1376> 1377> I need to setup an identity federation with Artifact binding and SLO over 1378> SOAP. 1379> I would also like to set up a IDP proxy to act as a local IDP between my 1380> local services. 1381> 1382> Is this possible with ZXID? 1383 1384Main focus of ZXID is to be an SP. 1385 1386It is "product" in the sense that it offers mod_auth_saml that 1387can be used with Apache to achive this without programming. 1388 1389It is also a library, which allows implementation of SP, as well as 1390ID-WSF WSC and WSP, from various programming languages including 1391C/C++, Java, php, and perl (Net::SAML). 1392 1393zxididp implements SAML IdP, including proxy IdP. It is a "product" in 1394the sense that it is self contained stand-alone program. 1395 1396zxididp is also available on SaaS basis, see 1397https://zxidp.org/index-idp.html and 1398https://zxidp.org/idp?o=F 1399option "Authenticate using another IdP (Proxy IdP)". 1400 1401The documentation at http://zxid.org/html/zxid-idp.html 1402does mention the proxy IdP possibility, but does not 1403really tell how to configure it. Turns out it is quite 1404easy to use: basically the proxy IdP functionality is always 1405latently available - you can see this by looking at the IdP 1406metadata which lists SPSSODescriptor (i.e. zxididp is 1407able to act as SP towards another IdP). To use the functionality, 1408all you need is make it available in the user interface. Just 1409edit an-main.html of the IdP. You can look at the zxidp.org login 1410screen for an example. 1411 1412Cheers, 1413--Sampo 1414 1415<<fi: >> 1416