<h1class="sectionedit1"id="saml_service_configuration">SAML service configuration</h1>
<divclass="level1">
<divclass="noteclassic"><abbrtitle="Security Assertion Markup Language">SAML</abbr> service configuration is a common step to configure <abbrtitle="LemonLDAP::NG">LL::NG</abbr> as <ahref="authsaml.html"class="wikilink1"title="documentation:2.0:authsaml">SAML SP</a> or <ahref="idpsaml.html"class="wikilink1"title="documentation:2.0:idpsaml">SAML IDP</a>.
</div>
</div>
<!-- EDIT1 SECTION "SAML service configuration" [1-169] -->
This documentation explains how configure <abbrtitle="Security Assertion Markup Language">SAML</abbr> service in <abbrtitle="LemonLDAP::NG">LL::NG</abbr>, in particular:
<liclass="level1"><divclass="li"> Import or generate security keys</div>
</li>
<liclass="level1"><divclass="li"> Set <abbrtitle="Security Assertion Markup Language">SAML</abbr> end points</div>
</li>
</ul>
<divclass="noteimportant">Service configuration will be used to generate <abbrtitle="LemonLDAP::NG">LL::NG</abbr><abbrtitle="Security Assertion Markup Language">SAML</abbr> metadata, that will be shared with other providers. It means that if you modify some settings here, you will have to share again the metadata with other providers. In other words, take the time to configure this part before sharing metadata.
SAML2 implementation is based on <ahref="http://lasso.entrouvert.org"class="urlextern"title="http://lasso.entrouvert.org"rel="nofollow">Lasso</a>. You will need a very recent version of Lasso (>= 2.5.0).
You can use official Debian packages or those available here: <ahref="http://deb.entrouvert.org/"class="urlextern"title="http://deb.entrouvert.org/"rel="nofollow">http://deb.entrouvert.org/</a>.
RPMs are available in <abbrtitle="LemonLDAP::NG">LL::NG</abbr> RPM “extras” repository (see <ahref="installrpm.html#yum_repository"class="wikilink1"title="documentation:2.0:installrpm">yum_repository</a>)
<ahref="http://lasso.entrouvert.org/download/"class="urlextern"title="http://lasso.entrouvert.org/download/"rel="nofollow">Download the Lasso tarball</a> and compile it on your system.
You can define keys for <abbrtitle="Security Assertion Markup Language">SAML</abbr> message signature and encryption. If no encryption keys are defined, signature keys are used for signature and encryption.
</p>
<p>
To define keys, you can:
</p>
<ul>
<liclass="level1"><divclass="li"> import your own private and public keys (<code>Replace by file</code> input)</div>
</li>
<liclass="level1"><divclass="li"> generate new public and private keys (<code>New keys</code> button)</div>
</li>
</ul>
<divclass="notetip">You can enter a password to protect private key with a password. It will be prompted if you generate keys, else you can set it in the <code>Private key password</code>.
You can import a certificate containing the public key instead the raw public key. However, certificate will not be really validated by other <abbrtitle="Security Assertion Markup Language">SAML</abbr> components (expiration date, common name, etc.), but will just be a public key wrapper.
</p>
<divclass="notetip">You can easily generate a certificate to replace your public key by saving the private key in a file, and use <code>openssl</code> commands to issue a self-signed certificate:
<liclass="level1"><divclass="li"><strong>Use certificate in response</strong>: Certificate will be sent inside <abbrtitle="Security Assertion Markup Language">SAML</abbr> responses.</div>
</li>
<liclass="level1"><divclass="li"><strong>Signature method</strong>: set the signature algorithm</div>
</li>
</ul>
<divclass="noteimportant">Default value is RSA SHA1 for compatibility purpose but we recommend to use RSA SHA256. This requires to test all partners to check their compatibility.
<abbrtitle="Security Assertion Markup Language">SAML</abbr> can use different NameID formats. The NameID is the main user identifier, carried in <abbrtitle="Security Assertion Markup Language">SAML</abbr> messages. You can configure here which field of <abbrtitle="LemonLDAP::NG">LL::NG</abbr> session will be associated to a NameID format.
</p>
<divclass="noteclassic">This parameter is used by <ahref="idpsaml.html"class="wikilink1"title="documentation:2.0:idpsaml">SAML IDP</a> to fill the NameID in authentication responses.
</div>
<p>
Customizable NameID formats are:
</p>
<ul>
<liclass="level1"><divclass="li"> Email</div>
</li>
<liclass="level1"><divclass="li"> X509</div>
</li>
<liclass="level1"><divclass="li"> Windows</div>
</li>
<liclass="level1"><divclass="li"> Kerberos</div>
</li>
</ul>
<divclass="notetip">For example, if you are using <ahref="authldap.html"class="wikilink1"title="documentation:2.0:authldap">AD as authentication backend</a>, you can use sAMAccountName for the Windows NameID format.
</div>
<p>
Other NameID formats are automatically managed:
</p>
<ul>
<liclass="level1"><divclass="li"><strong>Transient</strong>: NameID is generated</div>
</li>
<liclass="level1"><divclass="li"><strong>Persistent</strong>: NameID is restored from previous sessions</div>
</li>
<liclass="level1"><divclass="li"><strong>Undefined</strong>: Default NameID format is used</div>
Each <abbrtitle="LemonLDAP::NG">LL::NG</abbr> authentication module has an authentication level, which can be associated to an <ahref="http://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf"class="urlextern"title="http://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf"rel="nofollow">SAML authentication context</a>.
</p>
<divclass="noteclassic">This parameter is used by <ahref="idpsaml.html"class="wikilink1"title="documentation:2.0:idpsaml">SAML IDP</a> to fill the authentication context in authentication responses. It will use the authentication level registered in user session to match the <abbrtitle="Security Assertion Markup Language">SAML</abbr> authentication context. It is also used by <ahref="authsaml.html"class="wikilink1"title="documentation:2.0:authsaml">SAML SP</a> to fill the authentication level in user session, based on authentication response authentication context.
<liclass="level1"><divclass="li"><strong><abbrtitle="Uniform Resource Locator">URL</abbr></strong>: <abbrtitle="Uniform Resource Locator">URL</abbr> of your society</div>
<liclass="level1"><divclass="li"><strong>Want Authentication Request Signed</strong>: set to On to require that received authentication request are signed.</div>
</li>
</ul>
<divclass="notetip">This option can then be overridden for each Service Provider.
</div>
</div>
<h4id="single_sign_on">Single Sign On</h4>
<divclass="level4">
<p>
For each binding you can set:
</p>
<ul>
<liclass="level1"><divclass="li"><strong>Location</strong>: Access Point for <abbrtitle="Single Sign On">SSO</abbr> request.</div>
</li>
<liclass="level1"><divclass="li"><strong>Response Location</strong>: Access Point for <abbrtitle="Single Sign On">SSO</abbr> response.</div>
These parameters are not mandatory to run <abbrtitle="Security Assertion Markup Language">SAML</abbr> service, but can help to customize it:
</p>
<ul>
<liclass="level1"><divclass="li"><strong>IDP resolution cookie name</strong>: by default, it's the <abbrtitle="LemonLDAP::NG">LL::NG</abbr> cookie name suffixed by <code>idp</code>, for example: <code>lemonldapidp</code>.</div>
</li>
<liclass="level1"><divclass="li"><strong>UTF8 metadata conversion</strong>: set to On to force partner's metadata conversion.</div>
</li>
</ul>
</div>
<h4id="saml_sessions_module_name_and_options">SAML sessions module name and options</h4>
<divclass="level4">
<p>
By default, the main session module is used to store <abbrtitle="Security Assertion Markup Language">SAML</abbr> temporary data (like relay-states), but <abbrtitle="Security Assertion Markup Language">SAML</abbr> sessions need to use a session module compatible with the <ahref="documentation/features.html#session_restrictions"class="wikilink1"title="documentation:features">sessions restrictions feature</a>.
</p>
<p>
This is not the case of <ahref="memcachedsessionbackend.html"class="wikilink1"title="documentation:2.0:memcachedsessionbackend">Memcached</a> for example. In this case, you can choose a different module to manage <abbrtitle="Security Assertion Markup Language">SAML</abbr> sessions.
</p>
<divclass="notetip">You can also choose a different session module to split <abbrtitle="Single Sign On">SSO</abbr> sessions and <abbrtitle="Security Assertion Markup Language">SAML</abbr> sessions.
<liclass="level1"><divclass="li"><strong>RelayState session timeout</strong>: timeout for RelayState sessions. By default, the RelayState session is deleted when it is read. This timeout allows one to purge sessions of lost RelayState.</div>
<liclass="level1"><divclass="li"><strong>Use specific query_string method</strong>: the CGI query_string method may break invalid <abbrtitle="Uniform Resource Locator">URL</abbr> encoded signatures (issued for example by ADFS). This option allows one to use a specific method to extract query string, that should be compliant with non standard <abbrtitle="Uniform Resource Locator">URL</abbr> encoded parameters.</div>
<divclass="noteclassic">Common Domain Cookie is also know as <ahref="http://www.switch.ch/aai/support/tools/wayf.html"class="urlextern"title="http://www.switch.ch/aai/support/tools/wayf.html"rel="nofollow">WAYF Service</a>.
</div>
<p>
The common domain is used by <ahref="authsaml.html"class="wikilink1"title="documentation:2.0:authsaml">SAML SP</a> to find an Identity Provider for the user, and by <ahref="idpsaml.html"class="wikilink1"title="documentation:2.0:idpsaml">SAML IDP</a> to register itself in user's IDP list.
</p>
<p>
Configuration parameters are:
</p>
<ul>
<liclass="level1"><divclass="li"><strong>Activation</strong>: Set to On to enable Common Domain Cookie support.</div>
</li>
<liclass="level1"><divclass="li"><strong>Common domain</strong>: Name of the common domain (where common cookie is available).</div>
</li>
<liclass="level1"><divclass="li"><strong>Reader <abbrtitle="Uniform Resource Locator">URL</abbr></strong>: <abbrtitle="Uniform Resource Locator">URL</abbr> used by <abbrtitle="Security Assertion Markup Language">SAML</abbr> SP to read the cookie. Leave blank to deactivate the feature.</div>
</li>
<liclass="level1"><divclass="li"><strong>Writer <abbrtitle="Uniform Resource Locator">URL</abbr></strong>: <abbrtitle="Uniform Resource Locator">URL</abbr> used by <abbrtitle="Security Assertion Markup Language">SAML</abbr> IDP to write the cookie. Leave blank to deactivate the feature.</div>