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