===============================================================================
QLIKVIEW SAML AUTHENTICATION SAMPLE IMPLEMENTATION
===============================================================================

This package contains a sample implementation on how to interface QlikView
as a SAML 2.0 service provider, using a third-party SAML package.

The high-level view of how SAML interoperates with QlikView is shown below.

+--------------+       +------------+       +----------------------------+
| QlikView (1) |  <=>  | QvSaml (2) |  <=>  | SAML Identity Provider (3) |
+--------------+       +------------+       +----------------------------+

1) Your existing QlikView deployment.
2) This package, deployed as an IIS application (details below). Builds on
   third-party SAML implementation (see section 2 below).
3) Your own or other (trusted) SAML identity provider.

For details about SAML authentication, have a look at WikiPedia:
http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language
Further references are available in that article.

This sample implementation utilises QlikView WebTickets, available as of
QV11. Consult white paper available on XXX for more information about this
technology.

===============================================================================
1. SET UP IIS
===============================================================================

Make sure that you are running IIS (Control Panel -> Programs and Features
-> Turn Windows features on or off -> Internet Information Services)
   
* Turn on ASP.NET support under World Wide Web Services

If you are still having problems with ASP.NET, it might be because the version 
you try to use isn't registered with the IIS. Search the web for how to use the
aspnet_regiis tool for that version of ASP.NET.

===============================================================================
2. DOWNLOAD AND INSTALL OIOSAML.NET
===============================================================================

Download and install OIOSAML.NET from http://digitaliser.dk/resource/2009763
(QlikView SAML sample was developed using OIOSAML.NET v1.7.4)

* You need dk.nita.saml20.dll in your solution/reference path when making
  your own implementation.

===============================================================================
3. CONFIGURE OIOSAML.NET [OPTIONAL (but recommended)]
===============================================================================

This section is completely optional. All you _really_ need from the OIOSAML
package is the .dll mentioned in section 2 above.

However, for test and development purposes it's probably useful to
configure OIOSAML.NET, following the instructions in that package. You
probably want at least the demo identity provider for this purpose.

* Make sure to import certificates exactly as outlined in the documentation,
  do _not_ double-click on the .pfx files. (This will cause the OIOSAML
  certificates to end up in the "Current User" certificate storage rather
  than the "Local Machine" that we want). You can _not_ fix this by moving
  the certificates in MMC snap-in since the private keys won't be moved
  along with the public certificate. 

* If running IIS 7.5 (7.0?) or later, when adding permissions to the
  certificates' private keys and metadata directories, use
  "IIS AppPool\DefaultAppPool" (or the application pool you want to use of
  course). Rather than the suggested "Network Service" account.

* Add your own test users to the demo identity provider
  (C:\Program Files (x86)\dk.nita.saml20\bin\IdentityProviderDemo\Web.config).

  If you want to provide user groups along with the user, the syntax is as
  in the example below:

    <add userName="qvt" password="foobar" ppid="QTTST\qvt">
      <attributes>
        <add name="urn:FirstName" value="QlikView" />
        <add name="urn:LastName" value="Tester" />
        <add name="urn:Age" value="42" />
        <add name="urn:oid:0.9.2342.19200300.100.1.3" value="qlikview.tester@qliktech.com" />
        <add name="urn:foo:group" value="QTTST\qvdev" />
      </attributes>
    </add>

  'ppid' is the username that is used in QlikView.

  The attribute name for user groups should obviously not be "urn:foo:group",
  but rather the oid or whichever identifier that is used in your organization.
  This value is used in three places; in the identity provider's Web.config
  (above), the service provider/QlikView SAML's Web.config (see the Visual Studio
  solution in this package). And in QlikView.aspx.cs (also in the solution).  

===============================================================================
4. UNPACK AND CONFIGURE QLIKVIEW SAMPLE SAML SERVICE PROVIDER
===============================================================================
  
Unpack QlikViewSamlAuthentication (qvsaml) wherever you like it and add it as a
web application using your IIS Manager (use alias 'qvsaml', otherwise you will
have to make more changes in Web.config).

