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