doc/saml-integration.rst

   1 ============================================
   2 Ipsilon - Web Application Integration (SAML)
   3 ============================================
   4
   5 Ipsilon allows web applications to consume users from existing identity
   6 management systems, even those that it doesn't have direct access to.
   7
   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.
  12
  13 Local user database:
  14
  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
  19   perspective.
  20 * Scalability and replication of the database become the responsibility of the
  21   web application developers.
  22
  23 LDAP server:
  24
  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
  27   perspective.
  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.
  31
  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.
  35
  36 This document describes the recommended practices for integrating a web
  37 application with Ipsilon to allow for SAML federated single sign-on.
  38
  39
  40 Federated Single Sign-On Concepts
  41 =================================
  42
  43 Before getting into the concepts of SAML federated single sign-on, it is
  44 important to understand some basic terminology:
  45
  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
  50   is a SAML IDP.
  51
  52 Service Provider (SP)
  53   A SAML Service Provider is a web application that is using an IDP to provide
  54   authentication service and user information.
  55
  56 Assertion
  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.
  60
  61 Single Sign-On (SSO)
  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.
  64
  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.
  68
  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.
  82
  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.
  90
  91 Authentication Flow
  92 -------------------
  93
  94 The following picture depicts the authentication flow that occurs when using
  95 SAML::
  96
  97     +---------------+      +---------------+
  98     |               |      |               |
  99     |  Application  |      |    Ipsilon    |
 100     |      (SP)     |      |     (IDP)     |
 101     |               |      |               |
 102     +--^----+----^--+      +----^-----+----+
 103        |    |    |              |     |
 104       (1)  (2)  (5)            (3)   (4)
 105        |    |    |              |     |
 106     +--+----v----+--------------+-----v----+
 107     |                                      |
 108     |             Web Browser              |
 109     |                                      |
 110     +--------------------------------------+
 111
 112 The steps in the authentication flow are:
 113
 114   1. A user accesses a protected URL of the web application via browser.
 115
 116   2. The web application returns a redirect to the user, pointing them to the
 117      IDP.
 118
 119   3. The browser follows the redirect to the IDP, where the user is asked to
 120      authenticate.
 121
 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.
 124
 125   5. The browser automatically sumbits the returned form, which does a POST
 126      of the SAML response to the web application.
 127
 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.
 133
 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.
 139
 140
 141 Web Application Integration
 142 ===========================
 143
 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.
 148
 149 Service Provider Configuration
 150 ------------------------------
 151
 152 Configuring a web application's webserver as a SP is comprised of a few steps:
 153
 154 * SP key, certificate, and metadata generation
 155 * IDP metadata retrieval
 156 * SP registration
 157 * httpd configuration
 158
 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.
 163
 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.
 173
 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.
 177
 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.
 183
 184 Here is a basic example of using ``ipsilon-client-install`` to set up a SP::
 185
 186     ipsilon-client-install --saml-idp-url https://ipsilon.example.test/idp \
 187                            --saml-sp-name mysite --saml-auth /sp \
 188                            --saml-no-httpd
 189
 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.
 194
 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.
 200
 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:
 204
 205 base
 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.
 209
 210 auth
 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.
 217
 218 endpoint
 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.
 223
 224 logout
 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.
 231
 232 post
 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.
 238
 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).
 242
 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::
 245
 246     ``https://<ipsilon FQDN>/idp/saml2/metadata``
 247
 248 You will need to save this metadata for configuring httpd in the next step.
 249
 250 Apache HTTPD Config
 251 -------------------
 252
 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::
 256
 257     LoadModule auth_mellon_module /usr/lib64/httpd/modules/mod_auth_mellon.so
 258
 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::
 265
 266     <Location />
 267       MellonEnable "info"
 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
 273       MellonIdP "IDP"
 274     </Location>
 275
 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
 282 authentication flow.
 283
 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``.
 287
 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.
 294
 295 The ``MellonEndpointPath`` directive must match the endpoint URI that was used
 296 when generating the metadata with ``ipsilon-client-install``.
 297
 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.
 301
 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::
 306
 307     <Location /sp>
 308       AuthType "Mellon"
 309       MellonEnable "auth"
 310     </Location>
 311
 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
 317 assertion data.
 318
 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
 327 emerge.
 328
 329 The provided environment variables fall into two main categories.  A user
 330 identifier, and other information about the user.
 331
 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.
 337
 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.
 345
 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
 354 following examples::
 355
 356     MellonSetEnv "email" "mail"
 357     MellonSetEnvNoPrefix "DISPLAY_NAME" "displayName"
 358
 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.
 368
 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
 379 much as possible.
 380
 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.
 391
 392 Logout Handling
 393 ---------------
 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::
 403
 404     <logout URI>?ReturnTo=<url to redirect to after logout>
 405
 406 Typically, your application will either redirect or provide a direct link to
 407 the logout URI.
 408
 409
 410 References
 411 ==========
 412 .. target-notes::
 413
 414 .. _mod_auth_mellon: https://github.com/UNINETT/mod_auth_mellon/wiki
 415 .. _Web App Authentication: http://www.freeipa.org/page/Web_App_Authentication