diff options
| -rw-r--r-- | doc/saml-integration.rst | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/doc/saml-integration.rst b/doc/saml-integration.rst new file mode 100644 index 0000000..ec3404d --- /dev/null +++ b/doc/saml-integration.rst @@ -0,0 +1,415 @@ +============================================ +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 |