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 NOTE: If you are installing Ipsilon in a FreeIPA[4] environment you can use the
  66 --ipa switch to simplify the deployment. Using the --ipa switch will allow the
  67 use of your IPA Kerberos administrative credentials to automatically provision
  68 a keytab for the HTTP service if one is not available yet.
  69
  70 Once the script has successfully completed the installation, restart the Apache
  71 HTTPD server to activate it.
  72
  73 Use your 'admin' user to connect to the Web UI and perform additional
  74 administration tasks.
  75
  76
  77 Ipsilon Clients configuration
  78 =============================
  79
  80 Ipsilon clients can be quickly configured running the provided
  81 'ipsilon-client-install' command.
  82
  83 Prerequisites:
  84 - An Apache server with SSL configured
  85 - The mod_mellon[5] authentication module for Apache
  86 - A previously installed SAML IdP server (like Ipsilon itself)
  87
  88 The default configuration for the client will install a configuration in Apache
  89 that will authenticate via the IdP any attempt to connect to the location named
  90 '/saml2protected', a test file is returned at that location.
  91
  92 In order to successfully install a client 2 steps are necessary:
  93
  94 1. Prepare the client configuration and SAML metadata file.
  95
  96 To generate a valid metadata file and configuration it is necessary to provide
  97 the IdP metadata file  to the installer, it is also useful to decide upfront
  98 where the application to be protected is located.
  99
 100 Let's assume the IdP is a standard install of the Ipsilon server on the server
 101 name ipsilon.example.com, and the client to be installed is called
 102 media.exmple.com with a wiki application located under /wiki
 103
 104 The following command will configure the server and generate the metadata file:
 105
 106  $ ipsilon-client-install \
 107      --saml-idp-metadata http://ipsilon.example.com/idp/saml2/metadata \
 108      --saml-auth /wiki
 109
 110 Use --help to explore all the possible options.
 111
 112 2. Upload the generated metadata file to the IdP.
 113
 114 Once the script has successfully completed installation it will create a
 115 few files in /etc/httpd/saml2/`hostname`. There you will find a (self-signed)
 116 certificate and a private key used to authenticate with the IdP and 2 metadata
 117 files, one of which is called 'metadata.xml'
 118
 119 Log in with the 'admin' account to the Ipsilon server and go to:
 120  Administration -> Identity Providers -> saml2 -> Administer
 121 Click the 'Add New' button and add a new entry uploading the metadata.xml file
 122 just generated.
 123
 124 Once this is done, test that the authentication is working by going to the
 125 application server url: https://media.example.com/wiki
 126 The SP should redirect you to the IdP server, perform authentication, and then
 127 redirect you automatically back to the application server where you should find
 128 yourself authenticated.
 129
 130 NOTE: read modmellon's documentation to find out how to pass additional
 131 authorization data to the application. For simple authentication the application
 132 should expect a user have been authenticate if it finds a non empty 'REMOTE_USER'
 133 environment variable in the incoming requests.
 134
 135 ALSO NOTE: If your application is already SAML aware you can simply run the
 136 install script with the --saml-no-httpd option. This will generate the
 137 certificates and the metadata.xml file you need to provide to the application
 138 and the IdP in the current directory.
 139
 140 Links
 141 =====
 142
 143 [1] http://en.wikipedia.org/wiki/Identity_provider
 144 [2] http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language
 145 [3] http://lasso.entrouvert.org
 146 [4] http://www.freeipa.org
 147 [5] https://code.google.com/p/modmellon/