Adding Holder-of-Key Web Browser SSO Profile support to the IdP
This document describes the necessary steps to enable support for the SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile on a SimpleSAMLphp Identity Provider (IdP).
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 IdP 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.
The IdP 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
of the webserver. The IdP embeds the client certificate into the created HoK assertion.
Enabling HoK SSO Profile on the IdP
To enable the IdP to send HoK assertions you must add the
option to the
$metadata['https://example.org/saml-idp'] = [ [....] 'auth' => 'example-userpass', 'saml20.hok.assertion' => true, ];
Add new metadata to SPs
After enabling the Holder-of-Key Web Browser SSO Profile your IdP metadata will change. An additional HoK
endpoint is added.
You therefore need to update the metadata for your IdP at your SPs.
metadata for SimpleSAMLphp SPs should contain something like the following code:
'SingleSignOnService' => [ [ 'hoksso:ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser', 'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php', ], [ 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php', ], ],
SP metadata on the IdP
A SP using the HoK Web Browser SSO Profile must have an
endpoint supporting that profile.
This means that you have to use the complex endpoint format in
In general, this should look like the following code:
'AssertionConsumerService' => [ [ 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp', 'index' => 0, ], [ 'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser', 'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp', 'index' => 4, ], ],
(The specific values of the various fields will vary depending on the SP.)