1 ============================================
2 Ipsilon - Web Application Integration (SAML)
3 ============================================
5 Ipsilon allows web applications to consume users from existing identity
6 management systems, even those that it doesn't have direct access to.
8 Traditionally, web applications have their own user database, or they directly
9 interact with a centralized identity management system such as an LDAP server.
10 Both of these approaches put a lot of responsibility on the web application
11 itself. Let's consider some of the issues around these two approaches.
15 * User management interfaces need to be developed.
16 * User accounts are local to the application, leading to users having
17 different passwords for different applications.
18 * Authentication is often password based, which is not ideal from a security
20 * Scalability and replication of the database become the responsibility of the
21 web application developers.
25 * Users and credentials are centralized, but we don't get true single sign-on.
26 * Authentication is often password based, which is not ideal from a security
28 * The web application has to be able to handle the wide variety of LDAP schema
29 that deployers may have in their environments.
30 * The web application needs direct access to the LDAP server.
32 When using Ipsilon for SAML federation, an application is relieved of the above
33 burdens. Ipsilon deals with all of the authentication and lookup of user
34 information from the centralized identity source.
36 This document describes the recommended practices for integrating a web
37 application with Ipsilon to allow for SAML federated single sign-on.
40 Federated Single Sign-On Concepts
41 =================================
43 Before getting into the concepts of SAML federated single sign-on, it is
44 important to understand some basic terminology:
46 Identity Provider (IDP)
47 A SAML Identity Provider is responsible for authenticating users on behalf of
48 other web applications. The IDP then provides information about
49 authenticated users to web applications in the form of assertions. Ipsilon
53 A SAML Service Provider is a web application that is using an IDP to provide
54 authentication service and user information.
57 An assertion is some property about a user that the IDP claims is true. A
58 collection assertions represent a user object, which a web application can
59 then use for identification and authorization purposes.
62 Single Sign-On allows a user to authenticate once within some period of time,
63 and then access multiple applications without having to authenticate again.
65 Federated single sign-on (SSO) allows a web application to use identities
66 from an external identity source that it does not manage, while also having
67 the benefit of true SSO.
69 Most organizations already have some form of centralized identity management,
70 such as an LDAP server. Having separate identity silos per application is a
71 frustrating user experience. Tying a web application directly into a
72 centralized identity management system is a burden on the web application
73 developer for the reasons previously mentioned in this document. SAML
74 federation allows a web application to be presented with data representing
75 an authenticated user when that user accesses the application. This data is
76 crytographically proven to be from a trusted source, and is provided in an
77 easy to consume form. This data can be used by the web application without the
78 need for the web application to reach out to a central identity management
79 system. The web application does not need to know how the user authenticated,
80 or even where the user information is stored. This removes a lot of complexity
81 from the web application itself.
83 In some cases, the identity management system might not even be accessible by
84 the web application. Consider a company that provides a web application as a
85 paid-for service. Instead of requiring customers to create users within a
86 database for the web application, the web application can be configured to
87 trust a customer's IDP. The web application never needs to communicate
88 directly with the IDP or the underlying identity management system, which are
89 likely behind the customer's firewall.
94 The following picture depicts the authentication flow that occurs when using
97 +---------------+ +---------------+
99 | Application | | Ipsilon |
102 +--^----+----^--+ +----^-----+----+
106 +--+----v----+--------------+-----v----+
110 +--------------------------------------+
112 The steps in the authentication flow are:
114 1. A user accesses a protected URL of the web application via browser.
116 2. The web application returns a redirect to the user, pointing them to the
119 3. The browser follows the redirect to the IDP, where the user is asked to
122 4. Upon successful authentication, the IDP returns a SAML response as a
123 part of a form that is set to submit when loaded.
125 5. The browser automatically sumbits the returned form, which does a POST
126 of the SAML response to the web application.
128 At the end of the authentication flow, the assertion values contained in the
129 SAML response are mapped into environment variables by an Apache httpd module
130 on the SP. These environment variables are made available to the web
131 application, where they can be used for user identification, authorization, or
132 any other purpose that the web application may have.
134 The nice thing from the web application developers viewpoint is that none of
135 the above steps are the responsibility of the web application itself. All of
136 the work is performed by the browser, an Apache httpd module on the SP, and
137 the Ipsilon IDP. The web application only needs to deal with the environment
138 variable data that is provided to it.
141 Web Application Integration
142 ===========================
144 In order for a web application to use Ipsilon for federated SSO, there are a
145 few things that need to be done. Its webserver needs to be configured as a
146 SP, and the web application needs to be able to handle the user data that is
147 provided to it from the SAML assertions.
149 Service Provider Configuration
150 ------------------------------
152 Configuring a web application's webserver as a SP is comprised of a few steps:
154 * SP key, certificate, and metadata generation
155 * IDP metadata retrieval
157 * httpd configuration
159 A number of the above steps are handled for you by the
160 ``ipsilon-client-install`` utility. We will still describe the steps here to
161 provide a thorough understanding of each step, but it is recommended to use the
162 ipsilon-client-install utility to simplify the configuration procedure.
164 SAML relies on trusted responses that are sent between the IDP and the SP via
165 the user's browser. These responses are cryptographically authenticated and
166 even have the capability to be encrypted. This requires key and certificate
167 generation, and an establishment of trust on both the IDP and the SP. In
168 addition to certificate trust, some additional information needs to be
169 exchanged between the IDP and SP so that each side knows how to communicate
170 with each other from a SAML perspective. This information takes the form of an
171 XML metadata file, and both the IDP and SP need to exchange their metadata
172 when a SP is being configured.
174 Using ``ipsilon-client-install`` will generate a key, certificate, and SP
175 metadata. If Ipsilon admin user credentials are supplied, it will also send
176 the SP metadata to Ipsilon to register it as a trusted SP.
178 The ``ipsilon-client-install`` utility also has the ability to create a basic
179 Apache httpd configuration, but that is typically only useful for a very basic
180 new site or experimentation. For existing web applications, one should tell
181 ``ipsilon-client-install`` to skip the httpd configuration and the
182 configuration should be performed manually.
184 Here is a basic example of using ``ipsilon-client-install`` to set up a SP::
186 ipsilon-client-install --saml-idp-url https://ipsilon.example.test/idp \
187 --saml-sp-name mysite --saml-auth /sp \
190 In this example, we are providing a pointer to our Ipsilon IDP, providing a
191 name for our SP to be used during registration, and specifying the URI where we
192 want to require SAML authentication (``/sp``). We are also skipping the httpd
193 configuration since we will be doing that manually.
195 If you use a non-standard port for your web application, of if the hostname
196 that is used to access your web application is not the FQDN, you will need
197 to use the ``--hostname`` and ``--port`` options to ensure that the URLs are
198 correct in the generated metadata. Note that ``ipsilon-client-install``
199 currently enforces that https is being used in the URLs it generates.
201 There are a few other options which may or may not be needed depending on the
202 exact URIs that you want to use for SAML communication. The following are the
203 URIs that ``ipsilon-client-install`` will set in the SP metadata:
206 This is the URI where SAML assertion data will be made available to the web
207 application if it is present. The default is ``/``, but it can be set with the
208 ``--saml-base`` option.
211 This is the URI where SAML authentication is required. This URI must be
212 beneath the base URI. Accessing this URI will trigger the authentication
213 flow described above. The browser will then return to this URI upon
214 successful authentication. This should typically be set to the "Log In" URI
215 of your web application. It defaults to ``/saml2protected``, but it can be
216 set with the ``--saml-auth`` option.
219 This is the URI where SAML communication will occur. This URI must be
220 beneath the base URI. This is not an actual URI within your web
221 application, as the httpd module will be handling communication for this URI.
222 The default is ``/saml2``, but it can be set with the ``--saml-sp`` option.
225 This is the URI where SAML logout will be triggered. This URI must be
226 beneath the endpoint URI. This is not an actual URI within your web
227 application, as the httpd module will be handling communication for this URI.
228 The default is ``/saml2/logout``, but it can be set with the
229 ``--saml-sp-logout`` option. More detail about how the logout URI is used
230 are provided in the `Logout Handling`_ section below.
233 This is the URI where SAML responses from the IDP will be posted. This URI
234 must be beneath the endpoint URI. This is not an actual URI within your web
235 application, as the httpd module will be handling communication for this URI.
236 The default is ``/saml2/postResponse``, but if can be set with the
237 ``--saml-sp-post`` option.
239 You will typically only need to specify the auth URI option above, unless you
240 have a reason to change the base URI (which will affect all of the other URIs
241 since they all must be beneath the base).
243 You can download the IDP metadata from Ipsilon. Assuming that the IDP name of
244 Ipsilon is the default of ``idp``, the metadata can be accessed at::
246 ``https://<ipsilon FQDN>/idp/saml2/metadata``
248 You will need to save this metadata for configuring httpd in the next step.
253 The handling of SAML in httpd is taken care of by the `mod_auth_mellon`_
254 module. The first step in ensuring that you are loading the mod_auth_mellon
255 library. This will look something like this::
257 LoadModule auth_mellon_module /usr/lib64/httpd/modules/mod_auth_mellon.so
259 You will need to ensure that the ``Location`` directive that matches the base
260 URI we specified during metadata creation contains the proper Mellon
261 directives. This ``Location`` directive is where we specify the key and
262 certificate that the SP is using, the trusted IDP metadata, and the endpoint
263 URI to use for SAML communication. Here is an example of the base URI
264 ``Location`` directive::
268 MellonSPPrivateKeyFile /etc/httpd/saml2/mysite/certificate.key
269 MellonSPCertFile /etc/httpd/saml2/mysite/certificate.pem
270 MellonSPMetadataFile /etc/httpd/saml2/mysite/metadata.xml
271 MellonIdPMetadataFile /etc/httpd/saml2/mysite/idp-metadata.xml
272 MellonEndpointPath /saml2
276 The ``MellonEnable`` directive with a value of ``info`` means that assertion
277 data will be made available to the web application at this location if it is
278 present. If a user has not authenticated via SAML, they will be allowed into
279 your site, but no assertion data will be present to provide. Typically, this
280 location will encompass your entire web application and you will have an
281 additional protected location at your "Log In" URI that triggers the
284 The ``MellonSP*`` directives tell mod_auth_mellon about the SP that it is
285 representing. These directives point to the key, certificate, and metadata
286 that was generated by ``ipsilon-client-install``.
288 The ``MellonIdPMetadataFile`` directive points to the IDP metadata that you
289 downloaded from the IDP. The IDP metadata contains the certificate of the IDP,
290 so it is used to validate the signature of the responses that come from the
291 IDP. In effect, this is how the trust of the IDP is configured for your SP.
292 The IDP metadata also contains the URL of the IDP, which is used when
293 redirecting users to the IDP to perform authentication.
295 The ``MellonEndpointPath`` directive must match the endpoint URI that was used
296 when generating the metadata with ``ipsilon-client-install``.
298 The ``MellonIdP`` directive is used to expose an IDP identifier to your web
299 application via an environment variable. The value of this directive is used
300 to indicate the name of the environment variable.
302 You also need to configure your auth URI to require authentication via
303 mod_auth_mellon. This is done by adding the ``AuthType`` and ``MellonEnable``
304 directives within the ``Location`` directive that matches your auth URI. Here
305 is an example of the auth URI ``Location`` directive::
312 With these changes, you should be able to access your auth URI, which will
313 trigger the authentication flow that was previously described. The browser
314 will be returned to the auth URI, and values contained in the SAML assertion
315 will be exposed to your web application as environment variables. To do
316 anything useful, your application will have to know how to consume this
319 Consuming Assertion Data
320 ------------------------
321 A web application will typically need changes to allow it to make use of the
322 environment variables that are provided by mod_auth_mellon. Making these
323 changes even has value outside of Ipsilon, as it allows your web application to
324 support external authentication and user info as described in the
325 `Web App Authentication`_ page on the FreeIPA wiki. It will ultimately make
326 your web application more flexible as new authentication and federation methods
329 The provided environment variables fall into two main categories. A user
330 identifier, and other information about the user.
332 If your web application only needs to know who the user is and nothing else
333 about the user, it's quite possible that no changes are needed in your
334 application. This is because the user identifier is provided as the
335 ``REMOTE_USER`` environment variable, which is commonly used by other httpd
336 authentication modules.
338 Quite often, the ``REMOTE_USER`` environment variable isn't enough. It is
339 common for a web application to want more information about a user, such as
340 their e-mail address, their full name, and the groups that they are a member
341 of. Depending on how the Ipsilon IDP is configured, all of this information
342 can be provided to a SP in the SAML assertions. This of course assumes that
343 the underlying identity management system that Ipsilon is using has the
344 information that you need.
346 Every assertion that is contained in the SAML response is provided to your web
347 application by mod_auth_mellon. The environment variables that expose these
348 values are prefixed by `MELLON_`, followed by the name of the assertion. These
349 names are defined by the IDP configuration. Your application is not forced to
350 use a specific set of environment variable names however. You can configure
351 mod_auth_mellon to map the SAML assertions to different environment variable
352 names. This is done by using the ``MellonSetEnv`` and ``MellonSetEnvNoPrefix``
353 directives in the ``Location`` directive for your base URI. Consider the
356 MellonSetEnv "email" "mail"
357 MellonSetEnvNoPrefix "DISPLAY_NAME" "displayName"
359 Both of these directives take the form ``<directive> <local name> <IDP name>``.
360 In the case of the above example, a ``mail`` attribute in the SAML assertion
361 would be expressed as the ``MELLON_email`` environment variable. The
362 ``MellonSetEnvNoPrefix`` directive works the same way, but it does not use the
363 ``MELLON_`` prefix. In this case, a ``displayName`` attribute in the SAML
364 assertion would be expressed as the ``DISPLAY_NAME`` environment variable.
365 There are some good recommendations on some common environment variables that
366 should be used for web application authentication in general on the FreeIPA
367 wiki's `Web App Authentication`_ page.
369 For the purposes of authorization within a web application, it is recommended
370 to take advantage of group membership information that is provided in the SAML
371 assertions. For instance, if your web application has a concept of an
372 ``user`` role, it can allow that role to be assigned to a group that is
373 defined in the identity management system that is used by the IDP. This
374 allows for application access to be controlled by group assignment centrally
375 in the identity management system. It is of course possible to assign the
376 web application roles directly to a user as well if the groups don't map
377 cleanly to the authorization grouping within your application. Still, it is
378 best to try to keep user and group management out of the web application as
381 It is not uncommon for a web application to have a need to store information
382 about a user that will not be provided by an IDP or even by any identity
383 management system. One of the most common cases of this is storing user
384 preferences that are specific to the web application. The recommended way of
385 handling this is to have the web application create a record for this data in
386 it's own backend database when it first sees a new user. It can associate this
387 data with a user identitfier from the assertion, such as ``REMOTE_USER`` or
388 some combination of assertion values that is guaranteed to be unique. The
389 important thing is that none of the other user data from the assertion should
390 be duplicated in the web application's backend database.
394 Changes may also be needed to the web application to allow logout to work
395 properly. When a user succesfully authenticates and accesses a SP that uses
396 mod_auth_mellon, a cookie is set in the user's browser to represent their
397 session. In order to terminate this session when the user logs out of the
398 web application, you have to make sure that your web application will send the
399 user to the logout URI that was defined when the SP metadata was generated. In
400 addition, a required ``ReturnTo`` query parameter must be specified, which
401 tells mod_auth_mellon where to send the user after completing the logout
402 operation. The format of this looks like::
404 <logout URI>?ReturnTo=<url to redirect to after logout>
406 Typically, your application will either redirect or provide a direct link to
414 .. _mod_auth_mellon: https://github.com/UNINETT/mod_auth_mellon/wiki
415 .. _Web App Authentication: http://www.freeipa.org/page/Web_App_Authentication