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
Hide whitespace changes
Inline Side-by-side
docs/source/simplesamlphp-sp.xml
+ 365
− 203
View file @ ee3701e3
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
<articleinfo> <articleinfo>
<date>2007-10-15</date> <date>2007-10-15</date>
<pubdate>Fri Feb 1 08:44:40 2008</pubdate> <pubdate>Fri Feb 1 08:44:40 2008</pubdate>
<author> <author>
<firstname>Andreas Åkre</firstname> <firstname>Andreas Åkre</firstname>
...@@ -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,166 +58,293 @@ ...@@ -50,166 +58,293 @@
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>
/*
* Example of a hosted SP <programlisting>/*
*/ * Example of a hosted SP
'entityid' =&gt; array( */
'host' =&gt; 'hostname', 'sp-entityid' =&gt; array(
'spNameQualifier' =&gt; 'entityid', 'host' =&gt; 'sp.example.org'
'NameIDFormat' =&gt; 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', )</programlisting>
'ForceAuthn' =&gt; 'false' </example>
)
<para>You may add any number of SP definitions in the same installation
);</programlisting> of simpleSAMLphp. simpleSAMLphp will discover automatically which
configuration to use in a specific scenario, by looking up the current
<para>Here are the description of the possible fields:</para> hostname sent by the client and map that to the <literal>host</literal>
entry in the metadata.</para>
<glosslist>
<glossentry> <para>Below is a description of the mandatory and optional fields in the
<glossterm>index (the index of the array)</glossterm> SAML 2.0 SP hosted metadata.</para>
<glossdef> <section>
<para>The entity ID of the hosted SP entity.</para> <title>Mandatory metadata fields</title>
</glossdef>
</glossentry> <para>These field are required to be included in the metadata:</para>
<glossentry> <glosslist>
<glossterm>spNameQualifier</glossterm> <glossentry>
<glossterm>index (the index of the array)</glossterm>
<glossdef>
<para>The name qualifier of the SP. If this is not important to <glossdef>
you, you can set it to be identical with the entity ID <para>The entity ID of the hosted SP entity.</para>
above.</para> </glossdef>
</glossdef> </glossentry>
</glossentry>
<glossentry>
<glossentry> <glossterm>host</glossterm>
<glossterm>host</glossterm>
<glossdef>
<glossdef> <para>The hostname of the server running this SAML 2.0 SP. This
<para>The hostname of the server running this SAML 2.0 SP. This option allows simpleSAMLphp to automatically discover which SP
option allows simpleSAMLphp to automatically discover which SP 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>
<glossentry>
<glossterm>NameIDFormat</glossterm> <section>
<title>Optional metadata fields</title>
<glossdef>
<para>The NameIDFormat in the request. If you don't know what this <para>These fields can be left out if not needed.</para>
is, or don't need it to be anything specific, leave it with the
default configuration.</para> <glosslist>
</glossdef> <glossentry>
</glossentry> <glossterm>NameIDFormat</glossterm>
<glossentry> <glossdef>
<glossterm>ForceAuthn</glossterm> <para>The NameIDFormat in the request. If you don't know what
this is, or don't need it to be anything specific, leave it with
<glossdef> the default configuration.</para>
<para>Force authentication is a parameter that allows you to force </glossdef>
re-authenticatino of users even if the user contains a SSO session </glossentry>
at the IdP.</para>
</glossdef> <glossentry>
</glossentry> <glossterm>ForceAuthn</glossterm>
</glosslist>
<glossdef>
<para>Force authentication is a parameter that allows you to
force re-authenticatino of users even if the user contains a SSO
session at the IdP.</para>
</glossdef>
</glossentry>
</glosslist>
</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> <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>
<programlisting> /*
* Example simpleSAMLphp SAML 2.0 IdP <example>
*/ <title>Example of metadata for trusted remote SAML 2.0 IdP</title>
'idp.example.org' =&gt; array(
'name' =&gt; 'Test', <para>Here is an example of a metadata entry for a remote trusted
'description' =&gt; 'Description of this example entry', IdP:</para>
'SingleSignOnService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
'SingleLogoutService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/LogoutService.php', <programlisting>/*
'certFingerprint' =&gt; '3fa158e8abfd4b5203315b08c0b791b6ee4715f6', * Example simpleSAMLphp SAML 2.0 IdP
'base64attributes' =&gt; true */
),</programlisting> 'idp-entity-id-simple' =&gt; array(
'name' =&gt; 'Test',
<glosslist> 'description' =&gt; 'Description of this example entry',
<glossentry>
<glossterm>index (the index of the array)</glossterm> 'SingleSignOnService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
'SingleLogoutService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
<glossdef> 'certFingerprint' =&gt; '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
<para>The entity ID of this SAML 2.0 IdP entity.</para> ),</programlisting>
</glossdef> </example>
</glossentry>
<section>
<glossentry> <title>Mandatory metadata fields</title>
<glossterm>name</glossterm>
<para>These field are required to be included in the metadata:</para>
<glossdef>
<para>Set the name of this identity provider. Will just be used in <glosslist>
the UI of the discovery service, so set it to whatever you <glossentry>
want.</para> <glossterm>index (the index of the array)</glossterm>
</glossdef>
</glossentry> <glossdef>
<para>The entity ID of the remote IdP.</para>
<glossentry> </glossdef>
<glossterm>description</glossterm> </glossentry>
<glossdef> <glossentry>
<para>Set the description of this identity provider. Will just be <glossterm>name</glossterm>
used in the UI of the discovery service, so set it to whatever you
want.</para> <glossdef>
</glossdef> <para>A textual name of the IdP. (used in the SAML 2.0 discovery
</glossentry> service)</para>
</glossdef>
<glossentry> </glossentry>
<glossterm>SingleSignOnService</glossterm>
<glossentry>
<glossdef> <glossterm>description</glossterm>
<para>Contact the IdP to get the endpoint URL of this service.
This is the URL which the user is redirected with the AuthnRequest <glossdef>
using HTTP-REDIRECT.</para> <para>A longer description of the IdP. (used in the SAML 2.0
</glossdef> discovery service)</para>
</glossentry> </glossdef>
</glossentry>
<glossentry>
<glossterm>SingleLogoutService</glossterm> <glossentry>
<glossterm>SingleSignOnService</glossterm>
<glossdef>
<para>Contact the IdP to get the endpoint URL of this service. <glossdef>
This is the URL which the user is redirected with the <para>Contact the IdP to get the endpoint URL of this service.
LogoutRequest using HTTP-REDIRECT.</para> This is the URL which the user is redirected with the
</glossdef> AuthnRequest using HTTP-REDIRECT.</para>
</glossentry> </glossdef>
</glossentry>
<glossentry>
<glossterm>certFingerprint</glossterm> <glossentry>
<glossterm>SingleLogoutService</glossterm>
<glossdef>
<para>The md5sum of the certificate used by the IdP. If you don't <glossdef>
know how to compute this, you can leave it as it is, and then <para>Contact the IdP to get the endpoint URL of this service.
you'll get an error message the first time you try to login. In This is the URL which the user is redirected with the
this error message you are told what is the fingerprint of the IdP LogoutRequest using HTTP-REDIRECT.</para>
certiciate, so you can copy and use that.</para> </glossdef>
</glossdef> </glossentry>
</glossentry>
<glossentry>
<glossentry> <glossterm>certFingerprint</glossterm>
<glossterm>base64encode</glossterm>
<glossdef>
<glossdef> <para>The md5sum of the certificate used by the IdP. If you
<para>Is the IdP base64 encoding all the attributes? don't know how to compute this, you can leave it as it is, and
Base64encoding should be avoided but makes it much easier to send then you'll get an error message the first time you try to
data in different formats and characterencodings, so you can leave login. In this error message you are told what is the
it on when you test. If you are using simpleSAMLphp at the IdP, fingerprint of the IdP certiciate, so you can copy and use
remember to set the parameter in the metadata at the IdP to be the that.</para>
same.</para>
</glossdef> <para>See <xref linkend="a.fingerprint" /> for an example of how
</glossentry> to calculate the fingerprint with the openssl tool.</para>
</glosslist> </glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<para>These fields can be left out if not needed.</para>
<glosslist>
<glossentry>
<glossterm>base64encode</glossterm>
<glossdef>
<para>Is the IdP base64 encoding all the attributes?
Base64encoding should be avoided but makes it much easier to
send data in different formats and characterencodings, so you
can leave it on when you test. <warning>
<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>
</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>
</glossentry>
</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,32 +392,41 @@ ...@@ -257,32 +392,41 @@
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>
<programlisting> /* <example>
* Example of hosted Shibboleth 1.3 SP. <title>Shibboleth 1.3 SP hosted metadata</title>
*/
'sp1entityid' =&gt; array(
'host' =&gt; 'sp.example.org'
)</programlisting>
<glosslist> <programlisting>/*
<glossentry> * Example of hosted Shibboleth 1.3 SP.
<glossterm>index (the index of the array)</glossterm> */
'sp-provider-id' =&gt; array(
<glossdef> 'host' =&gt; 'sp.example.org'
<para>The entity ID of the hosted SP entity.</para> )
</glossdef> </programlisting>
</glossentry> </example>
<glossentry> <section>
<glossterm>host</glossterm> <title>Mandatory fields</title>
<glossdef> <glosslist>
<para>The hostname of the server running this Shibboleth 1.3 SP. <glossentry>
This option allows simpleSAMLphp to automatically discover which <glossterm>index (the index of the array)</glossterm>
SP metadata to use, when it runs multiple virtual hosts.</para>
</glossdef> <glossdef>
</glossentry> <para>The entity ID of the hosted SP entity.</para>
</glosslist> </glossdef>
</glossentry>
<glossentry>
<glossterm>host</glossterm>
<glossdef>
<para>The hostname of the server running this Shibboleth 1.3 SP.
This option allows simpleSAMLphp to automatically discover which
SP metadata to use, when it runs multiple virtual hosts.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
</section> </section>
<section> <section>
...@@ -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