Skip to content
Snippets Groups Projects
Commit ee3701e3 authored by Andreas Åkre Solberg's avatar Andreas Åkre Solberg
Browse files

Updating installing SP documentation to better correspond to simplesamlphp 1 

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@257 44740490-163a-0410-bde0-09ae8108e29a
parent 3c0b0fbe
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
docs/source/simplesamlphp-sp.xml
+ 365
− 203
View file @ ee3701e3
...@@ -18,6 +18,12 @@ ...@@ -18,6 +18,12 @@
</author> </author>
</articleinfo> </articleinfo>
<note>
<para>This document is in progress of beeing updated to correspond to
simpleSAMLphp version 1.0. simpleSAMLphp version 1.0 is scheduled to be
released in March 2008.</para>
</note>
<section> <section>
<title>Introduction</title> <title>Introduction</title>
...@@ -31,9 +37,11 @@ ...@@ -31,9 +37,11 @@
<title>Configuring metadata for SAML 2.0 SP</title> <title>Configuring metadata for SAML 2.0 SP</title>
<para>When you are setting up a SAML 2.0 SP, you would need to configure <para>When you are setting up a SAML 2.0 SP, you would need to configure
two metadata files. saml20-sp-hosted.php and saml20-idp-remote.php. two metadata files. <filename>saml20-sp-hosted.php</filename> and
saml20-sp-hosted.php represent the SAML entity of the service provider <filename>saml20-idp-remote.php</filename>.
itself, while the saml20-idp-remote.php configuration lists all the <filename>saml20-sp-hosted.php</filename> represent the SAML entity of the
service provider itself, while the
<filename>saml20-idp-remote.php</filename> configuration lists all the
trusted SAML 2.0 IdP and how to connect to them.</para> trusted SAML 2.0 IdP and how to connect to them.</para>
<section> <section>
...@@ -50,23 +58,32 @@ ...@@ -50,23 +58,32 @@
use.</para> use.</para>
</note> </note>
<para>Here is an example of the metadata file:</para> <example>
<title>Example of metadata for hosted SAML 2.0 SP</title>
<programlisting>$metadata = array( <para>Here is an example of the metadata file:</para>
/* <programlisting>/*
* Example of a hosted SP * Example of a hosted SP
*/ */
'entityid' =&gt; array( 'sp-entityid' =&gt; array(
'host' =&gt; 'hostname', 'host' =&gt; 'sp.example.org'
'spNameQualifier' =&gt; 'entityid', )</programlisting>
'NameIDFormat' =&gt; 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', </example>
'ForceAuthn' =&gt; 'false'
) <para>You may add any number of SP definitions in the same installation
of simpleSAMLphp. simpleSAMLphp will discover automatically which
configuration to use in a specific scenario, by looking up the current
hostname sent by the client and map that to the <literal>host</literal>
entry in the metadata.</para>
);</programlisting> <para>Below is a description of the mandatory and optional fields in the
SAML 2.0 SP hosted metadata.</para>
<section>
<title>Mandatory metadata fields</title>
<para>Here are the description of the possible fields:</para> <para>These field are required to be included in the metadata:</para>
<glosslist> <glosslist>
<glossentry> <glossentry>
...@@ -77,16 +94,6 @@ ...@@ -77,16 +94,6 @@
</glossdef> </glossdef>
</glossentry> </glossentry>
<glossentry>
<glossterm>spNameQualifier</glossterm>
<glossdef>
<para>The name qualifier of the SP. If this is not important to
you, you can set it to be identical with the entity ID
above.</para>
</glossdef>
</glossentry>
<glossentry> <glossentry>
<glossterm>host</glossterm> <glossterm>host</glossterm>
...@@ -96,14 +103,22 @@ ...@@ -96,14 +103,22 @@
metadata to use, when it runs multiple virtual hosts.</para> metadata to use, when it runs multiple virtual hosts.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<para>These fields can be left out if not needed.</para>
<glosslist>
<glossentry> <glossentry>
<glossterm>NameIDFormat</glossterm> <glossterm>NameIDFormat</glossterm>
<glossdef> <glossdef>
<para>The NameIDFormat in the request. If you don't know what this <para>The NameIDFormat in the request. If you don't know what
is, or don't need it to be anything specific, leave it with the this is, or don't need it to be anything specific, leave it with
default configuration.</para> the default configuration.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -111,37 +126,98 @@ ...@@ -111,37 +126,98 @@
<glossterm>ForceAuthn</glossterm> <glossterm>ForceAuthn</glossterm>
<glossdef> <glossdef>
<para>Force authentication is a parameter that allows you to force <para>Force authentication is a parameter that allows you to
re-authenticatino of users even if the user contains a SSO session force re-authenticatino of users even if the user contains a SSO
at the IdP.</para> session at the IdP.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
</glosslist> </glosslist>
</section> </section>
<section>
<title>Fields for signing authentication requests</title>
<para>simpleSAMLphp supports signing the HTTP-REDIRECT authentication
request, but by default it will not sign it. Note that if you want to
sign the authentication requests, you will need to have a
keypair/certificate at the SP.</para>
<glosslist>
<glossentry>
<glossterm>request.signing</glossterm>
<glossdef>
<para>A boolean value, that should be true or false. Default is
false. To turn on signing authentication requests, set this flag
to true.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>privatekey</glossterm>
<glossdef>
<para>The filename of the privatekey to be used for
singing.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>certificate</glossterm>
<glossdef>
<para>The filename of the certificate which corresponds to the
privatekey.</para>
</glossdef>
</glossentry>
</glosslist>
<example>
<title>Example of configured signed requests</title>
<programlisting>'request.signing' =&gt; true,
'privatekey' =&gt; 'server.pem',
'certificate' =&gt; 'server.crt'</programlisting>
</example>
</section>
</section>
<section> <section>
<title>Configuring SAML 2.0 IdP Remote metadata</title> <title>Configuring SAML 2.0 IdP Remote metadata</title>
<para>This metadata file lists all the IdPs that you trust.</para> <para>The metadata file <filename>saml20-idp-remote.php</filename>
represent the SAML 2.0 IdPs that your service provider trust.</para>
<example>
<title>Example of metadata for trusted remote SAML 2.0 IdP</title>
<para>Here is an example of a metadata entry for a remote trusted
IdP:</para>
<programlisting>/* <programlisting>/*
* Example simpleSAMLphp SAML 2.0 IdP * Example simpleSAMLphp SAML 2.0 IdP
*/ */
'idp.example.org' =&gt; array( 'idp-entity-id-simple' =&gt; array(
'name' =&gt; 'Test', 'name' =&gt; 'Test',
'description' =&gt; 'Description of this example entry', 'description' =&gt; 'Description of this example entry',
'SingleSignOnService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php', 'SingleSignOnService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
'SingleLogoutService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/LogoutService.php', 'SingleLogoutService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
'certFingerprint' =&gt; '3fa158e8abfd4b5203315b08c0b791b6ee4715f6', 'certFingerprint' =&gt; '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
'base64attributes' =&gt; true
),</programlisting> ),</programlisting>
</example>
<section>
<title>Mandatory metadata fields</title>
<para>These field are required to be included in the metadata:</para>
<glosslist> <glosslist>
<glossentry> <glossentry>
<glossterm>index (the index of the array)</glossterm> <glossterm>index (the index of the array)</glossterm>
<glossdef> <glossdef>
<para>The entity ID of this SAML 2.0 IdP entity.</para> <para>The entity ID of the remote IdP.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -149,9 +225,8 @@ ...@@ -149,9 +225,8 @@
<glossterm>name</glossterm> <glossterm>name</glossterm>
<glossdef> <glossdef>
<para>Set the name of this identity provider. Will just be used in <para>A textual name of the IdP. (used in the SAML 2.0 discovery
the UI of the discovery service, so set it to whatever you service)</para>
want.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -159,9 +234,8 @@ ...@@ -159,9 +234,8 @@
<glossterm>description</glossterm> <glossterm>description</glossterm>
<glossdef> <glossdef>
<para>Set the description of this identity provider. Will just be <para>A longer description of the IdP. (used in the SAML 2.0
used in the UI of the discovery service, so set it to whatever you discovery service)</para>
want.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -170,8 +244,8 @@ ...@@ -170,8 +244,8 @@
<glossdef> <glossdef>
<para>Contact the IdP to get the endpoint URL of this service. <para>Contact the IdP to get the endpoint URL of this service.
This is the URL which the user is redirected with the AuthnRequest This is the URL which the user is redirected with the
using HTTP-REDIRECT.</para> AuthnRequest using HTTP-REDIRECT.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -189,27 +263,88 @@ ...@@ -189,27 +263,88 @@
<glossterm>certFingerprint</glossterm> <glossterm>certFingerprint</glossterm>
<glossdef> <glossdef>
<para>The md5sum of the certificate used by the IdP. If you don't <para>The md5sum of the certificate used by the IdP. If you
know how to compute this, you can leave it as it is, and then don't know how to compute this, you can leave it as it is, and
you'll get an error message the first time you try to login. In then you'll get an error message the first time you try to
this error message you are told what is the fingerprint of the IdP login. In this error message you are told what is the
certiciate, so you can copy and use that.</para> fingerprint of the IdP certiciate, so you can copy and use
that.</para>
<para>See <xref linkend="a.fingerprint" /> for an example of how
to calculate the fingerprint with the openssl tool.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<para>These fields can be left out if not needed.</para>
<glosslist>
<glossentry> <glossentry>
<glossterm>base64encode</glossterm> <glossterm>base64encode</glossterm>
<glossdef> <glossdef>
<para>Is the IdP base64 encoding all the attributes? <para>Is the IdP base64 encoding all the attributes?
Base64encoding should be avoided but makes it much easier to send Base64encoding should be avoided but makes it much easier to
data in different formats and characterencodings, so you can leave send data in different formats and characterencodings, so you
it on when you test. If you are using simpleSAMLphp at the IdP, can leave it on when you test. <warning>
remember to set the parameter in the metadata at the IdP to be the <para>If you are using simpleSAMLphp at the IdP, remember to
set the parameter in the metadata at the IdP to be the
same.</para> same.</para>
</warning></para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Fields for requireing signed LogoutRequests</title>
<para>simpleSAMLphp supports signing the HTTP-REDIRECT authentication
request, but by default it will not sign it. Note that if you want to
sign the authentication requests, you will need to have a
keypair/certificate at the SP.</para>
<glosslist>
<glossentry>
<glossterm>request.signing</glossterm>
<glossdef>
<para>A boolean value, that should be true or false. Default is
false. To turn on signing authentication requests, set this flag
to true.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>privatekey</glossterm>
<glossdef>
<para>The filename of the privatekey to be used for
singing.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>certificate</glossterm>
<glossdef>
<para>The filename of the certificate which corresponds to the
privatekey.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
</glosslist> </glosslist>
<example>
<title>Example of configured signed LogoutRequests</title>
<programlisting>'request.signing' =&gt; true,
'certificate' =&gt; 'server.crt'</programlisting>
</example>
</section>
</section> </section>
<section> <section>
...@@ -257,12 +392,20 @@ ...@@ -257,12 +392,20 @@
configure two parameters, the entity ID and the hostname of the server configure two parameters, the entity ID and the hostname of the server
running this SP.</para> running this SP.</para>
<example>
<title>Shibboleth 1.3 SP hosted metadata</title>
<programlisting>/* <programlisting>/*
* Example of hosted Shibboleth 1.3 SP. * Example of hosted Shibboleth 1.3 SP.
*/ */
'sp1entityid' =&gt; array( 'sp-provider-id' =&gt; array(
'host' =&gt; 'sp.example.org' 'host' =&gt; 'sp.example.org'
)</programlisting> )
</programlisting>
</example>
<section>
<title>Mandatory fields</title>
<glosslist> <glosslist>
<glossentry> <glossentry>
...@@ -284,6 +427,7 @@ ...@@ -284,6 +427,7 @@
</glossentry> </glossentry>
</glosslist> </glosslist>
</section> </section>
</section>
<section> <section>
<title>Configuring Shibboleth 1.3 IdP Remote metadata</title> <title>Configuring Shibboleth 1.3 IdP Remote metadata</title>
...@@ -291,29 +435,37 @@ ...@@ -291,29 +435,37 @@
<para>Here (shib13-idp-remote.php) you configure which IdPs that you <para>Here (shib13-idp-remote.php) you configure which IdPs that you
trust.</para> trust.</para>
<programlisting> 'urn:mace:switch.ch:aaitest:dukono.switch.ch' =&gt; array( <example>
'SingleSignOnUrl' =&gt; 'https://dukono.switch.ch/shibboleth-idp/SSO', <title>Example of remote Shibboleth 1.3 IdP metadata</title>
'certFingerprint' =&gt; 'c7279a9f28f11380509e075441e3dc55fb9ab864'
),</programlisting> <programlisting>'theproviderid-of-the-idp' =&gt; array(
'SingleSignOnService' =&gt; 'https://idp.example.org/shibboleth-idp/SSO',
'certFingerprint' =&gt; 'c7279a9f28f11380509e072441e3dc55fb9ab864'
)</programlisting>
</example>
<glosslist> <glosslist>
<glossentry> <glossentry>
<glossterm>index (the index of the array)</glossterm> <glossterm>index (the index of the array)</glossterm>
<glossdef> <glossdef>
<para>The entity ID of this Shibboleth 1.3 IdP entity. In this <para>The providerID of this Shibboleth 1.3 IdP entity. In this
example the entity ID is set to example the entity ID is set to
<literal>urn:mace:switch.ch:aaitest:dukono.switch.ch</literal>.</para> <literal>urn:mace:switch.ch:aaitest:dukono.switch.ch</literal>.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
<glossentry> <glossentry>
<glossterm>SingleSignOnUrl</glossterm> <glossterm>SingleSignOnService</glossterm>
<glossdef> <glossdef>
<para>Contact the IdP to get the endpoint URL of this service. <para>Contact the IdP to get the endpoint URL of this service.
This is the URL which the user is redirected with the request for This is the URL which the user is redirected with the request for
authentication.</para> authentication.<note>
<para>The name of this parameter changed from SingleSignOnUrl
to SingleSignOnService betwen simpleSAMLphp version 0.5 and
1.0.</para>
</note></para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -326,6 +478,9 @@ ...@@ -326,6 +478,9 @@
you'll get an error message the first time you try to login. In you'll get an error message the first time you try to login. In
this error message you are told what is the fingerprint of the IdP this error message you are told what is the fingerprint of the IdP
certiciate, so you can copy and use that.</para> certiciate, so you can copy and use that.</para>
<para>See <xref linkend="a.fingerprint" /> for an example of how
to calculate the fingerprint with the openssl tool.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
</glosslist> </glosslist>
...@@ -449,10 +604,6 @@ ...@@ -449,10 +604,6 @@
<programlisting>require_once('SimpleSAML/Utilities.php'); <programlisting>require_once('SimpleSAML/Utilities.php');
require_once('SimpleSAML/Session.php'); require_once('SimpleSAML/Session.php');
require_once('SimpleSAML/Metadata/MetaDataStorageHandler.php'); require_once('SimpleSAML/Metadata/MetaDataStorageHandler.php');
require_once('SimpleSAML/XML/SAML20/AuthnRequest.php');
require_once('SimpleSAML/XML/SAML20/AuthnResponse.php');
require_once('SimpleSAML/Bindings/SAML20/HTTPRedirect.php');
require_once('SimpleSAML/Bindings/SAML20/HTTPPost.php');
require_once('SimpleSAML/XHTML/Template.php'); require_once('SimpleSAML/XHTML/Template.php');
</programlisting> </programlisting>
...@@ -460,13 +611,10 @@ require_once('SimpleSAML/XHTML/Template.php'); ...@@ -460,13 +611,10 @@ require_once('SimpleSAML/XHTML/Template.php');
with simpleSAMLphp. You can copy this lines into your application without with simpleSAMLphp. You can copy this lines into your application without
changes:</para> changes:</para>
<programlisting>session_start(); <programlisting>/* Load simpleSAMLphp, configuration and metadata */
/* Load simpleSAMLphp, configuration and metadata */
$config = SimpleSAML_Configuration::getInstance(); $config = SimpleSAML_Configuration::getInstance();
$metadata = SimpleSAML_Metadata_MetaDataStorageHandler::getMetadataHandler(); $metadata = SimpleSAML_Metadata_MetaDataStorageHandler::getMetadataHandler();
$session = SimpleSAML_Session::getInstance(); $session = SimpleSAML_Session::getInstance(true);</programlisting>
</programlisting>
<para>Then at last, you check whether the session is valid. If it is not, <para>Then at last, you check whether the session is valid. If it is not,
redirect to the initSSO.php script adding the current URL as a RelayState redirect to the initSSO.php script adding the current URL as a RelayState
...@@ -475,9 +623,12 @@ $session = SimpleSAML_Session::getInstance(); ...@@ -475,9 +623,12 @@ $session = SimpleSAML_Session::getInstance();
so why don't you print_r it out right away to get the structure...</para> so why don't you print_r it out right away to get the structure...</para>
<programlisting>/* Check if valid local session exists.. */ <programlisting>/* Check if valid local session exists.. */
if (!isset($session) || !$session-&gt;isValid() ) { if (!isset($session) || !$session-&gt;isValid('saml2') ) {
header('Location: /' . $config-&gt;getValue('baseurlpath') . 'saml2/sp/initSSO.php?RelayState=' . urlencode(SimpleSAML_Utilities::selfURL())); SimpleSAML_Utilities::redirect(
exit(0); '/' . $config-&gt;getValue('baseurlpath') .
'saml2/sp/initSSO.php',
array('RelayState' =&gt; SimpleSAML_Utilities::selfURL())
);
} }
$attributes = $session-&gt;getAttributes(); $attributes = $session-&gt;getAttributes();
...@@ -500,4 +651,15 @@ print_r($attributes); ...@@ -500,4 +651,15 @@ print_r($attributes);
<para>And please join the mailinglist: <ulink <para>And please join the mailinglist: <ulink
url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">http://rnd.feide.no/content/simplesamlphp-users-mailinglist</ulink></para> url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">http://rnd.feide.no/content/simplesamlphp-users-mailinglist</ulink></para>
</section> </section>
<appendix id="a.fingerprint">
<title>Calculating the fingerprint of a certificate</title>
<para>If you have a certificate file, and want to calculate the
fingerprint, you can use the openssl command:</para>
<screen>cert]$ cat server.crt|openssl x509 -fingerprint
MD5 Fingerprint=D1:BA:B0:17:66:6D:7F:42:7B:91:1E:22:7E:3A:27:D2
</screen>
</appendix>
</article> </article>
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment