Using Holder-of-Key Web Browser SSO Profile on a simpleSAMLphp SP
=================================================================

This document describes how to enable the [SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf)
on a simpleSAMLphp Service Provider (SP).

The SAML V2.0 HoK Web Browser SSO Profile is an alternate version of the standard SAML Web Browser SSO Profile. Its primary benefit is the enhanced security of the SSO process
while preserving maximum compatibility with existing deployments on client and server side.

When using this profile the communication between the user and the SP is required to be protected by the TLS protocol. Additionally, the user needs a TLS client certificate.
This certificate is usually selfsigned and stored in the certificate store of the browser or the underlying operating system.

Configuring Apache
------------------

The SP requests a client certificate from the user agent during the TLS handshake. This behaviour is enabled with the following Apache webserver configuration:

    SSLEngine on
    SSLCertificateFile /etc/openssl/certs/server.crt
    SSLCertificateKeyFile /etc/openssl/private/server.key
    SSLVerifyClient optional_no_ca
    SSLOptions +ExportCertData

If the user agent can successfully prove possession of the private key associated to the public key from the certificate, the received certificate is stored in the
environment variable `SSL_CLIENT_CERT` of the webserver.

Enable HoK on SP
----------------

Which binding/profile the Identity Provider (IdP) should use when sending authentication responses to the SP is controlled by the `ProtocolBinding` option in the SP configuration.
To make your SP request that the response from the IdP is send using the HoK SSO Profile, this option must be set accordingly:

    'hok-sp' => array(
        'saml:SP',
		'ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
    ),

When this is done, you can add the metadata of your SP to the IdP and test the authentication.
