From 5fbd0275bf0263e0bfb384a51dbe144c90c9f57b Mon Sep 17 00:00:00 2001 From: Simo Sorce Date: Thu, 1 May 2014 20:50:17 -0400 Subject: [PATCH] Add README file with basic installation HOWTO The HowTo cover the simplest scenarios for both the Identiry and Service Provider applications. Signed-off-by: Simo Sorce --- README | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..78f8ee2 --- /dev/null +++ b/README @@ -0,0 +1,147 @@ + +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_kerb (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, used 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 Kerberos and PAM authentication use: + + $ ipsilon-server-install --krb=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.exmple.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. + +2. 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 -> Administer +Click the 'Add New' button and add a new entry uploading 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 modmellon'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. + +Links +===== + +[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://code.google.com/p/modmellon/ -- 2.20.1