ZXID.org Identity Management toolkit implements standalone SAML 2.0 and Liberty ID-WSF 2.0 stacks. This document explains creating CoT.
ZXID, out of box, starts with default URL (Entity ID), metadata for couple of test servers, and demo certificates already configured. The Auto-CoT feature that automatically adds IdPs to the Circle-of-Trust is enabled.
These are good settings for a demo, but if you want to run any serious operation, you will need to address the certificates, trust, and admission of partners to the circle of trust yourself. You will also need to get others to add your site to their configuration.
When done for high value or liability services, all of this becomes rather serious business and you may want to hire a consultant to help getting it all right.
(One day I hope this documentation is so good that no consultant is needed. Right now this is just a place holder.)
If you are setting up zxididp, see zxid-idp.pd for more specific instructions.
mod_auth_saml Apache module documentation: SSO without programming.
zxid_simple() Easy API for SAML
ZXID Raw API: Program like the pros (and fix your own problems). See also Function Reference
ZXID ID-WSF API: Make Identity Web Services Calls using ID-WSF
ZXID Compilation and Installation: Compile and install from source or package. See also INSTALL.zxid for quick overview.
ZXID Configuration Reference: Nitty gritty on all options.
ZXID Circle of Trust Reference: How to set up the Circle of Trust, i.e. the partners your web site works with.
ZXID Logging Reference: ZXID digitally signed logging facility
javazxid: Using ZXID from Java
Net::SAML: Using ZXID from Perl
php_zxid: Using ZXID from PHP
zxididp: Using ZXID IdP and Discovery
README.smime: Crypto and Cert Tutorial
FAQ: Frequently Asked Questions
README.zxid: ZXID project overview
Others can obtain the metadata of your site by accessing a URL that is the entity ID of your site, for example:
https://sp1.zxid.org/zxidhlo?o=B
If they want a file, you can capture the output of the http operation in a file, for example
curl https://sp1.zxid.org/zxidhlo?o=B >mymeta.xml wget -O mymeta.xml https://sp1.zxid.org/zxidhlo?o=B
or just access the URL with web browser and save the page.
Usage: zxcot [options] [dir]
zxcot -a [options] [dir] <meta.xml
curl https://site.com/metadata.xml | zxcot -a [options] [dir]
zxcot -g https://site.com/metadata.xml [options] [dir]
zxcot -p https://site.com/metadata.xml
[dir] CoT directory. Default /var/zxid/cot
-a Add metadata from stdin
-g URL Do HTTP(S) GET to URL and add as metadata (if compiled w/libcurl)
-n Dryrun. Do not actually add the metadata. Instead print it to stdout.
-s Swap columns, for easier sorting by URL
-p ENTID Print sha1 name corresponding to an entity ID.
-v Verbose messages.
-q Be extra quiet.
-d Turn on debugging.
-h This help message
-- End of options
Automatic Circle-of-Trust (Auto-CoT) feature allows other parties metadata to be automatically fetched on the fly as needed. The fetch is made by using the entity ID of the other party as a URL. This is known as the Well Known Location (WKL) method, see [SAML2meta] section 4.1 "Publication and Resolution via Well-Known Location", p.29, for normative description of this method. Auto-CoT makes setting up the Circle-of-Trust very easy, but has its drawbacks: anyone can join, connectivity between entities is needed, and WKL method needs to be supported and enabled in the partner's server.
When ZXID ships, it has Auto-CoT enabled. To disable Auto-CoT, you need to set in your configuration string or file
MD_FETCH=0
TBD - This chapter to be written
*** TBD - This chapter should be elaborated to be a certificate tutorial with following contents:
Intro to certs and private keys
Generating self signed cert
Generating certificate signing request and using it to obtain commercially issued cert
Installing root certs so you can recognize other people's certs
Client TLS considerations
For the time being, the short answer is that ZXID uses OpenSSL and PEM format certificates. You can use same techniques as you would use for Apache / mod_ssl for acquiring certificates.
You should NEVER password protect your private key. There will not be any opportunity to supply the password. You should instead protect your private key using Unix filesystem permissions. See OpenSSL.org or modssl.org FAQs for further information, including how to remove a password if you accidentally enabled it.
See zxid-faq.pd for full story.
Sometimes you get warning messages (in browser) or signature validation errors (in IdP end) because the Subject field of the certificate does not match your actual domain name. You can check this with
openssl x509 -text </var/zxid/pem/ssl-nopw-cert.pem | grep Subject:
If the domain name is different, then you need to obtain a certificate with correct domain name, see next question.
ZXID ships with zxid.pem which gets by default copied to /var/zxid/pem under various different names. This is fine for testing, but disastrous for production or security sentitive use as the private key corresponding to zxid.pem certificate is of public knowledge (it is distributed with every copy of ZXID) - it offers no security and no non-repudiation what-so-ever.
For production or security sensitive install you need to either
Obtain certificates from an official certification authority, usually a commercial one. ZXID uses same certificate format as Apache (i.e. the pem format), so aquiring certificates is easi. Or,
Generate your own certificate. The simplest case is a self signed certificate:
openssl req -new -x509 -nodes -keyout pkey.pem -out cert.pem
cat cert.pem pkey.pem >/var/zxid/pem/ssl-nopw-cert.pem
The cat step is there because you need to supply both certificate and the private key in same file for ZXID to understand it.
Warning: Although ZXID wants to see the private key in the same file as the certificate, you MUST NOT give this concatenated file to any outsider. Others have legitimate need to know your certificate, but they MUST NOT know your private key. If they ask, you should take special care to delete the private key from the file prior to giving it to them. Often those who need to get your certificate, actually need your metadata: just tell them to fetch it from the Well Known Location URL (i.e. the Entity ID of your SP). ZXID will never leak the private key to the metadata.
Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved. Author: Sampo Kellomäki (sampo@iki.fi)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.