1README.zxid-tas3 2================ 3$Id: README.zxid-tas3,v 1.4 2009-10-18 12:39:10 sampo Exp $ 4 5ZXID is general purpose SSO and Identity Web Services project, see zxid.org 6 7TAS3 - Trustable Architecture for Secure Shared Services - is an European 8FP7 research project that has chosen to use SAML 2.0 and ID-WSF 2.0 9and is using ZXID as one implementation of these technologies. See tas3.eu 10 11The research leading to these results has received funding from the 12European Community's Seventh Framework Programme (FP7/2007-2013) under 13grant agreement number 216287 (TAS3 - Trusted Architecture for Securely 14Shared Services - www.tas3.eu). 15 16Since ZXID is important for TAS3 and vice versa, ZXID Makefile contains 17some targets for producing ZXID specific packages 18 19 make tas3maspkg # T3-SSO-ZXID-MODAUTHSAML-V.VV.zip 20 make tas3phppkg # T3-SSO-ZXID-PHP-V.VV.zip 21 make tas3javapkg # T3-SSO-ZXID-JAVA-V.VV.zip 22 make tas3idppkg # T3-IDP-ZXID-V.VV.zip 23 make tas3rel # build all of the above 24 make tas3copyrel # scp release packages 25 26https://portal.tas3.eu/pool/ -- Download from here 27http://idpdemo.tas3.eu/cot/ -- Register your metadata here 28http://idpdemo.tas3.eu/zxididp?o=B -- Publicly available TAS3 demo IdP 29 30<<dia: tas3-integration,,:bg,fg,comp,api,zxmod:: API and modules for SSO and web service call.>> 31 32For help, I recommend joining the ZXID mailing 33list zxid.user@lists.unh.edu 34at http://listproc.unh.edu/archives/zxid.user/ 35 36You can also see TAS3 Architecture Video 37 38http://www.youtube.com/watch?v=QXQ7bbOULYc 39http://zxid.org/tas3/ArchitectureExplained_3_4_1.avi 40 41--Sampo 42 43 44T3-ZXID-LINUX-X86 Install 45------------------------- 46 47T3-ZXID-LINUX-X86 package contains binaries for Linux x86 platforms. 48It was produced by compiling the source code in T3-ZXID-SRC. 49 50To obtain latest version of the T3-ZXID-LINUX-X86 package please 51check https://portal.tas3.eu/pool/ (login needed). 52 531. Download and unzip the package 54 55 unzip T3-ZXID-LINUX-X86_1.03.zip 56 cd T3-ZXID-LINUX-X86_1.03 57 582. Check that your system has all the dependency libraries 59 installed: 60 61 ldd zxididp 62 linux-gate.so.1 => (0xb7818000) 63 libpthread.so.0 => /lib/libpthread.so.0 (0xb77d6000) 64 libcurl.so.3 => not found 65 libssl.so.0.9.8 => /usr/lib/libssl.so.0.9.8 (0xb7792000) 66 libcrypto.so.0.9.8 => /usr/lib/libcrypto.so.0.9.8 (0xb766a000) 67 libz.so.1 => /lib/libz.so.1 (0xb7656000) 68 libc.so.6 => /lib/libc.so.6 (0xb7512000) 69 /lib/ld-linux.so.2 (0xb7819000) 70 libdl.so.2 => /lib/libdl.so.2 (0xb750e000) 71 72 Here you can see that libcurl.so.3 was not found. To remedy 73 such dependencies you may need to adjust LD_LIBRARY_PATH 74 or you may need to simply install the dependency packages 75 76 Debian / Ubuntu Redhat 77 ------------------------------ ------------------------- 78 sudo apt-get install libcurl sudo yum install libcurl 79 sudo apt-get install openssl sudo yum install openssl 80 sudo apt-get install libz sudo yum install libz 81 82 Then recheck with ldd that all libraries are found. 83 843. Copy maintenance utilities to a directory in your PATH 85 86 sudo cp zxcot zxpasswd zxmkdirs.sh zxlogview zxdecode /usr/local/bin 87 884. Copy zxididp and SP demos to document root of your web server 89 90 cp zxididp zxidhlo.php /srv/www/htdocs # OpenSUSE 10.2 91 92 The document root directory is distribution and/or web server 93 and/or local configuration specific. You should know where 94 it is. 95 96 Configuring and using zxididp is further documented in 97 zxid-idp.pd file or on web site http://zxid.org/html/zxid-idp.html 98 995. Copy PHP libraries to expected place 100 101 sudo mkdir -p `php-config --extension-dir` 102 sudo cp php/php_zxid.so `php-config --extension-dir` 103 104 If you do not intend to use PHP, you can skip this step. 105 106 The PHP usage is further documented in 107 108 php/README.zxid-php: PHP specific README 109 zxid-php.pd: Using ZXID from PHP 110 zxidhlo.php: Example code 111 Web site: http://zxid.org/html/zxid-php.html 112 1136. Copy Java libraries to expected place 114 115 If you do not intend to use Java, you can skip this step. 116 117 Here the tricky part is knowing what "the expected place" is. 118 This will depend on how you configure your servlet engine. 119 You will need to investigate your own configuration and 120 tweak the following accordingly: 121 122 sudo cp zxidjava/libzxidjni.so /usr/local/apache-tomcat-5.5.20/bin/ 123 sudo cp -r zxidjava /usr/local/apache-tomcat-5.5.20/webapps/your-servlet-dir 124 125 To get things to work you may need to perform detctive work 126 to understand where Java is looking for them or adjust SERVLET_PATH 127 and/or LD_LIBRARY_PATH. zxid-java.pd has entire section of 128 documentation dedicated to solving these issues. 129 130 The Java usage is further documented in 131 132 zxidjava/README.zxid-java Java specific README 133 zxid-java.pd Using ZXID from Java 134 zxidsrvlet.java Ready to use SSO servlet 135 zxidappdemo.java Example code for using SSO servlet 136 zxidhlo.java Example code for direct SSO integration 137 Web site: http://zxid.org/html/zxid-java.html 138 1397. Copy Apache SSO support module to the right place 140 141 sudo cp mod_auth_saml.so /usr/local/httpd/modules 142 143 You will need to determine where your distribution has 144 installed the Apache httpd and adjust the path accordingly. 145 Once you think you got it right, you can check with 146 command 147 148 httpd -M 149 150 the following line should appear in the output 151 152 auth_saml_module (shared) 153 154 Despite the name, it indicates that mod_auth_saml has 155 loaded successfully. 156 157 > N.B. Linux distributions often rename httpd as apache2 and 158 > install it in a location different than where apache httpd 159 > source code distribution would install by default. For 160 > example, on Ubuntu the modules directory seems to be 161 > /usr/lib/apache2/modules 162 163 1648. Copy include files and libraries to where your development 165 environment can find them: 166 167 sudo cp libzxid.a /usr/local/lib 168 sudo cp -r include/zx /usr/local/include 169 170 This step is only needed if you plan to compile programs 171 to use zxid. If that is your plan and skillset, you may 172 prefer to install zxid from source anyway. 173 1749. Create directory hierarchy 175 176 Before you run these commands, you need to find out what user 177 your httpd runs as. Here we have assumed user "apache". Adjust 178 as needed. 179 180 sudo zxmkdirs.sh # For the SP 181 chown -R apache /var/zxid 182 su apache 183 echo NICE_NAME=Your SP Branding >/var/zxid/zxid.conf 184 echo ORG_NAME=Your Organization >>/var/zxid/zxid.conf 185 echo ORG_URL=http://your.org/ >>/var/zxid/zxid.conf 186 echo URL=https://sp1.zxidsp.org:8443/zxidhlo >>/var/zxid/zxid.conf 187 188 zxmkdirs.sh /var/zxid/idp # For the IdP 189 echo NICE_NAME=Your IdP Branding >/var/zxid/idpzxid.conf 190 echo ORG_NAME=Your IdP Organization >>/var/zxid/idpzxid.conf 191 echo ORG_URL=http://youridp.org/ >>/var/zxid/idpzxid.conf 192 echo URL=https://idp1.zxid.org:8443/zxididp >>/var/zxid/idpzxid.conf 193 echo IDP_ENA=1 >>/var/zxid/idpzxid.conf 194 echo AS_ENA=1 >>/var/zxid/idpzxid.conf 195 echo PDP_ENA=1 >>/var/zxid/idpzxid.conf 196 197 In the above, the configuration files for SP and IdP were created. Some 198 configuration options are actually set in the source code of the respective 199 applications. In the config files you MUST set 200 201 NICE_NAME:: Used for user interface purposes (displayed to user) to identify the site. 202 ORG_NAME:: The name of the legal entity responsible for the site, shown to user. 203 ORG_URL:: Institutional web site of the legal entity, shown to user. 204 URL:: Entity Id of the web site. For demo, set them as shown (often set in source). 205 20610. Create certificates 207 208 There are two ways to obtain certificates: (a) Allow ZXID to generate them 209 for you, and (b) obtain and install commercial certificates. 210 211 a. Using auto generated certificates 212 213 i. For SP certificates, run 214 215 zxcot -m 216 217 and observe that the output has two large base64 blobs. They 218 are inside <ds:X509Certificate> XML elements. zxcot -m generates 219 metadata for the SP. In doing so, it will also generate the 220 certificates on the fly if they do not exist. If the filesystem 221 permissions are incorrect, it will fail to generate the certificates. 222 This is why the `chown -R apache /var/zxid' command was issued 223 in the previous step (9). Check the permissions with 224 225 ls -alF /var/zxid/pem 226 227 Keep running zxcot -m until you get it to output the certificates. 228 229 ii. For IdP certificates, run 230 231 zxcot -ci -m 232 233 Again, the certificates are generated on the fly. If not, check 234 permissions with 235 236 ls -alF /var/zxid/idppem 237 238 N.B. This assumes the IdP is configured to use the default 239 PATH /var/zxid/idp (-ci is shorthand for this). If this is 240 not the case, you will need to supply the PATH explicitly: 241 242 zxcot -c 'PATH=/your/idp/path/&IDP_ENA=1' -m 243 244 Similarily, if any config options (that affect metadata) are 245 specified in source code rather than in zxid.conf file, 246 you would need to supply them to zxcot using the -c option. 247 248 b. Installing previously obtained certificates 249 250 We assume you have the certificate in file cert.pem and the 251 private key in priv.pem. 252 253 i. For SP 254 255 sudo su 256 cat cert.pem priv.pem >/var/zxid/pem/ssl-nopw-cert.pem # put both in one file 257 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/sign-nopw-cert.pem 258 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/enc-nopw-cert.pem 259 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/logenc-nopw-cert.pem 260 cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/logsign-nopw-cert.pem 261 chmod 600 /var/zxid/pem/* 262 # end su 263 264 Check with 265 266 zxcot -m 267 268 ii. For IdP 269 270 sudo su 271 cat cert.pem priv.pem >/var/zxid/idppem/ssl-nopw-cert.pem # put both in one file 272 cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/sign-nopw-cert.pem 273 cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/enc-nopw-cert.pem 274 cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/logenc-nopw-cert.pem 275 cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/logsign-nopw-cert.pem 276 chmod 600 /var/zxid/idppem/* 277 # end su 278 279 Check with 280 281 zxcot -ci -m 282 283T3-IDP-ZXID Install 284------------------- 285 286Prerequisite:: you must have CGI capable web server, such as mini_httpd, Apache, or IIS. 287 288See also: zxid-idp.pd for more comprehensive documantation 289 290N.B: T3-IDP-ZXID package has been merged with T3-ZXID-LINUX-X86 package, see above. 291 2921. Download and unzip the package 293 2942. ldd zxididp 295 2963. Copy zxididp to document root of your web server 297 298 cp zxididp /srv/www/htdocs # OpenSUSE 10.2 299 3004. Create directory hierarchy and initial config 301 302 mkdir /var/zxid 303 chown webuser /var/zxid 304 su webuser 305 zxmkdirs.sh /var/zxid/idp 306 ls -alFR /var/zxid 307 3085. Create configuration file /var/zxid/idpzxid.conf 309 310 URL=http://idp.tas3.pt:8081/zxididp 311 PDP_ENA=1 312 3136. Create a user 314 315 mkdir /var/zxid/idpuid/koerkki 316 echo -n salainen >/var/zxid/idpuid/koerkki/.pw 317 3187. Configure web server to run the zxididp as a CGI script. 319 320 On Apache edit httpd.conf (often in /etc/apache2/httpd.conf) 321 322 <Location "/zxididp"> 323 Options ExecCGI 324 SetHandler cgi-script 325 </Location> 326 3278. Test it 328 329 tail -f /var/tmp/zxid.stderr 330 tail -f /var/log/apache2/error_log 331 332 http://idp.tas3.pt:8081/zxididp?o=B 333 334T3-ZXID-SRC Compile and Install 335------------------------------- 336 337After unzipping the package, unpack the tarball contained therein, and 338read INSTALL.zxid contained in the tarball. 339 340Mapping between TAS3 API and ZXID API 341------------------------------------- 342 343* Use zxidjava/libzxidjni.so instead of tas3jni.so 344* import zxidjava.*; instead of import tas3.*; 345* System.loadLibrary("tas3jni.so"); should become 346 System.loadLibrary("zxidjava/libzxidjni.so"); 347* In class names replace "tas3" with "zxidjni", for example 348 349 tas3.wsp_validate() 350 351 becomes 352 353 zxidjni.wsp_validate() 354 355--Sampo