--- /dev/null
+============================================
+Ipsilon - Web Application Integration (SAML)
+============================================
+
+Ipsilon allows web applications to consume users from existing identity
+management systems, even those that it doesn't have direct access to.
+
+Traditionally, web applications have their own user database, or they directly
+interact with a centralized identity management system such as an LDAP server.
+Both of these approaches put a lot of responsibility on the web application
+itself. Let's consider some of the issues around these two approaches.
+
+Local user database:
+
+* User management interfaces need to be developed.
+* User accounts are local to the application, leading to users having
+ different passwords for different applications.
+* Authentication is often password based, which is not ideal from a security
+ perspective.
+* Scalability and replication of the database become the responsibility of the
+ web application developers.
+
+LDAP server:
+
+* Users and credentials are centralized, but we don't get true single sign-on.
+* Authentication is often password based, which is not ideal from a security
+ perspective.
+* The web application has to be able to handle the wide variety of LDAP schema
+ that deployers may have in their environments.
+* The web application needs direct access to the LDAP server.
+
+When using Ipsilon for SAML federation, an application is relieved of the above
+burdens. Ipsilon deals with all of the authentication and lookup of user
+information from the centralized identity source.
+
+This document describes the recommended practices for integrating a web
+application with Ipsilon to allow for SAML federated single sign-on.
+
+
+Federated Single Sign-On Concepts
+=================================
+
+Before getting into the concepts of SAML federated single sign-on, it is
+important to understand some basic terminology:
+
+Identity Provider (IDP)
+ A SAML Identity Provider is responsible for authenticating users on behalf of
+ other web applications. The IDP then provides information about
+ authenticated users to web applications in the form of assertions. Ipsilon
+ is a SAML IDP.
+
+Service Provider (SP)
+ A SAML Service Provider is a web application that is using an IDP to provide
+ authentication service and user information.
+
+Assertion
+ An assertion is some property about a user that the IDP claims is true. A
+ collection assertions represent a user object, which a web application can
+ then use for identification and authorization purposes.
+
+Single Sign-On (SSO)
+ Single Sign-On allows a user to authenticate once within some period of time,
+ and then access multiple applications without having to authenticate again.
+
+Federated single sign-on (SSO) allows a web application to use identities
+from an external identity source that it does not manage, while also having
+the benefit of true SSO.
+
+Most organizations already have some form of centralized identity management,
+such as an LDAP server. Having separate identity silos per application is a
+frustrating user experience. Tying a web application directly into a
+centralized identity management system is a burden on the web application
+developer for the reasons previously mentioned in this document. SAML
+federation allows a web application to be presented with data representing
+an authenticated user when that user accesses the application. This data is
+crytographically proven to be from a trusted source, and is provided in an
+easy to consume form. This data can be used by the web application without the
+need for the web application to reach out to a central identity management
+system. The web application does not need to know how the user authenticated,
+or even where the user information is stored. This removes a lot of complexity
+from the web application itself.
+
+In some cases, the identity management system might not even be accessible by
+the web application. Consider a company that provides a web application as a
+paid-for service. Instead of requiring customers to create users within a
+database for the web application, the web application can be configured to
+trust a customer's IDP. The web application never needs to communicate
+directly with the IDP or the underlying identity management system, which are
+likely behind the customer's firewall.
+
+Authentication Flow
+-------------------
+
+The following picture depicts the authentication flow that occurs when using
+SAML::
+
+ +---------------+ +---------------+
+ | | | |
+ | Application | | Ipsilon |
+ | (SP) | | (IDP) |
+ | | | |
+ +--^----+----^--+ +----^-----+----+
+ | | | | |
+ (1) (2) (5) (3) (4)
+ | | | | |
+ +--+----v----+--------------+-----v----+
+ | |
+ | Web Browser |
+ | |
+ +--------------------------------------+
+
+The steps in the authentication flow are:
+
+ 1. A user accesses a protected URL of the web application via browser.
+
+ 2. The web application returns a redirect to the user, pointing them to the
+ IDP.
+
+ 3. The browser follows the redirect to the IDP, where the user is asked to
+ authenticate.
+
+ 4. Upon successful authentication, the IDP returns a SAML response as a
+ part of a form that is set to submit when loaded.
+
+ 5. The browser automatically sumbits the returned form, which does a POST
+ of the SAML response to the web application.
+
+At the end of the authentication flow, the assertion values contained in the
+SAML response are mapped into environment variables by an Apache httpd module
+on the SP. These environment variables are made available to the web
+application, where they can be used for user identification, authorization, or
+any other purpose that the web application may have.
+
+The nice thing from the web application developers viewpoint is that none of
+the above steps are the responsibility of the web application itself. All of
+the work is performed by the browser, an Apache httpd module on the SP, and
+the Ipsilon IDP. The web application only needs to deal with the environment
+variable data that is provided to it.
+
+
+Web Application Integration
+===========================
+
+In order for a web application to use Ipsilon for federated SSO, there are a
+few things that need to be done. Its webserver needs to be configured as a
+SP, and the web application needs to be able to handle the user data that is
+provided to it from the SAML assertions.
+
+Service Provider Configuration
+------------------------------
+
+Configuring a web application's webserver as a SP is comprised of a few steps:
+
+* SP key, certificate, and metadata generation
+* IDP metadata retrieval
+* SP registration
+* httpd configuration
+
+A number of the above steps are handled for you by the
+``ipsilon-client-install`` utility. We will still describe the steps here to
+provide a thorough understanding of each step, but it is recommended to use the
+ipsilon-client-install utility to simplify the configuration procedure.
+
+SAML relies on trusted responses that are sent between the IDP and the SP via
+the user's browser. These responses are cryptographically authenticated and
+even have the capability to be encrypted. This requires key and certificate
+generation, and an establishment of trust on both the IDP and the SP. In
+addition to certificate trust, some additional information needs to be
+exchanged between the IDP and SP so that each side knows how to communicate
+with each other from a SAML perspective. This information takes the form of an
+XML metadata file, and both the IDP and SP need to exchange their metadata
+when a SP is being configured.
+
+Using ``ipsilon-client-install`` will generate a key, certificate, and SP
+metadata. If Ipsilon admin user credentials are supplied, it will also send
+the SP metadata to Ipsilon to register it as a trusted SP.
+
+The ``ipsilon-client-install`` utility also has the ability to create a basic
+Apache httpd configuration, but that is typically only useful for a very basic
+new site or experimentation. For existing web applications, one should tell
+``ipsilon-client-install`` to skip the httpd configuration and the
+configuration should be performed manually.
+
+Here is a basic example of using ``ipsilon-client-install`` to set up a SP::
+
+ ipsilon-client-install --saml-idp-url https://ipsilon.example.test/idp \
+ --saml-sp-name mysite --saml-auth /sp \
+ --saml-no-httpd
+
+In this example, we are providing a pointer to our Ipsilon IDP, providing a
+name for our SP to be used during registration, and specifying the URI where we
+want to require SAML authentication (``/sp``). We are also skipping the httpd
+configuration since we will be doing that manually.
+
+If you use a non-standard port for your web application, of if the hostname
+that is used to access your web application is not the FQDN, you will need
+to use the ``--hostname`` and ``--port`` options to ensure that the URLs are
+correct in the generated metadata. Note that ``ipsilon-client-install``
+currently enforces that https is being used in the URLs it generates.
+
+There are a few other options which may or may not be needed depending on the
+exact URIs that you want to use for SAML communication. The following are the
+URIs that ``ipsilon-client-install`` will set in the SP metadata:
+
+base
+ This is the URI where SAML assertion data will be made available to the web
+ application if it is present. The default is ``/``, but it can be set with the
+ ``--saml-base`` option.
+
+auth
+ This is the URI where SAML authentication is required. This URI must be
+ beneath the base URI. Accessing this URI will trigger the authentication
+ flow described above. The browser will then return to this URI upon
+ successful authentication. This should typically be set to the "Log In" URI
+ of your web application. It defaults to ``/saml2protected``, but it can be
+ set with the ``--saml-auth`` option.
+
+endpoint
+ This is the URI where SAML communication will occur. This URI must be
+ beneath the base URI. This is not an actual URI within your web
+ application, as the httpd module will be handling communication for this URI.
+ The default is ``/saml2``, but it can be set with the ``--saml-sp`` option.
+
+logout
+ This is the URI where SAML logout will be triggered. This URI must be
+ beneath the endpoint URI. This is not an actual URI within your web
+ application, as the httpd module will be handling communication for this URI.
+ The default is ``/saml2/logout``, but it can be set with the
+ ``--saml-sp-logout`` option. More detail about how the logout URI is used
+ are provided in the `Logout Handling`_ section below.
+
+post
+ This is the URI where SAML responses from the IDP will be posted. This URI
+ must be beneath the endpoint URI. This is not an actual URI within your web
+ application, as the httpd module will be handling communication for this URI.
+ The default is ``/saml2/postResponse``, but if can be set with the
+ ``--saml-sp-post`` option.
+
+You will typically only need to specify the auth URI option above, unless you
+have a reason to change the base URI (which will affect all of the other URIs
+since they all must be beneath the base).
+
+You can download the IDP metadata from Ipsilon. Assuming that the IDP name of
+Ipsilon is the default of ``idp``, the metadata can be accessed at::
+
+ ``https://<ipsilon FQDN>/idp/saml2/metadata``
+
+You will need to save this metadata for configuring httpd in the next step.
+
+Apache HTTPD Config
+-------------------
+
+The handling of SAML in httpd is taken care of by the `mod_auth_mellon`_
+module. The first step in ensuring that you are loading the mod_auth_mellon
+library. This will look something like this::
+
+ LoadModule auth_mellon_module /usr/lib64/httpd/modules/mod_auth_mellon.so
+
+You will need to ensure that the ``Location`` directive that matches the base
+URI we specified during metadata creation contains the proper Mellon
+directives. This ``Location`` directive is where we specify the key and
+certificate that the SP is using, the trusted IDP metadata, and the endpoint
+URI to use for SAML communication. Here is an example of the base URI
+``Location`` directive::
+
+ <Location />
+ MellonEnable "info"
+ MellonSPPrivateKeyFile /etc/httpd/saml2/mysite/certificate.key
+ MellonSPCertFile /etc/httpd/saml2/mysite/certificate.pem
+ MellonSPMetadataFile /etc/httpd/saml2/mysite/metadata.xml
+ MellonIdPMetadataFile /etc/httpd/saml2/mysite/idp-metadata.xml
+ MellonEndpointPath /saml2
+ MellonIdP "IDP"
+ </Location>
+
+The ``MellonEnable`` directive with a value of ``info`` means that assertion
+data will be made available to the web application at this location if it is
+present. If a user has not authenticated via SAML, they will be allowed into
+your site, but no assertion data will be present to provide. Typically, this
+location will encompass your entire web application and you will have an
+additional protected location at your "Log In" URI that triggers the
+authentication flow.
+
+The ``MellonSP*`` directives tell mod_auth_mellon about the SP that it is
+representing. These directives point to the key, certificate, and metadata
+that was generated by ``ipsilon-client-install``.
+
+The ``MellonIdPMetadataFile`` directive points to the IDP metadata that you
+downloaded from the IDP. The IDP metadata contains the certificate of the IDP,
+so it is used to validate the signature of the responses that come from the
+IDP. In effect, this is how the trust of the IDP is configured for your SP.
+The IDP metadata also contains the URL of the IDP, which is used when
+redirecting users to the IDP to perform authentication.
+
+The ``MellonEndpointPath`` directive must match the endpoint URI that was used
+when generating the metadata with ``ipsilon-client-install``.
+
+The ``MellonIdP`` directive is used to expose an IDP identifier to your web
+application via an environment variable. The value of this directive is used
+to indicate the name of the environment variable.
+
+You also need to configure your auth URI to require authentication via
+mod_auth_mellon. This is done by adding the ``AuthType`` and ``MellonEnable``
+directives within the ``Location`` directive that matches your auth URI. Here
+is an example of the auth URI ``Location`` directive::
+
+ <Location /sp>
+ AuthType "Mellon"
+ MellonEnable "auth"
+ </Location>
+
+With these changes, you should be able to access your auth URI, which will
+trigger the authentication flow that was previously described. The browser
+will be returned to the auth URI, and values contained in the SAML assertion
+will be exposed to your web application as environment variables. To do
+anything useful, your application will have to know how to consume this
+assertion data.
+
+Consuming Assertion Data
+------------------------
+A web application will typically need changes to allow it to make use of the
+environment variables that are provided by mod_auth_mellon. Making these
+changes even has value outside of Ipsilon, as it allows your web application to
+support external authentication and user info as described in the
+`Web App Authentication`_ page on the FreeIPA wiki. It will ultimately make
+your web application more flexible as new authentication and federation methods
+emerge.
+
+The provided environment variables fall into two main categories. A user
+identifier, and other information about the user.
+
+If your web application only needs to know who the user is and nothing else
+about the user, it's quite possible that no changes are needed in your
+application. This is because the user identifier is provided as the
+``REMOTE_USER`` environment variable, which is commonly used by other httpd
+authentication modules.
+
+Quite often, the ``REMOTE_USER`` environment variable isn't enough. It is
+common for a web application to want more information about a user, such as
+their e-mail address, their full name, and the groups that they are a member
+of. Depending on how the Ipsilon IDP is configured, all of this information
+can be provided to a SP in the SAML assertions. This of course assumes that
+the underlying identity management system that Ipsilon is using has the
+information that you need.
+
+Every assertion that is contained in the SAML response is provided to your web
+application by mod_auth_mellon. The environment variables that expose these
+values are prefixed by `MELLON_`, followed by the name of the assertion. These
+names are defined by the IDP configuration. Your application is not forced to
+use a specific set of environment variable names however. You can configure
+mod_auth_mellon to map the SAML assertions to different environment variable
+names. This is done by using the ``MellonSetEnv`` and ``MellonSetEnvNoPrefix``
+directives in the ``Location`` directive for your base URI. Consider the
+following examples::
+
+ MellonSetEnv "email" "mail"
+ MellonSetEnvNoPrefix "DISPLAY_NAME" "displayName"
+
+Both of these directives take the form ``<directive> <local name> <IDP name>``.
+In the case of the above example, a ``mail`` attribute in the SAML assertion
+would be expressed as the ``MELLON_email`` environment variable. The
+``MellonSetEnvNoPrefix`` directive works the same way, but it does not use the
+``MELLON_`` prefix. In this case, a ``displayName`` attribute in the SAML
+assertion would be expressed as the ``DISPLAY_NAME`` environment variable.
+There are some good recommendations on some common environment variables that
+should be used for web application authentication in general on the FreeIPA
+wiki's `Web App Authentication`_ page.
+
+For the purposes of authorization within a web application, it is recommended
+to take advantage of group membership information that is provided in the SAML
+assertions. For instance, if your web application has a concept of an
+``user`` role, it can allow that role to be assigned to a group that is
+defined in the identity management system that is used by the IDP. This
+allows for application access to be controlled by group assignment centrally
+in the identity management system. It is of course possible to assign the
+web application roles directly to a user as well if the groups don't map
+cleanly to the authorization grouping within your application. Still, it is
+best to try to keep user and group management out of the web application as
+much as possible.
+
+It is not uncommon for a web application to have a need to store information
+about a user that will not be provided by an IDP or even by any identity
+management system. One of the most common cases of this is storing user
+preferences that are specific to the web application. The recommended way of
+handling this is to have the web application create a record for this data in
+it's own backend database when it first sees a new user. It can associate this
+data with a user identitfier from the assertion, such as ``REMOTE_USER`` or
+some combination of assertion values that is guaranteed to be unique. The
+important thing is that none of the other user data from the assertion should
+be duplicated in the web application's backend database.
+
+Logout Handling
+---------------
+Changes may also be needed to the web application to allow logout to work
+properly. When a user succesfully authenticates and accesses a SP that uses
+mod_auth_mellon, a cookie is set in the user's browser to represent their
+session. In order to terminate this session when the user logs out of the
+web application, you have to make sure that your web application will send the
+user to the logout URI that was defined when the SP metadata was generated. In
+addition, a required ``ReturnTo`` query parameter must be specified, which
+tells mod_auth_mellon where to send the user after completing the logout
+operation. The format of this looks like::
+
+ <logout URI>?ReturnTo=<url to redirect to after logout>
+
+Typically, your application will either redirect or provide a direct link to
+the logout URI.
+
+
+References
+==========
+.. target-notes::
+
+.. _mod_auth_mellon: https://github.com/UNINETT/mod_auth_mellon/wiki
+.. _Web App Authentication: http://www.freeipa.org/page/Web_App_Authentication
projects / cascardo / ipsilon.git / commitdiff