Change qvsaml's Web.config. In the <SAML20Federation>-section, change the
id and server attributes of the <ServiceProvider> tag. Ensure that the
<Federation><AllowedAudienceUris> section contain an <Audience> element that
_exactly_ matches your <Saml20Federation><ServiceProvider id="..."> attribute.

Change <SAML20Federation><IDPEndPoints metadata="...">, and the <add> clause
specifying your identity provider. If you get errors from the OIOSAML package
with the message "The signature of the incoming message is invalid", it is
likely that this part of your configuration is wrong. Example below:

  <SAML20Federation xmlns="urn:dk.nita.saml20.configuration">
    <IDPEndPoints metadata="C:\spdata\">
      <add id="http://samlidp.yourdomain.com/IdP/">
        <CertificateValidation>
          <add type="dk.nita.saml20.Specification.SelfIssuedCertificateSpecification, dk.nita.saml20"/>
        </CertificateValidation>
      </add>
    </IDPEndPoints>
  </SAML20Federation>

Make sure that the directory pointed to in the metadata attribute is accessible
by "IIS AppPool\DefaultAppPool", just as for the certificates' private keys in
section 3 above.

There are also other relevant clauses which should be relatively straight-forward
to change. Consult the OIOSAML documentation for more details.

You need to provide urls to your AccessPoint's authentication page, the page
you want users to be redirected to on successful authentication. Finally you
need an error page that users will land on when authentication fails on the
QlikView end (as opposed to when it fails on the identity provider end, that is
handled by the set-up described in the OIOSAML package).

All of this information is entered in QlikViewSamlConfig.xml, example below:

  <QlikViewSaml
      accessPointUrl="http://qlikview.yourdomain.com/"
      authenticatePage="QvAjaxZfc/Authenticate.aspx"
      webTicketPage="QvAjaxZfc/GetWebTicket.aspx"
      tryPage="qlikview/"
      backUrl="http://qvsaml.yourdomain.com/qvsaml/webticketerror.html" />

===============================================================================
5. GENERATE/OBTAIN TEST CERTIFICATE FOR YOUR QLIKVIEW SAML SERVICE PROVIDER
===============================================================================

You could use Microsoft's makecert.exe (http://msdn.microsoft.com/en-us/library/bfsktky3(v=vs.80).aspx)
from the .NET Framework Tools (http://msdn.microsoft.com/en-us/library/d9kh6s92(v=vs.80).aspx).

  I used this command line:
    C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin>makecert.exe -r -n "CN=QlikViewSamlTest, O=QlikTech, C=SE" -e 01/01/2013 -sr LocalMachine -ss My

Add permission for the IIS application pool to read the certificate's private
key as you did for the OIOSAML certificate(s).

Change Web.config in the QlikViewSamlAuthentication solution to use your
newly generated certificate. This is done by changing the
<Federation><SigningCertificate findValue="..."> attribute.

Download QlikViewSamlTest's metadata and upload it to the demo identity
provider as explained in OIOSAML's documentation. (Or to the identity
provider you are integrating with).

Download the identity provider's metadata and put it in the directory you
specify in QlikViewSamlAuthentication's Web.config.

===============================================================================
6. CONFIGURING QLIKVIEW
===============================================================================

In QlikView web server, you need to set up you newly configured QlikView SAML
service provider as a trusted web ticket requester. 

This is done in the web server's configuration, usually located in:

  C:\ProgramData\QlikTech\WebServer\config.xml

In the <Authentication> section, add the IP number (not name) of the machine you
just set up for QlikView SAML.

  <Authentication>
    ...
    <GetWebTicket url="/QvAjaxZfc/GetWebTicket.aspx">
	<TrustedIP>fe80::b178:730a:5c2a:86d2%11</TrustedIP>
    </GetWebTicket>
    ...
  </Authentication>

Make sure that you add the IP number that will be used in the communication
between the SAML service provider and the web server. This might be an IPv6
number (as in the example above).

Start your QlikView server and you should be good to go!
