Building Circles-of-Trust using ZXID

Sampo Kellomäki ( Identity Management toolkit implements standalone SAML 2.0 and Liberty ID-WSF 2.0 stacks. This document explains creating CoT.

1 Introduction

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.

1.1 Other documents

2 Metadata of Your Own Site

Others can obtain the metadata of your site by accessing a URL that is the entity ID of your site, for example:

If they want a file, you can capture the output of the http operation in a file, for example

  curl >mymeta.xml
  wget -O mymeta.xml

or just access the URL with web browser and save the page.

3 zxcot - tool

  Usage: zxcot [options] [dir]
       zxcot -a [options] [dir] <meta.xml
       curl | zxcot -a [options] [dir]
       zxcot -g [options] [dir]
       zxcot -p
  [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

4 Auto-CoT Feature and Well Known Location Method

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


5 Circle-of-Trust: Create a Federation with Other Partners

TBD - This chapter to be written

6 Certificates and PKI Trust

*** TBD - This chapter should be elaborated to be a certificate tutorial with following contents:

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 or FAQs for further information, including how to remove a password if you accidentally enabled it.

7 FAQ extract

See zxid-faq.pd for full story.

7.1.1 Quick command for looking at certificate

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.

7.1.2 Self signed certificate

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

  1. 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,

  2. 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.

8 License

Copyright (c) 2006-2009 Symlabs (, All Rights Reserved. Author: Sampo Kellomäki (

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

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.


SAML 1.1 Core, OASIS, 2003
"Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) V1.1", Oasis Standard, 2.9.2003, oasis-sstc-saml-bindings-1.1
Peted Davis, Ed., "Liberty Metadata Description and Discovery Specification", version 1.1, Liberty Alliance Project, 2004. (liberty-metadata-v1.1.pdf)
Conor Cahill et al.: "Liberty Alliance Web Services Framework: A Technical Overview", Liberty Alliance, 2008. File: idwsf-intro-v1.0.pdf (from\_center/papers)
Jonathan Tourzan and Yuzo Koga, eds.: "Liberty ID-WSF Web Services Framework Overview", Liberty Alliance, 2006. liberty-idwsf-overview-v2.0.pdf from\_center/specifications
"Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-core-2.0-os
"Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-profiles-2.0-os
"Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-bindings-2.0-os
"Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-authn-context-2.0-os
Cantor, Moreh, Phipott, Maler, eds., "Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-metadata-2.0-os
"Security and Privacy Considerations for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-sec-consider-2.0-os
"Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-conformance-2.0-os
Eric Tiffany, ed.: "SAML 2.0 Interoperability Testing Procedures, Version 2.0", Liberty Alliance, 7 July 2006. File: Liberty-SAMLv2.0-TestPlan-v2.0-Final.pdf
"Test Plan for Liberty Alliance SAML Test Event, Test Criteria SAML 2.0 Version 3.0 Errata F", Drummon Group Inc, 2007. File: Liberty\_DGI\_4Q07\_Interoperability\_SAML\_Test\_Criteria\_Test\_Plan\_vs.3.0.Errata.F.pdf
"Glossary for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-glossary-2.0-os
XML Canonicalization (non-exclusive),; J. Boyer: "Canonical XML Version 1.0", W3C Recommendation, 15.3.2001,, RFC3076
Exclusive XML Canonicalization,
Dick Hardt and Yaron Goland: "Simple Web Token (SWT)", Version, Microsoft, Nov. 4, 2009 (SWT-v0.9.5.1.pdf)
Allen Tom, et al.: "OAuth Web Resource Authorization Profiles (OAuth WRAP)", Version, Google, Microsoft, and Yahoo, Nov. 5, 2009 (WRAP-v0.9.7.2.pdf)
"XML Encryption Syntax and Processing", W3C Recommendation, 10.12.2002,
"XML-Signature Syntax and Processing", W3C Recommendation, 12.2.2002,, RFC3275
Cahill, ed.: "Liberty ID-WSF Discovery service 2.0", liberty-idwsf-disco-svc-2.0-errata-v1.0.pdf from\_center/
Liberty ID-WSF Discovery service 1.2 (liberty-idwsf-disco-svc-v1.2.pdf)
"Liberty ID-WSF People Service Specification", liberty-idwsf-people-service-1.0-errata-v1.0.pdf from\_center/specifications/
"Liberty ID-WSF 2.0 Security Mechanisms", liberty-idwsf-security-mechanisms-core-2.0-errata-v1.0.pdf from\_center/specifications
"Liberty ID-WSF Authentication, Single Sign-On, and Identity Mapping Services Specification", liberty-idwsf-authn-svc-2.0-errata-v1.0.pdf from\_center/specifications/
"Liberty ID-WSF SOAP Binding Specification", liberty-idwsf-soap-binding-2.0-errata-v1.0.pdf from\_center/specifications
Sampo Kellomäki and Jukka Kainulainen, eds.: "Liberty Data Services Template 2.1", Liberty Alliance, 2007. liberty-idwsf-dst-v2.1.pdf from\_center/specifications/
Sampo Kellomäki and Jukka Kainulainen, eds.: "Liberty DST v2.0", Liberty Alliance, 2006.
Liberty DST v1.1
Sampo Kellomäki, ed.: "Liberty Identity based Directory Access Protocol", Liberty Alliance, 2007.
Sampo Kellomäki, ed.: "Liberty Personal Profile specification", Liberty Alliance, 2003.
Liberty ID-WSF Interaction Service protocol 1.1
Liberty ID Federation Framework 1.2, Protocols and Schemas
Liberty Subscriptions and Notifications specification
Henry S. Thompson et al. (eds): XML Schema Part 1: Structures, 2nd Ed., WSC Recommendation, 28. Oct. 2004,
P. Deutcsh, J-L. Gailly: "ZLIB Compressed Data Format Specification version 3.3", Aladdin Enterprises, Info-ZIP, May 1996
P. Deutcsh: "DEFLATE Compressed Data Format Specification version 1.3", Aladdin Enterprises, May 1996
P. Deutcsh: "GZIP file format specification version 4.3", Aladdin Enterprises, May 1996
S. Josefsson, ed.: "The Base16, Base32, and Base64 Data Encodings", July 2003. (Section 4 describes Safebase64)
Microsoft Web Browser Federated Sign-On Protocol Specification, 20080207,