wiki:WikiStart
Last modified 5 months ago Last modified on 10/27/16 19:56:55

Ipsilon - Identity Provider server and toolkit

Ipsilon is a server and a toolkit to configure Apache-based Service Providers. The server is a pluggable selfcontained mod_wsgi application that provides federated SSO to web applications. User authentication is always performed against a separate Identity Management system (for example a FreeIPA server), and communication with application is done using a federation protocol like SAML, OpenID, etc..

Code

The source code is available here: https://pagure.io/ipsilon.git/

We are using Pagure to handle reviews: https://pagure.io/ipsilon

For information on developing Ipsilon, see the Development page on our website.

Releases

Latest release: Version 2.0.0 Released on 2016-10-27. See details on the Releases page

Latest 1.2 release: Version 1.2.0 Released on 2016-05-02. See details on the Releases page

Latest 1.1 release: Version 1.1.1 Released on 2015-10-14. See details on the Releases page

Latest 1.0 release: Version 1.0.2 Released on 2015-10-14. See details on the Releases page


Diagram

https://fedorahosted.org/released/ipsilon/ipsilon-howto.svg




Mini HOWTO (from the README file in the code)

Ipsilon - Identity Provider

The Ipsilon project implements an Identity Provider[1] that is easy to use and configure. And it aims at providing installation scripts for applications that can use an Apache fronted to perform user authentication.

An IdP server allows users to authenticate against any identity provider whether that is a corporate LDAP server or even just local files or custom pluggable modules and allows applications to authenticate users while being completely agnostic of what authentication infrastructure is being used.

Applications can currently use the SAML2[2] protocol to talk to the Ipsilon identity provider, an application that uses SAML is called a Service Provider.

Ipsilon uses the LASSO[3] libraries an Python bindings to implement SAML support.

Ipsilon Server Installation

The Ipsilon server can be easily installed by simply running the 'ipsilon-server-install' command.

Prerequisites:

  • An Apache server with SSL configured
  • A keytab if Kerberos authentication is desired
  • An unprivileged user to run the Ipsilon code (defaults to 'ipsilon')

Currently there are only two available authentication modules, Kerberos and PAM. The Kerberos module uses mod_auth_gssapi (which it will configure for you at install time), the Pam module simply uses the PAM stack with a default service name set to 'remote'.

NOTE: The PAM module is invoked as an unprivileged user so if you are using the pam_unix plugin to authenticate users you'll find out that authentication does not work properly. Please use a different PAM module, like pam_sss, pam_ldap, etc..

Before you run the install script make sure to create an administrative user that can be authenticated either via PAM or Kerberos. The default name the installation script expects is 'admin' but that can be changed with the command line option named --admin-user

The hostname used is the system host name, if you can't set the system hostname to a fully qualified name, use the --hostname option to pass the desired fully qualified name for the IdP. It is important to use the correct name as this name is referenced and resolved by remote clients.

Other options are available by running ipsilon-server-install --help

To install a server that allow both GSSAPI (for Kerberos) and PAM authentication use:

$ ipsilon-server-install --gssapi=yes --pam=yes

This command will generate a default instance called 'idp' (you can change the default name using the --instance switch). Multiple instance can be installed in parallel, each wit a different name.

Instances are configured to be available at https://hostname/instance

So for a server called ipsilon.example.com, using the default installation options the IdP will be available at https://ipsilon.example.com/idp/

NOTE: If you are installing Ipsilon in a FreeIPA[4] environment you can use the --ipa switch to simplify the deployment. Using the --ipa switch will allow the use of your IPA Kerberos administrative credentials to automatically provision a keytab for the HTTP service if one is not available yet.

Once the script has successfully completed the installation, restart the Apache HTTPD server to activate it.

Use your 'admin' user to connect to the Web UI and perform additional administration tasks.

Ipsilon Clients configuration

Ipsilon clients can be quickly configured running the provided 'ipsilon-client-install' command.

Prerequisites:

  • An Apache server with SSL configured
  • The mod_mellon[5] authentication module for Apache
  • A previously installed SAML IdP server (like Ipsilon itself)

The default configuration for the client will install a configuration in Apache that will authenticate via the IdP any attempt to connect to the location named '/saml2protected', a test file is returned at that location.

In order to successfully install a client 2 steps are necessary:

  1. Prepare the client configuration and SAML metadata file.

To generate a valid metadata file and configuration it is necessary to provide the IdP metadata file to the installer, it is also useful to decide upfront where the application to be protected is located.

Let's assume the IdP is a standard install of the Ipsilon server on the server name ipsilon.example.com, and the client to be installed is called media.example.com with a wiki application located under /wiki

The following command will configure the server and generate the metadata file:

$ ipsilon-client-install \

--saml-idp-metadata http://ipsilon.example.com/idp/saml2/metadata \ --saml-auth /wiki

Use --help to explore all the possible options.

  1. Upload the generated metadata file to the IdP.

Once the script has successfully completed installation it will create a few files in /etc/httpd/saml2/hostname. There you will find a (self-signed) certificate and a private key used to authenticate with the IdP and 2 metadata files, one of which is called 'metadata.xml'

Log in with the 'admin' account to the Ipsilon server and go to:

Administration -> Identity Providers -> saml2 -> Manage

Click the 'Add New' button and add a new entry uploading or pasting the metadata.xml file just generated.

Once this is done, test that the authentication is working by going to the application server url: https://media.example.com/wiki The SP should redirect you to the IdP server, perform authentication, and then redirect you automatically back to the application server where you should find yourself authenticated.

NOTE: read mod_mellon's documentation to find out how to pass additional authorization data to the application. For simple authentication the application should expect a user have been authenticate if it finds a non empty 'REMOTE_USER' environment variable in the incoming requests.

ALSO NOTE: If your application is already SAML aware you can simply run the install script with the --saml-no-httpd option. This will generate the certificates and the metadata.xml file you need to provide to the application and the IdP in the current directory.

SAML 2.0 Conformance

Ipsilon 1.0 is targeting the Idp-Lite feature set as defined in the SAML 2.0 Conformance documentation. For more information on what is supported see SAML 2.0 Conformance.

[1] http://en.wikipedia.org/wiki/Identity_provider

[2] http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language

[3] http://lasso.entrouvert.org

[4] http://www.freeipa.org

[5] https://github.com/UNINETT/mod_auth_mellon