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

SP doc to markdown 

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1216 44740490-163a-0410-bde0-09ae8108e29a
parent b596eb63
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/simplesamlphp-sp.txt 0 → 100644
+ 754
− 0
View file @ 513a8ca5
Theming the user interface in SimpleSAMLphp
===========================================
<!--
This file is written in Markdown syntax.
For more information about how to use the Markdown syntax, read here:
http://daringfireball.net/projects/markdown/syntax
-->
* Version: `$Id$`
simpleSAMLphp documentation
---------------------------
This document is part of the simpleSAMLphp documentation suite.
-
[List of all simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)
This document assumes that you already have a installation of
simpleSAMLphp. Before you continue make sure all the required
entries in the check list at the buttom is showing green light.
Introduction
------------
simpleSAMLphp can run as both a SAML 2.0 Service Provider and as a
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.
Selecting the desired Service Provider functionality
----------------------------------------------------
Your identity provider (IdP) may offer user authentication either
using the SAML 2.0 protocol, or the older Shibboleth 1.3 protocol.
SAML 2.0 SP functionality is enabled by default. If this is what
you want to use, leave the default configuration unmodified.
To setup a Shibboleth 1.3 SP, you must disable SAML 2.0 SP and
enable Shib 1.3 SP in `config.php`:
'enable.saml20-sp' => false,
'enable.saml20-idp' => false,
'enable.shib13-sp' => true,
'enable.shib13-idp' => false,
Configuring metadata for SAML 2.0 SP
------------------------------------
To set up a SAML 2.0 SP, configure two metadata files:
`saml20-sp-hosted.php` and `saml20-idp-remote.php`. 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.
## Configuring SAML 2.0 SP Hosted metadata
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.
**Example&nbsp;1.&nbsp;Example of metadata for hosted SAML 2.0 SP**
Here is an example of the metadata file:
/*
* Example of a hosted SP
*/
'sp-entityid' => array(
'host' => 'sp.example.org'
)
**Example&nbsp;2.&nbsp;Real life example**
Here is a real life example from Feide:
'urn:mace:feide.no:services:no.feide.foodle' => array(
'host' => 'foodle.feide.no',
),
Here the service run on the host `foodle.feide.no` and have the
entity ID `urn:mace:feide.no:services:no.feide.foodle`.
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 mapping current
hostname in the URL sent by the end user client to the `host` entry
in the metadata.
Below is a description of mandatory and optional fields in the SAML
2.0 SP hosted metadata.
### Mandatory metadata fields
These metadata fields are required:
index in the `$metadata` array
: The entity ID of the hosted SP entity.
: simpleSAMLphp supports dynamic entityIDs that matches a URL
where simpleSAMLphp automatically generates metadata for the hosted
entity. To enable this functionality, set the index to be
`__DYNAMIC:1__`. The index needs to be unique, so when you have
multiple entries, increase the integer after the colon. When the
index `__DYNAMIC:1__` is used, the resulting generated entity
becomes something like:
: https://sp.example.org/simplesaml/saml2/sp/metadata.php
host
: Host name of the server running this SP. One of your metadata
entries can have the value `__DEFAULT__`. A default entry will be
used when no other entry matches the current hostname.
### Optional metadata fields
These fields can be left out if not needed.
NameIDFormat
: The NameIDFormat in the request. If you don't know what this
is, or do not require a specific format, leave the default value
unmodified.
: If you leave out this entry, the default value
`urn:oasis:names:tc:SAML:2.0:nameid-format:transient` is used in
the authentication request. If you set the value to `null`, the
`samlp:NameIDPolicy` element is completely removed from the
request.
ForceAuthn
: Force authentication allows you to force re-authentication of
users even if the user has a SSO session at the IdP.
AuthnContextClassRef
: The SP can request authentication with a specific
authentication context class. One example of usage could be if the
IdP supports both username/password authentication as well as
software-PKI.
attributemap
: Mapping table for translating attribute names. For further
information, see the *Advances Features* document.
attributealter
: Table of custom functions that injects or modifies attributes.
For further information, see the *Advances Features* document.
attributes
: Array of attributes sent to the SP. If this field is not set,
the SP receives all attributes available at the IdP.
IsPassive
: IsPassive allows you to enable passive authentication by
default for this SP.
AssertionConsumerService
: Override the default URL for the AssertionConsumerService for
this SP. This is an absolute URL. The default value is
`<simpleSAMLphp-root>/saml2/sp/AssertionConsumerService.php`
: Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.
SingleLogoutService
: Override the default URL for the SingleLogoutService for this
SP. This is an absolute URL. The default value is
`<simpleSAMLphp-root>/saml2/sp/SingleLogoutService.php`
: Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.
idpdisco.url
: Set which IdP discovery service this SP should use. If this is
unset, the IdP discovery service specified in the global option
`idpdisco.url.saml20` in `config/config.php` will be used. If that
one is also unset, the builtin default discovery service will be
used.
privatekey
: File name of private key to be used for signing messages.
certificate
: File name of certificate corresponding to the private key. This
certificate will be included in generated metadata.
privatekey\_pass
: Optional field with the passphrase for the private key.
### Fields for signing and validating messages
simpleSAMLphp only signs authentication responses by default.
Signing of authentication requests, logout requests and logout
responses can be enabled by setting the `redirect.sign` option.
Validation of received messages can be enabled by the
`redirect.validate` option. Note that if you want to sign messages,
you will need a keypair/certificate at the SP.
These options set the default for this SP, but options for each IdP
can be set in `saml20-idp-remote`.
redirect.sign
: Boolean, default `false`. To turn on signing of authentication
requests, logout requests and logout responses, set this flag to
true.
: This option can be overridden by the `redirect.sign` option in
`saml20-idp-remote`.
redirect.validate
: Boolean, default `false`. To turn on validation of received
logout requests and logout responses, set this flag to true.
: This option can be overridden by the `redirect.validate` option
in `saml20-idp-remote`.
**Example&nbsp;3.&nbsp;Example of configured signed messages**
'redirect.sign' => true,
'privatekey' => 'server.pem',
## Configuring SAML 2.0 IdP Remote metadata
The metadata file `saml20-idp-remote.php` represent the SAML 2.0
IdPs that your service provider trust to authenticate users of your
service.
**Example&nbsp;4.&nbsp;Example of metadata for trusted remote SAML 2.0 IdP**
Here is an example of a metadata entry for a remote trusted IdP:
/*
* 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'
),
**Example&nbsp;5.&nbsp;More complex example**
Here is an example with more configuration:
/*
* Example simpleSAMLphp SAML 2.0 IdP
*/
'idp-entity-id' => 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',
'base64attributes' => true,
/*
* When redirect.validate is true the certificate of the IdP will be used
* to verify all messages received with the HTTPRedirect binding.
*
* The certificate from the IdP must be installed in the cert directory
* before verification can be done.
*/
'redirect.validate' => false,
'certificate' => "idp.example.org.crt",
/*
* It is possible to relax some parts of the validation of SAML2 messages.
* To relax a part, add the id to the 'saml2.relaxvalidation' array.
*
* Valid ids:
* - 'unknowncondition' Disables errors when encountering unknown <Condition> nodes.
* - 'nosubject' Ignore missing <Subject> in <Assertion>.
* - 'noconditions' Ignore missing <Conditions> in <Assertion>.
* - 'noauthnstatement' Ignore missing <AuthnStatement> in <Assertion>.
* - 'noattributestatement' Ignore missing <AttributeStatement> in <Assertion>.
*
* Example:
* 'saml2.relaxvalidation' => array('unknowncondition', 'noattributestatement'),
*
* Default:
* 'saml2.relaxvalidation' => array(),
*/
'saml2.relaxvalidation' => array(),
),
### Mandatory metadata fields
These are the required metadata fields:
index in the `$metadata` array
: Entity ID of the remote IdP.
name
: A textual name of the IdP. This can contain a string or an
associative array of language code => translation pairs. This name
is used in the SAML 2.0 discovery service.
description
: A longer description of the IdP. This can contain a string or
an associative array of language code => translation pairs. The
description is used in the SAML 2.0 discovery service.
SingleSignOnService
: 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.
SingleLogoutService
: 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.
certFingerprint
: The `sha1` 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.
: It is also possible to add an array of valid fingerprints,
where any fingerprints in that array is accepted as valid. This can
be used to update the certificate of the IdP without having to
update every SP at that exact time. Instead, one can update the SPs
with the new fingerprint, and only update the certificate after
every SP is updated.
: See
[Appendix&nbsp;A, *Calculating the fingerprint of a certificate*](#a.fingerprint "A. Calculating the fingerprint of a certificate")
for an example of how to calculate the fingerprint with the
`openssl` tool.
### Optional metadata fields
These fields can be left out if not needed.
base64attributes
: If the IdP base64 encodesattributes, you may set this parameter
to `true`. Base64 encoding should be avoided when not strictly
needed, but it allows attributes in any binary format to be
exchanged.
: ### Warning
: If you are using simpleSAMLphp at the IdP, remember to set the
parameter in the metadata at the IdP to be the same.
SPNameQualifier
: This corresponds to the SPNameQualifier in the SAML 2.0
specification. It allows to give subjects a SP specific 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.
attributemap
: Mapping table for translating attribute names. For further
information, see the *Advances Features* document.
attributealter
: Table of custom functions that injects or modifies attributes.
For further information, see the *Advances Features* document.
certificate
: Name of certificate file in PEM format, in the `certs`
directory. Used for decrypting assertions and as an alternative to
certFingerprint for validating signatures.
: This option is also required if validating signed logout
requests/responses from this IdP.
assertion.encryption
: Set to true if the remote idp encrypts assertions. Encrypted
assertions are decrypted regardless of the value this field if the
neccesary certificate or key is available, but if it is set to true
and an unencrypted assertion is recieved an exception is raised.
sharedkey
: Used for optional symmetric decryption of assertions. Currently
the algorithm is hardcoded to AES128\_CBC/RIJNDAEL\_128 which uses
up to 128 bit for the passphrase/key. Not necessary if the idp uses
a sessionkey which is encrypted by the idp's private key.
caFile
: Alternative to certFingerprint. Allows you to specify a file
with root certificates, and responses from the service be validated
against these certificates. Note that simpleSAMLphp doesn't support
chains with any itermediate certificates between the root and the
certificate used to sign the response.
icon
: An icon for this IdP. This is a URL to a icon which will be
displayed next to this IdP in the IdP discovery service. The URL
can be absolute or relative. If it is relative, it will be relative
to the simpleSAMPphp www-directory.
### Fields for signing and validating messages
simpleSAMLphp only signs authentication responses by default.
Signing of authentication requests, logout requests and logout
responses can be enabled by setting the `redirect.sign` option.
Validation of received messages can be enabled by the
`redirect.validate` option. Note that if you want to sign messages,
you will need a keypair/certificate at the SP.
These options overrides the options set in `saml20-sp-hosted`.
redirect.sign
: Boolean, default `false`. To turn on signing of authentication
requests, logout requests and logout responses, set this flag to
true.
: This option overrides the `redirect.sign` option in
`saml20-sp-hosted`.
redirect.validate
: Boolean, default `false`. To turn on validation of received
logout requests and logout responses, set this flag to true.
: This option overrides the `redirect.validate` option in
`saml20-sp-hosted`.
**Example&nbsp;6.&nbsp;Example of configuration for validating messages**
'redirect.validate' => true,
'certificate' => 'server.crt'
## Setting the default SAML 2.0 IdP
The global configuration (`config.php`) 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.
Here is an example from `config.php`:
'default-saml20-idp' => 'sam.feide.no',
The configuration above will use the IdP configured in IdP Remote
metadata with entity ID equal to `sam.feide.no`.
## Using the SAML 2.0 IdP Discovery Service
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
`config.php`:
'default-saml20-idp' => null,
Configuring metadata for Shibboleth 1.3 SP
------------------------------------------
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.
Note: Shibboleth 2.0 IdPs should be configured as SAML 2.0 IdPs.
## Configuring Shibboleth 1.3 SP Hosted metadata
Two parameters, the entity ID and the host name of the web server
running this SP, are configured in the hosted metadata
(`shib13-sp-hosted.php`).
**Example&nbsp;7.&nbsp;Shibboleth 1.3 SP hosted metadata**
/*
* Example of hosted Shibboleth 1.3 SP.
*/
'sp-provider-id' => array(
'host' => 'sp.example.org'
)
### Mandatory fields
index (the index of the array)
: The entity ID of the hosted SP entity.
: simpleSAMLphp supports dynamic entityIDs that matches a URL
where simpleSAMLphp automatically generates metadata for the hosted
entity. To enable this functionality, set the index to be
`__DYNAMIC:1__`. The index needs to be unique, so when you have
multiple entries, increase the integer after the colon. When the
index `__DYNAMIC:1__` is used, the resulting generated entity
becomes something like:
: https://sp.example.org/simplesaml/shib13/sp/metadata.php
host
: Host name of the server running this SP. One of your metadata
entries can have the value `__DEFAULT__`. A default entry will be
used when no other entry matches the current hostname.
### Optional metadata fields
These fields can be left out if not needed.
AssertionConsumerService
: Override the default URL for the AssertionConsumerService for
this SP. This is an absolute URL. The default value is
`<simpleSAMLphp-root>/shib13/sp/AssertionConsumerService.php`
: Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.
idpdisco.url
: Set which IdP discovery service this SP should use. If this is
unset, the IdP discovery service specified in the global option
`idpdisco.url.shib13` in `config/config.php` will be used. If that
one is also unset, the builtin default discovery service will be
used.
## Configuring Shibboleth 1.3 IdP Remote metadata
Here (`shib13-idp-remote.php`) you configure which IdPs that you
trust to authenticate users of your service.
**Example&nbsp;8.&nbsp;Example of remote Shibboleth 1.3 IdP metadata**
'theproviderid-of-the-idp' => array(
'SingleSignOnService' => 'https://idp.example.org/shibboleth-idp/SSO',
'certFingerprint' => 'c7279a9f28f11380509e072441e3dc55fb9ab864'
)
index in the `$metadata` array
: The `providerID` of this Shibboleth 1.3 IdP entity. In this
example the entity ID is set to
`urn:mace:switch.ch:aaitest:dukono.switch.ch`.
SingleSignOnService
: Contact the IdP to get the endpoint URL of this service. This
is the URL which the user is redirected with the request for
authentication.
: ### Note
: The name of this parameter changed from SingleSignOnUrl to
SingleSignOnService betwen simpleSAMLphp version 0.5 and 1.0.
certFingerprint
: The `sha` 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.
: It is also possible to add an array of valid fingerprints,
where any fingerprints in that array is accepted as valid. This can
be used to update the certificate of the IdP without having to
update every SP at that exact time. Instead, one can update the SPs
with the new fingerprint, and only update the certificate after
every SP is updated.
: See
[Appendix&nbsp;A, *Calculating the fingerprint of a certificate*](#a.fingerprint "A. Calculating the fingerprint of a certificate")
for an example of how to calculate the fingerprint with the openssl
tool.
caFile
: Alternative to certFingerprint. Allows you to specify a file
with root certificates, and responses from the service be validated
against these certificates. Note that simpleSAMLphp doesn't support
chains with any itermediate certificates between the root and the
certificate used to sign the response.
icon
: An icon for this IdP. This is a URL to a icon which will be
displayed next to this IdP in the IdP discovery service. The URL
can be absolute or relative. If it is relative, it will be relative
to the simpleSAMPphp www-directory. This field is optional.
Exchange metadata with the IdP
------------------------------
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 must manually create metadata for your SP and send to the
IdP. If you use SAML 2.0, metadata can be generated automatically.
## Automatic generation of SAML 2.0 SP metadata
On the installation page there is a link named "Look at your SAML
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.
![image](resources/simplesamlphp-sp/saml2metadata.png)
If you are connected to Feide, and put one of Feides entity IDs as
default IdP, you will see an additional section on this page:
![image](resources/simplesamlphp-sp/saml2metadata-feide.png)
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.
Test the SAML 2.0 SP examples
-----------------------------
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.
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.
**Figure&nbsp;1.&nbsp;Screenshot of the status page after an user have succesfully authenticated**
![Screenshot of the status page after an user have succesfully authenticated](resources/simplesamlphp-sp/screenshot-example.png)
Integrating authentication with your own application
----------------------------------------------------
For those web resources you want to protect, you must add a few
lines of PHP code:
- Check whether the user is already authenticated.
-
If the user is not authenticated, but should be for this resource,
redirect him to the `initSSO.php` script with the appropriate
parameters. Note particularly the `RelayState` specifying the
treturn URL after login.
-
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.
Sample code:
We start off with including a common file \_include.php. All this
file does is to add simpleSAMLphp to the classpath. Alternately,
this can be configured in `php.ini`, or the contents of
`_include.php` can be included directly in the application code.
require_once('../_include.php');
Including class specifications. This is for SAML 2.0; for
Shibboleth look at the Shibboleth example in
`www/example-simple/shib13-example.php`.
require_once('SimpleSAML/Utilities.php');
require_once('SimpleSAML/Session.php');
require_once('SimpleSAML/XHTML/Template.php');
Enable PHP Sessions and load configuration with simpleSAMLphp. You
can copy this lines into your application without changes:
/* Load simpleSAMLphp, configuration and metadata */
$config = SimpleSAML_Configuration::getInstance();
$session = SimpleSAML_Session::getInstance();
Then check whether the session is valid. If not, redirect the user
to the IdP, specifying the `initSSO.php` script (for SAML 2.0 or
Shibboleth 1.3, respectively). adding the current URL as a
`RelayState` 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 `if` statement is
skipped.
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...
/* 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())
);
}
$attributes = $session->getAttributes();
print_r($attributes);
(Obviously, printing out all attributes this way would be done in a
test phase only!)
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.
## Upgrading service integration from version 0.5 to 1.0
-
[Wiki page describing the differences between integrating a service with simpleSAMLphp 0.5 and simpleSAMLphp 1.0.](https://ow.feide.no/simplesamlphp:spupgrade05to10)
Support
-------
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.
- [simpleSAMLphp homepage (at Feide RnD)](http://rnd.feide.no/simplesamlphp)
- [List of all available simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)
- [Join the simpleSAMLphp user's mailing list](http://rnd.feide.no/content/simplesamlphp-users-mailinglist)
- [Visit and contribute to the simpleSAMLphp wiki](https://ow.feide.no/simplesamlphp:start)
## A.&nbsp;Calculating the fingerprint of a certificate
If you have obtained a certificate file, and want to calculate the
fingerprint of the file, you can use the `openssl` command:
$ cat server.crt|openssl x509 -fingerprint
MD5 Fingerprint=D1:BA:B0:17:66:6D:7F:42:7B:91:1E:22:7E:3A:27:D2
docs/source/simplesamlphp-sp.xml deleted 100644 → 0
+ 0
− 1147
View file @ b596eb63
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
<title>Using simpleSAMLphp as a Service Provider</title>
<articleinfo>
<date>2007-10-15</date>
<pubdate>Sun Nov 2 14:37:37 2008</pubdate>
<author>
<firstname>Andreas Åkre</firstname>
<surname>Solberg</surname>
<email>andreas.solberg@uninett.no</email>
</author>
</articleinfo>
<section>
<title>simpleSAMLphp documentation</title>
<para>This document is part of the simpleSAMLphp documentation
suite.</para>
<itemizedlist>
<listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
all simpleSAMLphp documentation</ulink></para>
</listitem>
</itemizedlist>
<para>This document assumes that you already have a installation of
simpleSAMLphp. Before you continue make sure all the required entries in
the check list at the buttom is showing green light.</para>
</section>
<section>
<title>Introduction</title>
<para>simpleSAMLphp can run as both a SAML 2.0 Service Provider and as a
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>Selecting the desired Service Provider functionality</title>
<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' =&gt; false,
'enable.saml20-idp' =&gt; false,
'enable.shib13-sp' =&gt; true,
'enable.shib13-idp' =&gt; false,</programlisting>
</section>
<section>
<title>Configuring metadata for SAML 2.0 SP</title>
<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>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. 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--en.html">Regulations for SAML
2.0 entityIDs for Feide Services</ulink> (Feide Fact Sheet
#51)</para>
</listitem>
</itemizedlist>
</note>
<example>
<title>Example of metadata for hosted SAML 2.0 SP</title>
<para>Here is an example of the metadata file:</para>
<programlisting>/*
* Example of a hosted SP
*/
'sp-entityid' =&gt; array(
'host' =&gt; 'sp.example.org'
)</programlisting>
</example>
<example>
<title>Real life example</title>
<para>Here is a real life example from Feide:</para>
<programlisting>'urn:mace:feide.no:services:no.feide.foodle' =&gt; array(
'host' =&gt; 'foodle.feide.no',
),
</programlisting>
<para>Here the service run on the host
<literal>foodle.feide.no</literal> and have the entity ID
<literal>urn:mace:feide.no:services:no.feide.foodle</literal>.</para>
</example>
<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 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 mandatory and optional fields in the
SAML 2.0 SP hosted metadata.</para>
<section>
<title>Mandatory metadata fields</title>
<para>These metadata fields are required:</para>
<glosslist>
<glossentry>
<glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
<para>The entity ID of the hosted SP entity.</para>
<para>simpleSAMLphp supports dynamic entityIDs that matches a
URL where simpleSAMLphp automatically generates metadata for the
hosted entity. To enable this functionality, set the index to be
<literal>__DYNAMIC:1__</literal>. The index needs to be unique,
so when you have multiple entries, increase the integer after
the colon. When the index <literal>__DYNAMIC:1__</literal> is
used, the resulting generated entity becomes something
like:</para>
<literallayout>https://sp.example.org/simplesaml/saml2/sp/metadata.php</literallayout>
</glossdef>
</glossentry>
<glossentry>
<glossterm>host</glossterm>
<glossdef>
<para>Host name of the server running this SP. One of your
metadata entries can have the value
<literal>__DEFAULT__</literal>. A default entry will be used
when no other entry matches the current hostname.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<para>These fields can be left out if not needed.</para>
<glosslist>
<glossentry>
<glossterm>NameIDFormat</glossterm>
<glossdef>
<para>The NameIDFormat in the request. If you don't know what
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>
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>
<glossentry>
<glossterm>ForceAuthn</glossterm>
<glossdef>
<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>
<glossentry>
<glossterm>AuthnContextClassRef</glossterm>
<glossdef>
<para>The SP can request authentication with a specific
authentication context class. One example of usage could be if
the IdP supports both username/password authentication as well
as software-PKI.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributemap</glossterm>
<glossdef>
<para>Mapping table for translating attribute names. For further
information, see the <emphasis>Advances Features</emphasis>
document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributealter</glossterm>
<glossdef>
<para>Table of custom functions that injects or modifies
attributes. For further information, see the <emphasis>Advances
Features</emphasis> document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributes</glossterm>
<glossdef>
<para>Array of attributes sent to the SP. If this field is not
set, the SP receives all attributes available at the IdP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>IsPassive</glossterm>
<glossdef>
<para>IsPassive allows you to enable passive authentication by
default for this SP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>AssertionConsumerService</glossterm>
<glossdef>
<para>Override the default URL for the AssertionConsumerService
for this SP. This is an absolute URL. The default value is
<literal>&lt;simpleSAMLphp-root&gt;/saml2/sp/AssertionConsumerService.php</literal></para>
<para>Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SingleLogoutService</glossterm>
<glossdef>
<para>Override the default URL for the SingleLogoutService for
this SP. This is an absolute URL. The default value is
<literal>&lt;simpleSAMLphp-root&gt;/saml2/sp/SingleLogoutService.php</literal></para>
<para>Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>idpdisco.url</glossterm>
<glossdef>
<para>Set which IdP discovery service this SP should use. If
this is unset, the IdP discovery service specified in the global
option <literal>idpdisco.url.saml20</literal> in
<filename>config/config.php</filename> will be used. If that one
is also unset, the builtin default discovery service will be
used.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>privatekey</glossterm>
<glossdef>
<para>File name of private key to be used for signing
messages.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>certificate</glossterm>
<glossdef>
<para>File name of certificate corresponding to the private key.
This certificate will be included in generated metadata.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>privatekey_pass</glossterm>
<glossdef>
<para>Optional field with the passphrase for the private
key.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Fields for signing and validating messages</title>
<para>simpleSAMLphp only signs authentication responses by default.
Signing of authentication requests, logout requests and logout
responses can be enabled by setting the
<literal>redirect.sign</literal> option. Validation of received
messages can be enabled by the <literal>redirect.validate</literal>
option. Note that if you want to sign messages, you will need a
keypair/certificate at the SP.</para>
<para>These options set the default for this SP, but options for each
IdP can be set in <literal>saml20-idp-remote</literal>.</para>
<glosslist>
<glossentry>
<glossterm>redirect.sign</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>. To turn on
signing of authentication requests, logout requests and logout
responses, set this flag to true.</para>
<para>This option can be overridden by the
<literal>redirect.sign</literal> option in
<literal>saml20-idp-remote</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>redirect.validate</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>. To turn on
validation of received logout requests and logout responses, set
this flag to true.</para>
<para>This option can be overridden by the
<literal>redirect.validate</literal> option in
<literal>saml20-idp-remote</literal>.</para>
</glossdef>
</glossentry>
</glosslist>
<example>
<title>Example of configured signed messages</title>
<programlisting> 'redirect.sign' =&gt; true,
'privatekey' =&gt; 'server.pem',</programlisting>
</example>
</section>
</section>
<section>
<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 to
authenticate users of your service.</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>/*
* Example simpleSAMLphp SAML 2.0 IdP
*/
'idp-entity-id-simple' =&gt; array(
'name' =&gt; 'Test',
'description' =&gt; 'Description of this example entry',
'SingleSignOnService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
'SingleLogoutService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
'certFingerprint' =&gt; '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
),</programlisting>
</example>
<example>
<title>More complex example</title>
<para>Here is an example with more configuration:</para>
<programlisting> /*
* Example simpleSAMLphp SAML 2.0 IdP
*/
'idp-entity-id' =&gt; array(
'name' =&gt; 'Test',
'description' =&gt; 'Description of this example entry',
'SingleSignOnService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
'SingleLogoutService' =&gt; 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
'certFingerprint' =&gt; '3fa158e8abfd4b5203315b08c0b791b6ee4715f6',
'base64attributes' =&gt; true,
/*
* When redirect.validate is true the certificate of the IdP will be used
* to verify all messages received with the HTTPRedirect binding.
*
* The certificate from the IdP must be installed in the cert directory
* before verification can be done.
*/
'redirect.validate' =&gt; false,
'certificate' =&gt; "idp.example.org.crt",
/*
* It is possible to relax some parts of the validation of SAML2 messages.
* To relax a part, add the id to the 'saml2.relaxvalidation' array.
*
* Valid ids:
* - 'unknowncondition' Disables errors when encountering unknown &lt;Condition&gt; nodes.
* - 'nosubject' Ignore missing &lt;Subject&gt; in &lt;Assertion&gt;.
* - 'noconditions' Ignore missing &lt;Conditions&gt; in &lt;Assertion&gt;.
* - 'noauthnstatement' Ignore missing &lt;AuthnStatement&gt; in &lt;Assertion&gt;.
* - 'noattributestatement' Ignore missing &lt;AttributeStatement&gt; in &lt;Assertion&gt;.
*
* Example:
* 'saml2.relaxvalidation' =&gt; array('unknowncondition', 'noattributestatement'),
*
* Default:
* 'saml2.relaxvalidation' =&gt; array(),
*/
'saml2.relaxvalidation' =&gt; array(),
),</programlisting>
</example>
<section>
<title>Mandatory metadata fields</title>
<para>These are the required metadata fields:</para>
<glosslist>
<glossentry>
<glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
<para>Entity ID of the remote IdP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>name</glossterm>
<glossdef>
<para>A textual name of the IdP. This can contain a string or an
associative array of language code =&gt; translation pairs. This
name is used in the SAML 2.0 discovery service.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>description</glossterm>
<glossdef>
<para>A longer description of the IdP. This can contain a string
or an associative array of language code =&gt; translation
pairs. The description is used in the SAML 2.0 discovery
service.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SingleSignOnService</glossterm>
<glossdef>
<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>
<glossentry>
<glossterm>SingleLogoutService</glossterm>
<glossdef>
<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>
<glossentry>
<glossterm>certFingerprint</glossterm>
<glossdef>
<para>The <literal>sha1</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>It is also possible to add an array of valid fingerprints,
where any fingerprints in that array is accepted as valid. This
can be used to update the certificate of the IdP without having
to update every SP at that exact time. Instead, one can update
the SPs with the new fingerprint, and only update the
certificate after every SP is updated.</para>
<para>See <xref linkend="a.fingerprint" /> for an example of how
to calculate the fingerprint with the <literal>openssl</literal>
tool.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<para>These fields can be left out if not needed.</para>
<glosslist>
<glossentry>
<glossterm>base64attributes</glossterm>
<glossdef>
<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>
</warning></para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SPNameQualifier</glossterm>
<glossdef>
<para>This corresponds to the SPNameQualifier in the SAML 2.0
specification. It allows to give subjects a SP specific
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>
<glossentry>
<glossterm>attributemap</glossterm>
<glossdef>
<para>Mapping table for translating attribute names. For further
information, see the <emphasis>Advances Features</emphasis>
document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributealter</glossterm>
<glossdef>
<para>Table of custom functions that injects or modifies
attributes. For further information, see the <emphasis>Advances
Features</emphasis> document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>certificate</glossterm>
<glossdef>
<para>Name of certificate file in PEM format, in the
<filename>certs</filename> directory. Used for decrypting
assertions and as an alternative to certFingerprint for
validating signatures.</para>
<para>This option is also required if validating signed logout
requests/responses from this IdP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>assertion.encryption</glossterm>
<glossdef>
<para>Set to true if the remote idp encrypts assertions.
Encrypted assertions are decrypted regardless of the value this
field if the neccesary certificate or key is available, but if
it is set to true and an unencrypted assertion is recieved an
exception is raised.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>sharedkey</glossterm>
<glossdef>
<para>Used for optional symmetric decryption of assertions.
Currently the algorithm is hardcoded to AES128_CBC/RIJNDAEL_128
which uses up to 128 bit for the passphrase/key. Not necessary
if the idp uses a sessionkey which is encrypted by the idp's
private key.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>caFile</glossterm>
<glossdef>
<para>Alternative to certFingerprint. Allows you to specify a
file with root certificates, and responses from the service be
validated against these certificates. Note that simpleSAMLphp
doesn't support chains with any itermediate certificates between
the root and the certificate used to sign the response.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>icon</glossterm>
<glossdef>
<para>An icon for this IdP. This is a URL to a icon which will
be displayed next to this IdP in the IdP discovery service. The
URL can be absolute or relative. If it is relative, it will be
relative to the simpleSAMPphp www-directory.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Fields for signing and validating messages</title>
<para>simpleSAMLphp only signs authentication responses by default.
Signing of authentication requests, logout requests and logout
responses can be enabled by setting the
<literal>redirect.sign</literal> option. Validation of received
messages can be enabled by the <literal>redirect.validate</literal>
option. Note that if you want to sign messages, you will need a
keypair/certificate at the SP.</para>
<para>These options overrides the options set in
<literal>saml20-sp-hosted</literal>.</para>
<glosslist>
<glossentry>
<glossterm>redirect.sign</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>. To turn on
signing of authentication requests, logout requests and logout
responses, set this flag to true.</para>
<para>This option overrides the <literal>redirect.sign</literal>
option in <literal>saml20-sp-hosted</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>redirect.validate</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>. To turn on
validation of received logout requests and logout responses, set
this flag to true.</para>
<para>This option overrides the
<literal>redirect.validate</literal> option in
<literal>saml20-sp-hosted</literal>.</para>
</glossdef>
</glossentry>
</glosslist>
<example>
<title>Example of configuration for validating messages</title>
<programlisting>'redirect.validate' =&gt; true,
'certificate' =&gt; 'server.crt'</programlisting>
</example>
</section>
</section>
<section>
<title>Setting the default SAML 2.0 IdP</title>
<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>
<programlisting> 'default-saml20-idp' =&gt; 'sam.feide.no',</programlisting>
<para>The configuration above will use the IdP configured in IdP Remote
metadata with entity ID equal to <literal>sam.feide.no</literal>.</para>
</section>
<section>
<title>Using the SAML 2.0 IdP Discovery Service</title>
<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' =&gt; null,</programlisting>
</section>
</section>
<section>
<title>Configuring metadata for Shibboleth 1.3 SP</title>
<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>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>
<programlisting>/*
* Example of hosted Shibboleth 1.3 SP.
*/
'sp-provider-id' =&gt; array(
'host' =&gt; 'sp.example.org'
)
</programlisting>
</example>
<section>
<title>Mandatory fields</title>
<glosslist>
<glossentry>
<glossterm>index (the index of the array)</glossterm>
<glossdef>
<para>The entity ID of the hosted SP entity.</para>
<para>simpleSAMLphp supports dynamic entityIDs that matches a
URL where simpleSAMLphp automatically generates metadata for the
hosted entity. To enable this functionality, set the index to be
<literal>__DYNAMIC:1__</literal>. The index needs to be unique,
so when you have multiple entries, increase the integer after
the colon. When the index <literal>__DYNAMIC:1__</literal> is
used, the resulting generated entity becomes something
like:</para>
<literallayout>https://sp.example.org/simplesaml/shib13/sp/metadata.php</literallayout>
</glossdef>
</glossentry>
<glossentry>
<glossterm>host</glossterm>
<glossdef>
<para>Host name of the server running this SP. One of your
metadata entries can have the value
<literal>__DEFAULT__</literal>. A default entry will be used
when no other entry matches the current hostname.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<para>These fields can be left out if not needed.</para>
<glosslist>
<glossentry>
<glossterm>AssertionConsumerService</glossterm>
<glossdef>
<para>Override the default URL for the AssertionConsumerService
for this SP. This is an absolute URL. The default value is
<literal>&lt;simpleSAMLphp-root&gt;/shib13/sp/AssertionConsumerService.php</literal></para>
<para>Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>idpdisco.url</glossterm>
<glossdef>
<para>Set which IdP discovery service this SP should use. If
this is unset, the IdP discovery service specified in the global
option <literal>idpdisco.url.shib13</literal> in
<filename>config/config.php</filename> will be used. If that one
is also unset, the builtin default discovery service will be
used.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
</section>
<section>
<title>Configuring Shibboleth 1.3 IdP Remote metadata</title>
<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' =&gt; array(
'SingleSignOnService' =&gt; 'https://idp.example.org/shibboleth-idp/SSO',
'certFingerprint' =&gt; 'c7279a9f28f11380509e072441e3dc55fb9ab864'
)</programlisting>
</example>
<glosslist>
<glossentry>
<glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
<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>
<glossentry>
<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 request for
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>
</glossentry>
<glossentry>
<glossterm>certFingerprint</glossterm>
<glossdef>
<para>The <literal>sha</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>It is also possible to add an array of valid fingerprints,
where any fingerprints in that array is accepted as valid. This
can be used to update the certificate of the IdP without having to
update every SP at that exact time. Instead, one can update the
SPs with the new fingerprint, and only update the certificate
after every SP is updated.</para>
<para>See <xref linkend="a.fingerprint" /> for an example of how
to calculate the fingerprint with the openssl tool.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>caFile</glossterm>
<glossdef>
<para>Alternative to certFingerprint. Allows you to specify a file
with root certificates, and responses from the service be
validated against these certificates. Note that simpleSAMLphp
doesn't support chains with any itermediate certificates between
the root and the certificate used to sign the response.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>icon</glossterm>
<glossdef>
<para>An icon for this IdP. This is a URL to a icon which will be
displayed next to this IdP in the IdP discovery service. The URL
can be absolute or relative. If it is relative, it will be
relative to the simpleSAMPphp www-directory. This field is
optional.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
</section>
<section>
<title>Exchange metadata with the IdP</title>
<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 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>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 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
Metadata</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="resources/simplesamlphp-sp/saml2metadata.png" />
</imageobject>
</mediaobject>
</screenshot>
<para>If you are connected to Feide, and put one of Feides entity IDs as
default IdP, you will see an additional section on this page:</para>
<screenshot>
<screeninfo>Sending metadata to Feide</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="resources/simplesamlphp-sp/saml2metadata-feide.png" />
</imageobject>
</mediaobject>
</screenshot>
<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>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>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
authenticated</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="resources/simplesamlphp-sp/screenshot-example.png" />
</imageobject>
</mediaobject>
</screenshot>
</figure>
</section>
<section>
<title>Integrating authentication with your own application</title>
<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 already authenticated.</para>
</listitem>
<listitem>
<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 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>Sample code:</para>
<para>We start off with including a common file _include.php. All this
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
<filename>www/example-simple/shib13-example.php</filename>.</para>
<programlisting>require_once('SimpleSAML/Utilities.php');
require_once('SimpleSAML/Session.php');
require_once('SimpleSAML/XHTML/Template.php');
</programlisting>
<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();</programlisting>
<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-&gt;isValid('saml2') ) {
SimpleSAML_Utilities::redirect(
'/' . $config-&gt;getBaseURL() .
'saml2/sp/initSSO.php',
array('RelayState' =&gt; SimpleSAML_Utilities::selfURL())
);
}
$attributes = $session-&gt;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>
<itemizedlist>
<listitem>
<para><ulink
url="https://ow.feide.no/simplesamlphp:spupgrade05to10">Wiki page
describing the differences between integrating a service with
simpleSAMLphp 0.5 and simpleSAMLphp 1.0.</ulink></para>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Support</title>
<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>
<para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
homepage (at Feide RnD)</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
all available simpleSAMLphp documentation</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
the simpleSAMLphp user's mailing list</ulink></para>
</listitem>
<listitem>
<para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
contribute to the simpleSAMLphp wiki</ulink></para>
</listitem>
</itemizedlist>
</section>
<appendix id="a.fingerprint">
<title>Calculating the fingerprint of a certificate</title>
<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>$ 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>
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment