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