============================================ 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:///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:: 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" 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:: AuthType "Mellon" MellonEnable "auth" 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 `` ``. 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:: ?ReturnTo= 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