From 2dc7dd55d01868bc4a84d65a49f367011b5bc794 Mon Sep 17 00:00:00 2001
From: Ketil Albertsen <ketil.albertsen@uninett.no>
Date: Thu, 27 Mar 2008 17:38:42 +0000
Subject: [PATCH] Language check and correction of a number of errors.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@458 44740490-163a-0410-bde0-09ae8108e29a
---
docs/source/simplesamlphp-sp.xml | 386 ++++++++++++++++---------------
1 file changed, 203 insertions(+), 183 deletions(-)
diff --git a/docs/source/simplesamlphp-sp.xml b/docs/source/simplesamlphp-sp.xml
index 26d254ad2..c4c318d66 100644
--- a/docs/source/simplesamlphp-sp.xml
+++ b/docs/source/simplesamlphp-sp.xml
@@ -19,7 +19,7 @@
</articleinfo>
<note>
- <para>This document is in progress of beeing updated to correspond to
+ <para>This document is in progress of being updated to correspond to
simpleSAMLphp version 1.0. simpleSAMLphp version 1.0 is scheduled to be
released in March 2008.</para>
</note>
@@ -46,55 +46,55 @@
<title>Introduction</title>
<para>simpleSAMLphp can run as both a SAML 2.0 Service Provider and as a
- Shibboleth 1.3 Service Provider. The configuration and metadata would be
- somewhat different, therefore there are separate chapter for the two,
- although the configuration is similar.</para>
+ Shibboleth 1.3 Service Provider. Although the configuration is similar for
+ the two alternatives, there are some differences in configuration and
+ metadata differs somewhat, so they are treated in separate chapters.</para>
</section>
<section>
- <title>Enabling the Service Provider functionality</title>
+ <title>Selecting the desired Service Provider functionality</title>
- <para>The SAML 2.0 SP functionality is enabled per default. If you want to
- setup a shibboleth 1.3 SP, you shuold disable SAML 2.0 SP and enable Shib
- 1.3 SP. In <filename>config.php</filename>:</para>
+ <para>Your identity provider (IdP) may offer user authentication either
+ using the SAML 2.0 protocol, or the older Shibboleth 1.3 protocol.</para>
+
+ <para>SAML 2.0 SP functionality is enabled by default. If this is what you
+ want to use, leave the default configuration unmodified.</para>
+
+ <para>To setup a Shibboleth 1.3 SP, you must disable SAML 2.0 SP and
+ enable Shib 1.3 SP in <filename>config.php</filename>:</para>
<programlisting>'enable.saml20-sp' => false,
'enable.saml20-idp' => false,
'enable.shib13-sp' => true,
'enable.shib13-idp' => false,</programlisting>
-
- <para>If you will be using SAML 2.0 SP, leave the enable config as
- default.</para>
</section>
<section>
<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
- two metadata files. <filename>saml20-sp-hosted.php</filename> and
- <filename>saml20-idp-remote.php</filename>.
- <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>
+ <para>To set up a SAML 2.0 SP, configure two metadata files:
+ <filename>saml20-sp-hosted.php</filename> and
+ <filename>saml20-idp-remote.php</filename>. The former represents the SAML
+ entity of your SP, the latter lists all the SAML 2.0
+ IdPs you trust to authenticate users, and how to connect to them.</para>
<section>
<title>Configuring SAML 2.0 SP Hosted metadata</title>
- <para>You need to know at least two variables to be able to setup this
- metadata. You need to know the hostname of the server you are using, and
- you need to set an entity ID for this server. Talk to the people running
- the IdP of what entity ID you should use.</para>
+ <para>To se tup these metadata, you must know the host name of your
+ web server, and select an entity ID for this server. The IdP may impose
+ restrictions on your choice of entity ID.</para>
<note>
- <para>Feide has special rules for setting entity IDs. These rules and
- instructions on how to select an entity ID to use in Feide is
- documented in this document:</para>
+ <para>Feide has special rules for setting entity IDs. The rules and
+ instructions on how to select an entity ID to use in Feide are
+ documented in the fact sheet:</para>
<itemizedlist>
<listitem>
- <para><ulink url="http://docs.feide.no/fs-0051-1.0-en.html">Feide
- entity names (in norwegian)</ulink></para>
+ <para><ulink url="http://docs.feide.no/fs-0051--en.html">Regulations for
+ SAML 2.0 entityIDs
+ for Feide Services</ulink> (Feide Fact Sheet #51)</para>
</listitem>
</itemizedlist>
</note>
@@ -129,21 +129,21 @@
<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>
+ configuration to use in a specific scenario, by mapping current hostname
+ in the URL sent by the end user client to the <literal>host</literal>
entry in the metadata.</para>
- <para>Below is a description of the mandatory and optional fields in the
+ <para>Below is a description of mandatory and optional fields in the
SAML 2.0 SP hosted metadata.</para>
<section>
<title>Mandatory metadata fields</title>
- <para>These field are required to be included in the metadata:</para>
+ <para>These metadata fields are required:</para>
<glosslist>
<glossentry>
- <glossterm>key (the key of the associative array)</glossterm>
+ <glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
<para>The entity ID of the hosted SP entity.</para>
@@ -154,7 +154,7 @@
<glossterm>host</glossterm>
<glossdef>
- <para>The hostname of the server running this SAML 2.0 SP. This
+ <para>Host name of the web server running this SAML 2.0 SP. This
option allows simpleSAMLphp to automatically discover which SP
metadata to use, when it runs multiple virtual hosts.</para>
</glossdef>
@@ -173,15 +173,16 @@
<glossdef>
<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
- the default configuration.</para>
+ this is, or do not require a specific format, leave the default
+ value unmodified.</para>
<para>If you leave out this entry, the default value
<literal>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</literal>
- would be used in the authentication request. If you set the
- value to <code>null</code>, the
- <literal>samlp:NameIDPolicy</literal> element would be
+ is used in the authentication request. If you set the
+ value to <literal>null</literal>, the
+ <literal>samlp:NameIDPolicy</literal> element is
completely removed from the request.</para>
+
</glossdef>
</glossentry>
@@ -189,9 +190,8 @@
<glossterm>ForceAuthn</glossterm>
<glossdef>
- <para>Force authentication is a parameter that allows you to
- force re-authentication of users even if the user has a SSO
- session at the IdP.</para>
+ <para>Force authentication allows you to force re-authentication
+ of users even if the user has a SSO session at the IdP.</para>
</glossdef>
</glossentry>
@@ -213,7 +213,7 @@
<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
+ sign the authentication requests, you will need a
keypair/certificate at the SP.</para>
<glosslist>
@@ -221,9 +221,8 @@
<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>
+ <para>Boolean, default <literal>false</literal>. To turn on signing of
+ authentication requests, set this flag to true.</para>
</glossdef>
</glossentry>
@@ -231,8 +230,7 @@
<glossterm>privatekey</glossterm>
<glossdef>
- <para>The filename of the privatekey to be used for
- singing.</para>
+ <para>File name of private key to be used for singing.</para>
</glossdef>
</glossentry>
@@ -240,11 +238,10 @@
<glossterm>certificate</glossterm>
<glossdef>
- <para>The filename of the certificate which corresponds to the
- privatekey. This is highly optional, and the certificate is not
- used right now, but is reserved for future use. Then the
- certificate will be used to generate SAML 2.0 Metadata to export
- to the IdP.</para>
+ <para>File name of certificate corresponding to the private key.
+ Use of certificates is not yet implemented in simpleSAMLphp, but
+ is reserved for future use; the certificate will be used to
+ generate SAML 2.0 Metadata for export to the IdP.</para>
</glossdef>
</glossentry>
</glosslist>
@@ -262,7 +259,8 @@
<title>Configuring SAML 2.0 IdP Remote metadata</title>
<para>The metadata file <filename>saml20-idp-remote.php</filename>
- represent the SAML 2.0 IdPs that your service provider trust.</para>
+ represent the SAML 2.0 IdPs that your service provider trust to
+ authenticate users of your service.</para>
<example>
<title>Example of metadata for trusted remote SAML 2.0 IdP</title>
@@ -274,26 +272,26 @@
* Example simpleSAMLphp SAML 2.0 IdP
*/
'idp-entity-id-simple' => array(
- 'name' => 'Test',
- 'description' => 'Description of this example entry',
-
- 'SingleSignOnService' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
- 'SingleLogoutService' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
- 'certFingerprint' => '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
+ 'name' => 'Test',
+ 'description' => 'Description of this example entry',
+
+ 'SingleSignOnService' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
+ 'SingleLogoutService' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
+ 'certFingerprint' => '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
),</programlisting>
</example>
<section>
<title>Mandatory metadata fields</title>
- <para>These field are required to be included in the metadata:</para>
+ <para>These are the required metadata fields:</para>
<glosslist>
<glossentry>
- <glossterm>key (the key of the associative array)</glossterm>
+ <glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
- <para>The entity ID of the remote IdP.</para>
+ <para>Entity ID of the remote IdP.</para>
</glossdef>
</glossentry>
@@ -301,8 +299,8 @@
<glossterm>name</glossterm>
<glossdef>
- <para>A textual name of the IdP. (used in the SAML 2.0 discovery
- service)</para>
+ <para>A textual name of the IdP. This name is used in the SAML
+ 2.0 discovery service.</para>
</glossdef>
</glossentry>
@@ -310,8 +308,8 @@
<glossterm>description</glossterm>
<glossdef>
- <para>A longer description of the IdP. (used in the SAML 2.0
- discovery service)</para>
+ <para>A longer description of the IdP. The description is used
+ in the SAML 2.0 discovery service.</para>
</glossdef>
</glossentry>
@@ -319,9 +317,10 @@
<glossterm>SingleSignOnService</glossterm>
<glossdef>
- <para>Contact the IdP to get the endpoint URL of this service.
- This is the URL which the user is redirected with the
- AuthnRequest using HTTP-REDIRECT.</para>
+ <para>Endpoint URL for sign on. You should obtain this from the
+ IdP. Your simpleSAMLphp implementation will redirected users who
+ are not yet authenticated to this URL with the AuthnRequest
+ using HTTP-REDIRECT.</para>
</glossdef>
</glossentry>
@@ -329,9 +328,9 @@
<glossterm>SingleLogoutService</glossterm>
<glossdef>
- <para>Contact the IdP to get the endpoint URL of this service.
- This is the URL which the user is redirected with the
- LogoutRequest using HTTP-REDIRECT.</para>
+ <para>Endpoint URL for logout. You should obtain this from the
+ IdP. Users who log out from your service is redirected to this
+ URL with the LogoutRequest using HTTP-REDIRECT.</para>
</glossdef>
</glossentry>
@@ -339,15 +338,16 @@
<glossterm>certFingerprint</glossterm>
<glossdef>
- <para>The md5sum of the certificate used by the IdP. If you
- don't know how to compute this, you can leave it as it is, and
- then 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 certiciate, so you can copy and use
- that.</para>
+ <para>The <literal>md5</literal> checksum of the certificate
+ used by the IdP. If you don't know how to compute this, you can
+ leave it as it is, and then 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 certificiate, which you may
+ copy to this metadata parameter.</para>
<para>See <xref linkend="a.fingerprint" /> for an example of how
- to calculate the fingerprint with the openssl tool.</para>
+ to calculate the fingerprint with the <literal>openssl</literal>
+ tool.</para>
</glossdef>
</glossentry>
</glosslist>
@@ -363,10 +363,10 @@
<glossterm>base64attributes</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 the IdP base64 encodesattributes, you may set this
+ parameter to <literal>true</literal>. Base64 encoding should be
+ avoided when not strictly needed, but it allows attributes in
+ any binary format to be exchanged. <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>
@@ -380,30 +380,29 @@
<glossdef>
<para>This corresponds to the SPNameQualifier in the SAML 2.0
specification. It allows to give subjects a SP specific
- namespace. This value is seldom used, so if you don't need it,
- do not include it. If you do not include it, simpleSAMLphp will
- include the entityID of your SP as the SPNameQualifier.</para>
+ namespace. This option is rarely used, so if you don't need it,
+ leave it out. When left out, simpleSAMLphp assumes the entityID
+ of your SP as the SPNameQualifier.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
- <title>Fields for requireing signed LogoutRequests</title>
+ <title>Fields for requiring 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>
+ sign the authentication requests, you must supply a
+ keypair/certificate to 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>
+ <para>Boolean, default <literal>false</literal>. To turn on signing authentication
+ requests, set this flag to true.</para>
</glossdef>
</glossentry>
@@ -411,7 +410,7 @@
<glossterm>privatekey</glossterm>
<glossdef>
- <para>The filename of the privatekey to be used for
+ <para>File name of the private key to be used for
singing.</para>
</glossdef>
</glossentry>
@@ -420,8 +419,8 @@
<glossterm>certificate</glossterm>
<glossdef>
- <para>The filename of the certificate which corresponds to the
- privatekey.</para>
+ <para>File name of certificate corresponding to the private
+ key.</para>
</glossdef>
</glossentry>
</glosslist>
@@ -438,10 +437,10 @@
<section>
<title>Setting the default SAML 2.0 IdP</title>
- <para>In the global configuration (<filename>config.php</filename>)
- there is a parameter to set the default IdP to use. Alternatively you
- can specify which IdP to use in a parameter to the initSSO.php script
- when you initiate logon in your application.</para>
+ <para>The global configuration (<filename>config.php</filename>) holds a
+ parameter to set the default IdP to use. Alternatively you can specify
+ which IdP to use in a parameter to the initSSO.php script when you
+ initiate logon in your application.</para>
<para>Here is an example from <filename>config.php</filename>:</para>
@@ -454,11 +453,11 @@
<section>
<title>Using the SAML 2.0 IdP Discovery Service</title>
- <para>If you want end users to be able to select one of all the
- specified entries in IdP remote metadata, you can set the default IdP to
- be null, then simpleSAMLphp will initiate the builtin IdP discovery
- service to let the user select IdP. Here is the neccessary configuration
- from <filename>config.php</filename>:</para>
+ <para>If you want end users to be able to select one of several
+ specified entries in IdP remote metadata, set the default IdP to be
+ null. simpleSAMLphp will then use its builtin IdP discovery service to
+ let the user select IdP. Here is the neccessary configuration from
+ <filename>config.php</filename>:</para>
<programlisting> 'default-saml20-idp' => null,</programlisting>
</section>
@@ -467,18 +466,20 @@
<section>
<title>Configuring metadata for Shibboleth 1.3 SP</title>
- <para>When you are setting up a Shibboleth 1.3 SP, you need to configure
- two metadata files. shib13-sp-hosted.php and shib13-idp-remote.php.
- shib13-sp-hosted.php represents the SAML entity of the service provider
- itself, while the shib13-idp-remote.php metadata lists all the trusted
- SAML 2.0 IdPs and contains information on how to connect to them.</para>
+ <para>To set up a Shibboleth 1.3 SP, configure two metadata files.
+ shib13-sp-hosted.php and shib13-idp-remote.php.The former represents the
+ SAML entity of your service provider, the latter lists all the trusted
+ Shibboleth 1.3 IdPs and how to connect to them.</para>
+
+ <para>Note: Shibboleth 2.0 IdPs should be configured as SAML 2.0
+ IdPs.</para>
<section>
<title>Configuring Shibboleth 1.3 SP Hosted metadata</title>
- <para>In the hosted metadata (shib13-sp-hosted.php) you will need to
- configure two parameters, the entity ID and the hostname of the server
- running this SP.</para>
+ <para>Two parameters, the entity ID and the host name of the web server
+ running this SP, are configured in the hosted metadata
+ (<literal>shib13-sp-hosted.php</literal>).</para>
<example>
<title>Shibboleth 1.3 SP hosted metadata</title>
@@ -487,7 +488,7 @@
* Example of hosted Shibboleth 1.3 SP.
*/
'sp-provider-id' => array(
- 'host' => 'sp.example.org'
+ 'host' => 'sp.example.org'
)
</programlisting>
</example>
@@ -520,25 +521,25 @@
<section>
<title>Configuring Shibboleth 1.3 IdP Remote metadata</title>
- <para>Here (shib13-idp-remote.php) you configure which IdPs that you
- trust.</para>
+ <para>Here (<filename>shib13-idp-remote.php</filename>) you configure
+ which IdPs that you trust to authenticate users of your service.</para>
<example>
<title>Example of remote Shibboleth 1.3 IdP metadata</title>
- <programlisting>'theproviderid-of-the-idp' => array(
- 'SingleSignOnService' => 'https://idp.example.org/shibboleth-idp/SSO',
- 'certFingerprint' => 'c7279a9f28f11380509e072441e3dc55fb9ab864'
+ <programlisting>'theproviderid-of-the-idp' => array(
+ 'SingleSignOnService' => 'https://idp.example.org/shibboleth-idp/SSO',
+ 'certFingerprint' => 'c7279a9f28f11380509e072441e3dc55fb9ab864'
)</programlisting>
</example>
<glosslist>
<glossentry>
- <glossterm>index (the index of the array)</glossterm>
+ <glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
- <para>The providerID of this Shibboleth 1.3 IdP entity. In this
- example the entity ID is set to
+ <para>The <literal>providerID</literal> of this Shibboleth 1.3 IdP
+ entity. In this example the entity ID is set to
<literal>urn:mace:switch.ch:aaitest:dukono.switch.ch</literal>.</para>
</glossdef>
</glossentry>
@@ -561,11 +562,12 @@
<glossterm>certFingerprint</glossterm>
<glossdef>
- <para>The md5sum of the certificate used by the IdP. If you don't
- know how to compute this, you can leave it as it is, and then
- 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
- certiciate, so you can copy and use that.</para>
+ <para>The <literal>md5</literal> checksum of the certificate used
+ by the IdP. If you don't know how to compute this, you can leave
+ it as it is, and then 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 certificiate, which you may copy to this
+ metadata parameter.</para>
<para>See <xref linkend="a.fingerprint" /> for an example of how
to calculate the fingerprint with the openssl tool.</para>
@@ -580,15 +582,15 @@
<para>Before you can run the test examples, you need the people running
the IdP to load the metadata for your SP. If you run Shibboleth 1.3 SP,
- you will need to manually create metadata for your SP and send to the IdP,
- if you use SAML 2.0, metadata can be generated automatically.</para>
+ you must manually create metadata for your SP and send to the IdP. If you
+ use SAML 2.0, metadata can be generated automatically.</para>
<section>
- <title>Automatically generation of SP metadata for SAML 2.0</title>
+ <title>Automatic generation of SAML 2.0 SP metadata</title>
<para>On the installation page there is a link named "Look at your SAML
- 2.0 SP metadata". Click there to look at the metadata for your SP. Send
- this metadata document to the IdP and ask them to load it.</para>
+ 2.0 SP metadata". Click to inspect the metadata for your SP. Send this
+ metadata document to the IdP and ask them to load it.</para>
<screenshot>
<screeninfo>Example of automatically generated SAML 2.0
@@ -614,27 +616,26 @@
</mediaobject>
</screenshot>
- <para>Enter your email address and click the button to send the metadata
- to Feide. Remeber to get in contact with Feide to discuss your new
- service, and how you can be connected to Feides test environment.</para>
+ <para>Enter your email address and click the button "Send my metadata to
+ Feide". Remeber to get in contact with Feide to discuss your new
+ service, and how you can be connected to Feide's test environment. To
+ test your service, you must have a valid Feide login name. If you are
+ not affiliated with a Feide host institution, you may obtain a test user
+ identity from Feide.</para>
</section>
</section>
<section>
<title>Test the SAML 2.0 SP examples</title>
- <para>When you have installed simpleSAMLphp, configured apache, and setup
- metadata and exchanged metadata with the IdP you are ready to test the
- example service that is included in the simpleSAMLphp installation.</para>
-
- <para>On the installation page of simpleSAMLphp as you remember from the
- installation guide, there is a link to a Shibboleth 1.3 and SAML 2.0
- example. When you click on that example, you should be automatically
- redirected to the IdP. Then login as usual, and you should get back to a
- status page with .</para>
+ <para>After you have installed simpleSAMLphp, configured Apache, set up
+ metadata and exchanged metadata with the IdP, you are ready to test the
+ sample service included in the simpleSAMLphp distribution.</para>
- <para>You should be redirected to the IdP. Login, and you should be sent
- back and shown all the attributes sent form the IdP.</para>
+ <para>The installation page of simpleSAMLphp has a link to a Shibboleth
+ 1.3 and a SAML 2.0 sample service. When you click the link, you should be
+ automatically redirected to the IdP. Login, and you should be sent back
+ and shown all the attributes sent form the IdP.</para>
<figure>
<title>Screenshot of the status page after an user have succesfully
@@ -653,40 +654,45 @@
<section>
<title>Integrating authentication with your own application</title>
- <para>You will need to hook some code into your application executed for
- every protected HTTP request. The flow in that code goes like:</para>
+ <para>For those web resources you want to protect, you must add a few
+ lines of PHP code:</para>
<itemizedlist>
<listitem>
- <para>Check whether the user is authenticated or not.</para>
+ <para>Check whether the user is already authenticated.</para>
</listitem>
<listitem>
- <para>If the user is not authenticated, and it should be, then
- redirect the user to the initSSO.php script with the appropriate
- parameters. In particular the RelayState that tells the URL to return
- to after login.</para>
+ <para>If the user is not authenticated, but should be for this
+ resource, redirect him to the <filename>initSSO.php</filename> script
+ with the appropriate parameters. Note particularly the
+ <literal>RelayState</literal> specifying the treturn URL after
+ login.</para>
</listitem>
<listitem>
- <para>If the user is authenticated then your done, map to your own
- user database if neccessary, and access the attributes from the
- session object as you like.</para>
+ <para>If authentication is successful, but you need to determine the
+ user's authorization, read the user attributes supplied by the IdP
+ from the session object. If you need user attributes beyond those
+ supplied by the IdP, you may maintain an exteded user description in
+ you own database, using the (authenticated) user ID as a key.</para>
</listitem>
</itemizedlist>
- <para>Here are some example code from the included example that you can
- reuse:</para>
+ <para>Sample code:</para>
<para>We start off with including a common file _include.php. All this
- file is doing is adding simpleSAMLphp to the classpath. If you want you
- can do this in php.ini instead. Or you can include all the content of
- _include.php in the application it self.</para>
+ file does is to add simpleSAMLphp to the classpath. Alternately, this can
+ be configured in <filename>php.ini</filename>, or the contents of
+ <filename>_include.php</filename> can be included directly in the
+ application code.</para>
+
+ <para></para>
<programlisting>require_once('../_include.php');</programlisting>
- <para>Including class specifications. This is for SAML 2.0, for shibboleth
- look at the shibboleth example in
+ <para>Including class specifications. This is for SAML 2.0; for Shibboleth
+ look at the Shibboleth example in
<filename>www/example-simple/shib13-example.php</filename>.</para>
<programlisting>require_once('SimpleSAML/Utilities.php');
@@ -694,33 +700,45 @@ require_once('SimpleSAML/Session.php');
require_once('SimpleSAML/XHTML/Template.php');
</programlisting>
- <para>Then enable using PHP Sessions and load configuration with
- simpleSAMLphp. You can copy this lines into your application without
- changes:</para>
+ <para>Enable PHP Sessions and load configuration with simpleSAMLphp. You
+ can copy this lines into your application without changes:</para>
<programlisting>/* Load simpleSAMLphp, configuration and metadata */
$config = SimpleSAML_Configuration::getInstance();
$session = SimpleSAML_Session::getInstance(true);</programlisting>
- <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
- parameter. If you are authenticated, then retrieve all the attributes from
- the session object. You may want to look closer at the attributes array,
- so why don't you print_r it out right away to get the structure...</para>
+ <para>Then check whether the session is valid. If not, redirect the user
+ to the IdP, specifying the <filename>initSSO.php</filename> script (for
+ SAML 2.0 or Shibboleth 1.3, respectively). adding the current URL as a
+ <literal>RelayState</literal> parameter. The user will leave your web page
+ temporarily. When he returns after successful authentication, there will
+ be a valid session, and the body of the <code>if</code> statement is
+ skipped.</para>
+
+ <para>After successful athentication, user attributes supplied by the IdP
+ are available in session object. To take a closer look at the attributes
+ array, you may print it out...</para>
<programlisting>/* Check if valid local session exists.. */
if (!isset($session) || !$session->isValid('saml2') ) {
- SimpleSAML_Utilities::redirect(
- '/' . $config->getBaseURL() .
- 'saml2/sp/initSSO.php',
- array('RelayState' => SimpleSAML_Utilities::selfURL())
- );
+ SimpleSAML_Utilities::redirect(
+ '/' . $config->getBaseURL() .
+ 'saml2/sp/initSSO.php',
+ array('RelayState' => SimpleSAML_Utilities::selfURL())
+ );
}
$attributes = $session->getAttributes();
print_r($attributes);
</programlisting>
+ <para>(Obviously, printing out all attributes this way would be done in a
+ test phase only!)</para>
+
+ <para>Each attribute name can be used as an index into $attributes to
+ obtain the value. Every attribute value is an array - a single-valued
+ attribute is an array of a single element.</para>
+
<section>
<title>Upgrading service integration from version 0.5 to 1.0</title>
@@ -738,11 +756,12 @@ print_r($attributes);
<section>
<title>Support</title>
- <para>If you have problems to get this work, or want to discuss
- simpleSAMLphp with other users of the software you are lucky! Around
- simpleSAMLphp there is a great Open source community, and you are welcome
- to join! Both for asking question, answer other questions, request
- improvements or contribute with code or plugins of your own.</para>
+ <para>If you need help to make this work, or want to discuss simpleSAMLphp
+ with other users of the software, you are fortunate: Around simpleSAMLphp
+ there is a great Open source community, and you are welcome to join! The
+ forums are open for you to ask questions, contribute answers other further
+ questions, request improvements or contribute with code or plugins of your
+ own.</para>
<itemizedlist>
<listitem>
@@ -771,10 +790,11 @@ print_r($attributes);
<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>
+ <para>If you have obtained a certificate file, and want to calculate the
+ fingerprint of the file, you can use the <literal>openssl</literal>
+ command:</para>
- <screen>cert]$ cat server.crt|openssl x509 -fingerprint
+ <screen>$ 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>
--
GitLab