| Wiki Reorganisation | |:-------------------:| | This page has been classified for reorganisation. It has been given the category **MOVE**. | | The content of this page will be revised and moved to one or more other pages in the new wiki structure. | ## SAML Authz C-based Client Library (libglobus_adq) and Client Test Program ### Overview of the C-based Client Library (libglobus_adq) This package contains a C-based client library that builds on top of gSOAP for handling the SOAP communication. gSOAP was chosen to generate the SAML [ AuthzDecisionQuery ](http://www.ci.uchicago.edu/wiki/bin/view/ESGProject/AuthzDecisionQuery) based query objects and handle the [ AuthzDecisionStatement ](http://www.ci.uchicago.edu/wiki/bin/view/ESGProject/AuthzDecisionStatement) objects in response. The skeleton code was automatically generated from WSDL, which saved a lot of time that could have been used addressing the many details involved from scratch. This package is named libglobus_adq , which for lack of a better name, stands for (libglobus_ [ AuthzDecisionQuery ](https://github.com/ESGF/esgf.github.io/wiki/AuthzDecisionQuery) ). Since this package DEPENDS on gSOAP, instructions for downloading and building are included. If your distribution already has gSOAP installed, be sure to read the troubleshooting section below if you run into problems. ### Downloading and installing gSOAP Download gSOAP 2.7.15 as linked here: * [ http://downloads.sourceforge.net/project/gsoap2/gSOAP/2.7.15%20stable/gsoap_2.7.15.tar.gz?use_mirror=cdnetworks-us-1 ](http://downloads.sourceforge.net/project/gsoap2/gSOAP/2.7.15%20stable/gsoap_2.7.15.tar.gz?use_mirror=cdnetworks-us-1) Unpack, compile and install the library into a known location (for this example, I've chosen _ /usr/local/gsoap _ ). An example session of this is included here for your reference: # download gSOAP neillm@boiler:/tmp$ wget http://downloads.sourceforge.net/project/gsoap2/gSOAP/2.7.15%20stable/gsoap_2.7.15.tar.gz?use_mirror=cdnetworks-us-1 ... snip ... # untar and build gSOAP neillm@boiler:/tmp$ tar -xzf gsoap_2.7.15.tar.gz neillm@boiler:/tmp$ cd gsoap-2.7 neillm@boiler:/tmp/gsoap-2.7$ neillm@boiler:/tmp/gsoap-2.7$ ./configure --prefix=/usr/local/gsoap ... snip ... # this step requires (b)yacc and bison, perhaps among other third party libraries neillm@boiler:/tmp/gsoap-2.7$ make && make install ... snip ... ### Downloading and Building libglobus_adq You can download a source tarball of the package from the following link: * [ http://rainbow.llnl.gov/dist/globus/gridftp/libglobus_adq-0.9.1.tar.gz ](http://rainbow.llnl.gov/dist/globus/gridftp/libglobus_adq-0.9.1.tar.gz) The steps to compile and builds this are as follows: neillm@boiler:/tmp$ wget http://rainbow.llnl.gov/dist/globus/gridftp/libglobus_adq-0.9.1.tar.gz ... snip ... neillm@boiler:/tmp$ tar -xzf libglobus_adq-0.9.1.tar.gz neillm@boiler:/tmp$ cd libglobus_adq-0.9.1 # edit build.sh file to properly adjust the "GSOAP_PATH" variable # the default is GSOAP_PATH=/usr/local/gsoap, which should work if you followed the above step # now run the build script; you may see some warnings that are ok to ignore neillm@boiler:/tmp/libglobus_adq$ sh build.sh ... snip ... # if all built well, copy the shared libraries to $GLOBUS_LOCATION/lib neillm@boiler:/tmp/libglobus_adq$ cp libglobus_adq.so* $GLOBUS_LOCATION/lib ### Running the libglobus_adq test Client After building the package, you will see output that looks similar to the following: ... snip ... Compilation successful Build completed! Run the client with "LD_LIBRARY_PATH=/tmp/libglobus_adq ./libglobus_adq_client" To install the library for use with Globus, copy libglobus_adq.so* to $GLOBUS_LOCATION/lib Since a shared library is built but it's not explicitly in your system's library path, you must set the LD_LIBRARY_PATH variable so that it can be located before running programs that use it. Alternatively, you can google some instructions on how to use ldconfig and update the appropriate ld.so.conf file for your distribution. Running the libglobus_adq_client as-is, should yield a result like this: neillm@boiler:~/working/libglobus_adq$ LD_LIBRARY_PATH=/home/neillm/working/libglobus_adq ./libglobus_adq_client Usage: ./libglobus_adq_client An example command line may look like: ./libglobus_adq_client https://localhost/esgcet/saml/soap/secure/authorizationService.htm https://myopenid.com/testUser gsiftp://localhost:2811//data/file.nc If you test it with proper parameters pointing to a running Authorization service and plug in a user's OpenID for a file it has access, it will yield a result similar to this: neillm@boiler:~/working/libglobus_adq$ LD_LIBRARY_PATH=/home/neillm/working/libglobus_adq ./libglobus_adq_client https://esg.prototype.ucar.edu/saml/soap/secure/authorizationService.htm https://esg.prototype.ucar.edu/myopenid/testUser gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc Using CA Path: /etc/grid-security/certificates Using normalized Action of Read About to do soap call ...done (Success) Response Status urn:oasis:names:tc:SAML:2.0:status:Success, ID 422e470a-5acc-4a59-8503-3d00c00b50da, InResponseTo 140736105438016, IssueInstant 1294776048 Response type Assertion Assertion ID e81fe577-02c8-466f-a048-76c2cb2eb411, Version 2.0, IssueInstant 1294776048, AssertionType AuthzDecisionStatement AuthzDecisionStatement: Resource gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc, Action Read, Decision PERMIT Authz Decision returned successfully for Openid https://esg.prototype.ucar.edu/myopenid/testUser Resource gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc, Action Read, Decision Permit If however you point it to a non-running Authorization service, you may see an error like this: neillm@boiler:~/working/libglobus_adq$ LD_LIBRARY_PATH=/home/neillm/working/libglobus_adq ./libglobus_adq_client https://localhost:8080/saml/soap/secure/authorizationService.htm https://esg.prototype.ucar.edu/myopenid/testUser gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc Using CA Path: /etc/grid-security/certificates Using normalized Action of Read SOAP 1.1 fault: SOAP-ENV:Client [no subcode] "Connection refused" Detail: connect failed in tcp_connect() About to do soap call ...done (Error) Authz Decision Query failed for Openid https://esg.prototype.ucar.edu/myopenid/testUser This is normal since the code tries to contact a [ SamlAuthzService ](https://github.com/ESGF/esgf.github.io/wiki/SamlAuthzService) running on the localhost, port 8080. If you contact a properly running service, but enter a user's OpenID that is not valid, you will see an error like this: neillm@boiler:~/working/libglobus_adq$ LD_LIBRARY_PATH=/home/neillm/working/libglobus_adq ./libglobus_adq_client https://esg.prototype.ucar.edu/saml/soap/secure/authorizationService.htm https://esg.prototype.ucar.edu/myopenid/fakeOpenID gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc Using CA Path: /etc/grid-security/certificates Using normalized Action of Read About to do soap call ...done (Success) Response Status urn:oasis:names:tc:SAML:2.0:status:Success, ID 4a151af5-ce95-4b78-acb4-727d88fc4bb0, InResponseTo 140734742098736, IssueInstant 1294776208 Response type Assertion Assertion ID b6bba59c-a3b1-4538-9605-6534ad2d00a7, Version 2.0, IssueInstant 1294776208, AssertionType AuthzDecisionStatement AuthzDecisionStatement: Resource gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc, Action Read, Decision NOT PERMIT Authz Decision returned successfully for Openid https://esg.prototype.ucar.edu/myopenid/fakeOpenID Resource gsiftp://vetswebdev.ucar.edu:2811//datazone/narccap/DATA/MM5I/ncep/table2/vas_MM5I_ncep_2001010103.nc, Action Read, Decision Not Permitted Finally, if you contact a properly running service with a valid OpenID, but request access to a file that you do not have permission to read, you will see an error such as the following: neillm@boiler:~/working/libglobus_adq$ LD_LIBRARY_PATH=/home/neillm/working/libglobus_adq ./libglobus_adq_client https://esg.prototype.ucar.edu/saml/soap/secure/authorizationService.htm https://esg.prototype.ucar.edu/myopenid/testUser gsiftp://vetswebdev.ucar.edu:2811//FAKEFILE Using CA Path: /etc/grid-security/certificates Using normalized Action of Read About to do soap call ...done (Success) Response Status urn:oasis:names:tc:SAML:2.0:status:Success, ID aca36849-d3b7-4c75-9924-5374e2116615, InResponseTo 140736026785680, IssueInstant 1294776265 Response type Assertion Assertion ID 0e587f28-c32f-4c11-bf4b-0eafd709411b, Version 2.0, IssueInstant 1294776265, AssertionType AuthzDecisionStatement AuthzDecisionStatement: Resource gsiftp://vetswebdev.ucar.edu:2811//FAKEFILE, Action Read, Decision NOT PERMIT Authz Decision returned successfully for Openid https://esg.prototype.ucar.edu/myopenid/testUser Resource gsiftp://vetswebdev.ucar.edu:2811//FAKEFILE, Action Read, Decision Not Permitted ### Troubleshooting: Certificate verification failure This section addresses an error such as the following: SOAP 1.1 fault: SOAP-ENV:Client [no subcode] "SSL_ERROR_SSL error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed" Detail: SSL_connect error in tcp_connect() About to do soap call ...done (Error) Authz Decision Query failed for ... ### Method 1: Certificate verification resolution (Preferred) The preferred way to resolve this error is to set the X509_CERT_DIR environment variable to point to the directory location of where the certificates are stored. Or if that variable is already set, be sure that a copy of the remote machine's certificate is in that location. By default, the path of "/etc/grid-security/certificates" is used when no environment variable is used. If that is not a valid directory, the library also checks the standard OpenSSL CA Path (see Method 2 for that location). An example of setting the environment variable is either of the following: export X509_CERT_DIR=/path/to/certificates/ OR setenv X509_CERT_DIR /path/to/certificates ### Method 2: Certificate verification resolution To resolve this issue (connecting to an untrusted https server using SSL), we have to add the host certificate (or the certificate of the CA that signed the host certificate) to the standard location the the library checks for ca certificates. This location varies per distribution, and while there's some documentation on what that location might be, I'll present a sure-fire way for you to find it below. But first, here's the documentation on the location per distribution: * [ http://gagravarr.org/writing/openssl-certs/others.shtml#selfsigned-openssl ](http://gagravarr.org/writing/openssl-certs/others.shtml#selfsigned-openssl) Now, if you're just confused, or don't know what distribution you're running, or are not convinced that outdated documentation is correct, try the method below: neillm@boiler:~/working/libglobus_adq$ LD_LIBRARY_PATH=/home/neillm/working/libglobus_adq strace ./libglobus_adq_client > LOG 2>&1 neillm@boiler:~/working/libglobus_adq$ cat LOG | grep stat | grep ssl stat("/usr/lib/ssl/certs/f6442908.0", 0x7fff6377da90) = -1 ENOENT (No such file or directory) # if that command yields no output, try something like #cat LOG | grep stat | grep pki # OR #cat LOG | grep stat | grep tls Notice in the command line that I've inserted an "strace" command before running the libglobus_adq_client. This strace command shows all of the system calls that are made during the execution of the client. We first store them in a log above, then we grep it for the piece of information that we want. The last line of this shows the "certs" directory that is being checked is _ /usr/lib/ssl/certs/ _ and the certificate with the hash that it's looking for is _ f6442908.0 _ . Assuming you have access to that certificate (if not, contact the site administrator), copy that certificate into the /usr/lib/ssl/certs/ directory (or whatever it is on your system). Once complete, the command should work properly! ### Troubleshooting the libglobus_adq Build Process The most common problem that causes gSOAP compilation problems is a version mismatch of the code. For example, the libglobus_adq package may not be in sync with the gSOAP distribution that you have on your system. To remedy this, it's extremely important that the gSOAP code contained in the libglobus_adq directory match your version of gSOAP. So for example, you may need to copy stdsoap2.c into the libglobus_adq directory before the compile can complete. If you follow the instructions above, this will not be a problem.