248 lines
6.5 KiB
Plaintext
248 lines
6.5 KiB
Plaintext
===========
|
|
IdPC Manual
|
|
===========
|
|
|
|
:Author: Frederic Peters
|
|
:Contact: fpeters@entrouvert.com
|
|
:date: $Date$
|
|
:revision: $Revision$
|
|
:copyright: Copyright © 2004 Entr'ouvert
|
|
|
|
.. contents:: Table of Contents
|
|
.. section-numbering::
|
|
|
|
Introduction
|
|
============
|
|
|
|
IdPC is an implementation of a `Liberty`_ Identity Provider in the form
|
|
of several CGI C programs.
|
|
|
|
It supports the following IDFF-1.2 profiles:
|
|
|
|
- Single Sign-On and Federation (Liberty Artifact and Liberty-Enabled Client
|
|
and Proxy)
|
|
- Single Logout (SOAP, initiated by SP)
|
|
- Federation Termination (SOAP, initiated by SP)
|
|
|
|
It will complete existing profiles and implement other core profiles in the
|
|
future.
|
|
|
|
IdPC can authenticate users through several means including HTTP authentication
|
|
and client certificates.
|
|
|
|
|
|
Download
|
|
========
|
|
|
|
IdPC releases can be downloaded from
|
|
http://labs.libre-entreprise.org/download/idpc/
|
|
|
|
Development code is available using CVS::
|
|
|
|
export CVSROOT=:pserver:anonymous@cvs.labs.libre-entreprise.org:/cvsroot/idpc
|
|
cvs login # press enter
|
|
cvs -z3 checkout idpc
|
|
|
|
|
|
.. _INSTALL:
|
|
.. include:: INSTALL
|
|
|
|
|
|
IdPC Configuration
|
|
==================
|
|
|
|
IdPC needs a configuration file to work; its location depends of compilation
|
|
options; IdPC will tell you the correct path if you call one of the CGI with
|
|
the ``--help`` argument::
|
|
|
|
$ /usr/lib/cgi-bin/idpc/soapEndpoint --help
|
|
This is IdPC; it is meant to be used as a CGI
|
|
|
|
Config file should be installed as:
|
|
/etc/idpc/config.xml
|
|
|
|
The configuration file must be a valid XML file and its root element should be
|
|
named "idpc" and placed in the following namespace
|
|
``http://www.entrouvert.org/namespaces/idpc``.
|
|
|
|
metadataFilePath:
|
|
path to the Liberty identity provider metadata file
|
|
|
|
idpPublicKey:
|
|
path to the IdP public key (PEM encoded)
|
|
|
|
idpPrivateKey:
|
|
path to the IdP private key (PEM encoded)
|
|
|
|
idpCertificate:
|
|
path to the IdP certificate (PEM encoded) (?)
|
|
|
|
serviceProvider:
|
|
element that should contains three other elements; metadataFilePath,
|
|
spPublicKey and spCaCertificate. You can of course have more than one
|
|
<serviceProvider> element.
|
|
|
|
authenticationMethod:
|
|
authentication method to use, detailed below
|
|
|
|
reauthenticationDelay:
|
|
The time at, or after which the service provider must reauthenticate
|
|
the user against the IdP. (in seconds) (default is 7200, 2 hours)
|
|
|
|
dbhost:
|
|
hostname where the IdPC database is installed (optional)
|
|
|
|
dbport:
|
|
port where the IdPC database is listening (optional)
|
|
|
|
dbname:
|
|
name of the IdPC database
|
|
|
|
dblogin:
|
|
login to connect to the IdPC database
|
|
|
|
dbpassword:
|
|
password to connect to the IdPC database
|
|
|
|
ocspCheck:
|
|
true to use OCSP to check certificates (default false)
|
|
|
|
ocspUrl:
|
|
URL to the OCSP service for certificate validation (optional)
|
|
(fallback if the user certificate doesn't have a proper authority info
|
|
access element)
|
|
|
|
ocspIssuer:
|
|
path to the OCSP issuer certificate (PEM encoded)
|
|
|
|
|
|
Authentication Methods
|
|
----------------------
|
|
|
|
HTTP authentication
|
|
```````````````````
|
|
|
|
Keyword: ``http``
|
|
|
|
HTTP authentication is handled by the web server; it should pass a REMOTE_USER
|
|
environment variable to the CGI. Apache allows many sources for HTTP
|
|
authentication including LDAP directory and PostgreSQL and MySQL databases.
|
|
|
|
The REMOTE_USER will be used as key to identify users in the database.
|
|
|
|
Certificate authentication
|
|
``````````````````````````
|
|
|
|
Keyword: ``certificate``
|
|
|
|
This authentication relies on Apache ``mod_ssl`` to set several environment
|
|
variables; your Apache configuration must contains a ``SSLVerifyClient``
|
|
option with ``optional`` or ``require`` as value.
|
|
|
|
The certificate serial will be used as key to identify users in the database.
|
|
|
|
.. note:: (this is subject to change)
|
|
|
|
Additionally if you have set ocspCheck to true in the configuration file, a
|
|
OCSP connection will be made to check for certificate validity.
|
|
|
|
|
|
Apache Configuration
|
|
====================
|
|
|
|
Imagine ``soapEndPoint`` has been installed in ``/usr/lib/cgi-bin/idpc/`` and
|
|
``singleSignOn`` (and other service URLs) in ``/usr/lib/cgi-bin/idpc/auth/``.
|
|
Apache CGI configuration will typically look as follow::
|
|
|
|
ScriptAlias /idpc/ /usr/lib/cgi-bin/idpc/
|
|
|
|
<Directory /usr/lib/cgi-bin/idpc/>
|
|
AllowOverride None
|
|
Options ExecCGI -MultiViews +SymLinksIfOwnerMatch
|
|
Order allow,deny
|
|
Allow from all
|
|
</Directory>
|
|
|
|
|
|
For HTTP authentication Apache must be configured to restrict access to the
|
|
service URLs (``singleSignOn``, ``singleLogout``, ``federationTermination``);
|
|
it may done as follow::
|
|
|
|
<Directory /usr/lib/cgi-bin/idpc/auth>
|
|
AuthType Basic
|
|
AuthName "IdPc"
|
|
AuthUserFile /etc/apache/passwd
|
|
Require valid-user
|
|
</Directory>
|
|
|
|
For X.509 certificate authentication Apache must be configured with the
|
|
following SSL options::
|
|
|
|
SSLOptions +ExportCertData
|
|
SSLOptions +StdEnvVars
|
|
SSLOptions +ExportCertData
|
|
|
|
Additionally it is necessary to cache SSL session for some versions of
|
|
Microsoft Internet Explorer; this is done through the SSLSessionCache
|
|
directive::
|
|
|
|
SSLSessionCache dbm:/var/log/apache/ssl-session-cache.dbm
|
|
SSLSessionCacheTimeout 600
|
|
|
|
See `mod_ssl FAQ <http://www.modssl.org/docs/2.8/ssl_faq.html#ToC49>`_ for
|
|
details on browser quirks.
|
|
|
|
|
|
Database configuration
|
|
======================
|
|
|
|
PostgreSQL
|
|
----------
|
|
|
|
.. include:: create-db.sql
|
|
|
|
Be sure it is possible to connect using TCP/IP to the database; somethink like
|
|
the next line will do (you may have to disable ``ident`` authentication first)::
|
|
|
|
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
|
|
host idpc idpc 127.0.0.1 255.255.255.255 password
|
|
|
|
|
|
MySQL
|
|
-----
|
|
|
|
.. note:: Support not yet implemented.
|
|
|
|
|
|
|
|
Liberty Metadata Files
|
|
======================
|
|
|
|
Liberty metadata files are XML files with details about protocols implemented
|
|
by the provider and their URLs. The exact URLs will depend upon the Apache
|
|
configuration but here is a mapping between metadata elements and script
|
|
names.
|
|
|
|
=============================== =======================
|
|
Metadata element Script name
|
|
=============================== =======================
|
|
SingleSignOnServiceURL singleSignOn
|
|
SingleLogoutServiceURL singleLogout
|
|
FederationTerminationServiceURL federationTermination
|
|
SoapEndpoint soapEndpoint
|
|
=============================== =======================
|
|
|
|
|
|
|
|
Copyright and License
|
|
=====================
|
|
|
|
IdPC (both code and documentation) is copyright © 2004 Entr'ouvert and released
|
|
under the `GNU General Public License`_.
|
|
|
|
|
|
|
|
.. _Liberty: http://www.projectliberty.org
|
|
.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html
|
|
|