README

   1
   2 Ipsilon - Identity Provider
   3 ===========================
   4
   5 The Ipsilon project implements an Identity Provider[1] that is easy to use and
   6 configure. And it aims at providing installation scripts for applications
   7 that can use an Apache fronted to perform user authentication.
   8
   9 An IdP server allows users to authenticate against any identity provider
  10 whether that is a corporate LDAP server or even just local files or custom
  11 pluggable modules and allows applications to authenticate users while being
  12 completely agnostic of what authentication infrastructure is being used.
  13
  14 Applications can currently use the SAML2[2] protocol to talk to the Ipsilon
  15 identity provider, an application that uses SAML is called a Service Provider.
  16
  17 Ipsilon uses the LASSO[3] libraries an Python bindings to implement SAML support.
  18
  19 Ipsilon Server Installation
  20 ===========================
  21
  22 The Ipsilon server can be easily installed by simply running the
  23 'ipsilon-server-install' command.
  24
  25 Prerequisites:
  26 - An Apache server with SSL configured
  27 - A keytab if Kerberos authentication is desired
  28 - An unprivileged user to run the Ipsilon code (defaults to 'ipsilon')
  29
  30 Currently there are only two available authentication modules, Kerberos and
  31 PAM. The Kerberos module uses mod_auth_kerb (which it will configure for you at
  32 install time), the Pam module simply uses the PAM stack with a default service
  33 name set to 'remote'.
  34
  35 NOTE: The PAM module is invoked as an unprivileged user so if you are using the
  36 pam_unix plugin to authenticate users you'll find out that authentication does
  37 not work properly. Please use a different PAM module, like pam_sss, pam_ldap,
  38 etc..
  39
  40 Before you run the install script make sure to create an administrative user
  41 that can be authenticated either via PAM or Kerberos. The default name the
  42 installation script expects is 'admin' but that can be changed with the command
  43 line option named --admin-user
  44
  45 The hostname used is the system host name, if you can't set the system hostname
  46 to a fully qualified name, used the --hostname option to pass the desired fully
  47 qualified name for the IdP. It is important to use the correct name as this
  48 name is referenced and resolved by remote clients.
  49
  50 Other options are available by running ipsilon-server-install --help
  51
  52 To install a server that allow both Kerberos and PAM authentication use:
  53
  54  $ ipsilon-server-install --krb=yes --pam=yes
  55
  56 This command will generate a default instance called 'idp' (you can change the
  57 default name using the --instance switch). Multiple instance can be installed
  58 in parallel, each wit a different name.
  59
  60 Instances are configured to be available at https://hostname/instance
  61
  62 So for a server called ipsilon.example.com, using the default installation
  63 options the IdP will be available at https://ipsilon.example.com/idp/
  64
  65 The install script expects to find the keytab in /etc/httpd/conf/http.keytab
  66
  67 NOTE: If you are installing Ipsilon in a FreeIPA[4] environment you can use the
  68 --ipa switch to simplify the deployment. Using the --ipa switch will allow the
  69 use of your IPA Kerberos administrative credentials to automatically provision
  70 a keytab for the HTTP service if one is not available yet.
  71
  72 Once the script has successfully completed the installation, restart the Apache
  73 HTTPD server to activate it.
  74
  75 Use your 'admin' user to connect to the Web UI and perform additional
  76 administration tasks.
  77
  78
  79 Ipsilon Clients configuration
  80 =============================
  81
  82 Ipsilon clients can be quickly configured running the provided
  83 'ipsilon-client-install' command.
  84
  85 Prerequisites:
  86 - An Apache server with SSL configured
  87 - The mod_mellon[5] authentication module for Apache
  88 - A previously installed SAML IdP server (like Ipsilon itself)
  89
  90 The default configuration for the client will install a configuration in Apache
  91 that will authenticate via the IdP any attempt to connect to the location named
  92 '/saml2protected', a test file is returned at that location.
  93
  94 In order to successfully install a client 2 steps are necessary:
  95
  96 1. Prepare the client configuration and SAML metadata file.
  97
  98 To generate a valid metadata file and configuration it is necessary to provide
  99 the IdP metadata file  to the installer, it is also useful to decide upfront
 100 where the application to be protected is located.
 101
 102 Let's assume the IdP is a standard install of the Ipsilon server on the server
 103 name ipsilon.example.com, and the client to be installed is called
 104 media.exmple.com with a wiki application located under /wiki
 105
 106 The following command will configure the server and generate the metadata file:
 107
 108  $ ipsilon-client-install \
 109      --saml-idp-metadata http://ipsilon.example.com/idp/saml2/metadata \
 110      --saml-auth /wiki
 111
 112 Use --help to explore all the possible options.
 113
 114 2. Upload the generated metadata file to the IdP.
 115
 116 Once the script has successfully completed installation it will create a
 117 few files in /etc/httpd/saml2/`hostname`. There you will find a (self-signed)
 118 certificate and a private key used to authenticate with the IdP and 2 metadata
 119 files, one of which is called 'metadata.xml'
 120
 121 Log in with the 'admin' account to the Ipsilon server and go to:
 122  Administration -> Identity Providers -> saml2 -> Administer
 123 Click the 'Add New' button and add a new entry uploading the metadata.xml file
 124 just generated.
 125
 126 Once this is done, test that the authentication is working by going to the
 127 application server url: https://media.example.com/wiki
 128 The SP should redirect you to the IdP server, perform authentication, and then
 129 redirect you automatically back to the application server where you should find
 130 yourself authenticated.
 131
 132 NOTE: read modmellon's documentation to find out how to pass additional
 133 authorization data to the application. For simple authentication the application
 134 should expect a user have been authenticate if it finds a non empty 'REMOTE_USER'
 135 environment variable in the incoming requests.
 136
 137 ALSO NOTE: If your application is already SAML aware you can simply run the
 138 install script with the --saml-no-httpd option. This will generate the
 139 certificates and the metadata.xml file you need to provide to the application
 140 and the IdP in the current directory.
 141
 142 Links
 143 =====
 144
 145 [1] http://en.wikipedia.org/wiki/Identity_provider
 146 [2] http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language
 147 [3] http://lasso.entrouvert.org
 148 [4] http://www.freeipa.org
 149 [5] https://code.google.com/p/modmellon/