From 0146b94863f7bb2e3b1d163e5c965a3d25a34b2a Mon Sep 17 00:00:00 2001
From: Olav Morken <olav.morken@uninett.no>
Date: Tue, 6 Oct 2009 09:35:40 +0000
Subject: [PATCH] docs: Document SP migration from old to new code.
Update issue 207
Status: Started
Owner: andreassolberg
The document should be added to the documents at rnd.feide.no.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1823 44740490-163a-0410-bde0-09ae8108e29a
---
docs/simplesamlphp-sp-migration.txt | 261 ++++++++++++++++++++++++++++
1 file changed, 261 insertions(+)
create mode 100644 docs/simplesamlphp-sp-migration.txt
diff --git a/docs/simplesamlphp-sp-migration.txt b/docs/simplesamlphp-sp-migration.txt
new file mode 100644
index 000000000..a0136de18
--- /dev/null
+++ b/docs/simplesamlphp-sp-migration.txt
@@ -0,0 +1,261 @@
+Migrating to the `saml` module
+==============================
+
+This document describes how you can migrate your code to use the `saml` module for authentication against SAML 2.0 and SAML 1.1 IdPs.
+It assumes that you have previously set up a SP by using redirects to `saml2/sp/initSSO.php`.
+
+The steps we are going to follow are:
+
+1. Create a new authentication source.
+2. Add the metadata for this authentication source to the IdP.
+3. Test the new authentication source.
+4. Convert the application to use the new API.
+5. Test the application.
+6. Remove the old metadata from the IdP.
+7. Disable the old SAML 2 SP.
+
+
+Create a new authentication source
+----------------------------------
+
+In this step we are going to create an authentication source which uses the `saml` module for authentication.
+To do this, we open `config/authsources.php`. Create the file if it does not exist.
+If you create the file, it should looke like this:
+
+ <?php
+ $config = array(
+ /* Here we can add entries for authentication sources we want to use. */
+ );
+
+
+We are going to add an entry to this file.
+The entry should look something like this:
+
+ 'default-sp' => array(
+ 'saml:SP',
+
+ /*
+ * The entity ID of this SP.
+ * Can be NULL/unset, in which case an entity ID is generated based on the metadata URL.
+ */
+ 'entityID' => NULL,
+
+ /*
+ * The entity ID of the IdP this should SP should contact.
+ * Can be NULL/unset, in which case the user will be shown a list of available IdPs.
+ */
+ 'idp' => NULL,
+
+ /* Here you can add other options to the SP. */
+ ),
+
+`default-sp` is the name of the authentication source.
+It is used to refer to this authentication source when we use it.
+`saml:SP` tells simpleSAMLphp that authentication with this authentication source is handled by the `saml` module.
+
+The `idp` option should be set to the same value that is set in `default-saml20-idp` in `config.php`.
+
+To ease migration, you probably want the entity ID on the new SP to be different than on the old SP.
+This makes it possible to have both the old and the new SP active on the IdP at the same time.
+
+You can also add other options this authentication source.
+See the [`saml:SP`](https://rnd.feide.no/content/saml-service-provider-configuration-reference) documentation for more information.
+
+
+Add the metadata for this authentication source to the IdP
+----------------------------------------------------------
+
+After adding the authentication source on the SP, you need to register the metadata on the IdP.
+To retrieve the metadata, open the frontpage of your simpleSAMLphp installation, and go to the federation tab.
+You should have a list of metadata entries, and one will be marked with the name of the new authentication source.
+In our case, that was `default-sp`.
+
+Click the `Show metadata` link, and you will arrive on a web page with the metadata for that service provider.
+How you proceed from here depends on which IdP you are connecting to.
+
+If you use a simpleSAMLphp IdP, you can use the metadata in the flat file format at the bottom of the page.
+That metadata should be added to `saml20-sp-remote.php` on the IdP.
+For other IdPs you probably want to use the XML metadata.
+
+
+Test the new authentication source
+----------------------------------
+
+You should now be able to log in using the new authentication source.
+Go to the frontpage of your simpleSAMLphp installation and open the authentication tab.
+There you will find a link to test authentication sources.
+Click that link, and select the name of your authentication source (`default-sp` in our case).
+
+You should be able to log in using that authentication source, and receive the attributes from the IdP.
+
+
+Convert the application to use the new API
+------------------------------------------
+
+This section will go through some common changes that you need to do when you are using simpleSAMLphp from a different application.
+
+### `_include.php`
+
+You should also no longer include `.../simplesamlphp/www/_include.php`.
+Instead, you should include `.../simplesamlphp/lib/_autoload.php`.
+
+This means that you replace lines like:
+
+ require_once('.../simplesamlphp/www/_include.php');
+
+with:
+
+ require_once('.../simplesamlphp/lib/_autoload.php');
+
+`_autoload.php` will register an autoloader function for the simpleSAMLphp classes.
+This makes it possible to access the classes from your application.
+`_include.php` does the same, but also has some side-effects that you may not want in your application.
+
+If you load any simpleSAMLphp class files directly, you should remove those lines.
+That means that you should remove lines like the following:
+
+ require_once('SimpleSAML/Utilities.php');
+ require_once('SimpleSAML/Session.php');
+ require_once('SimpleSAML/XHTML/Template.php');
+
+
+### Authentication API
+
+There is a new authentication API in simpleSAMLphp which can be used to authenticate against authentication sources.
+This API is designed to handle the common operations.
+
+
+#### Overview
+
+This is a quick overview of the API:
+
+ /* Get a reference to our authentication source. */
+ $as = new SimpleSAML_Auth_Simple('default-sp');
+
+ /* Require the user to be authentcated. */
+ $as->requireAuth();
+ /* When that function returns, we have an authenticated user. */
+
+ /*
+ * Retrieve attributes of the user.
+ *
+ * Note: If the user isn't authenticated when getAttributes() is
+ * called, an empty array will be returned.
+ */
+ $attributes = $as->getAttributes();
+
+ /* Log the user out. */
+ $as->logout();
+
+
+#### `$config` and `$session`
+
+Generally, if you have:
+
+ $config = SimpleSAML_Configuration::getInstance();
+ $session = SimpleSAML_Session::getInstance();
+
+you should replace it with this single line:
+
+ $as = new SimpleSAML_Auth_Simple('default-sp');
+
+
+#### Requiring authentication
+
+Blocks of code like the following:
+
+ /* 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())
+ );
+ }
+
+should be replaced with a single call to `requireAuth()`:
+
+ $as->requireAuth();
+
+
+#### Fetching attributes
+
+Where you previously called:
+
+ $session->getAttributes();
+
+you should now call:
+
+ $as->getAttributes();
+
+
+#### Logging out
+
+Redirecting to the initSLO-script:
+
+ SimpleSAML_Utilities::redirect(
+ '/' . $config->getBaseURL() .
+ 'saml2/sp/initSLO.php',
+ array('RelayState' => SimpleSAML_Utilities::selfURL())
+ );
+
+should be replaced with a call to `logout()`:
+
+ $as->logout();
+
+If you want to return to a specific URL after logging out, you should include that URL as a parameter to the logout function:
+
+ $as->logout('https://example.org/');
+
+
+Test the application
+--------------------
+
+How you test the application is highly dependent on the application, but here are the elements you should test:
+
+
+### SP initiated login
+
+Make sure that it is still possible to log into the application.
+
+
+### IdP initiated login
+
+If you use a simpleSAMLphp IdP, and you want users to be able to bookmark the login page, you need to test IdP initiated login.
+To test IdP initiated login from a simpleSAMLphp IdP, you can access:
+
+ https://.../simplesaml/saml2/idp/SSOService.php?spentityid=<entity ID of your SP>&RelayState=<URL the user should be sent to after login>
+
+Note that the RelayState parameter is only supported if the IdP runs version 1.5 of simpleSAMLphp.
+If it isn't supported by the IdP, you need to configure the `RelayState` option in the authentication source configuration.
+
+
+### SP initiated logout
+
+Make sure that logging out of your application also logs out of the IdP.
+If this does not work, users who log out of your application can log in again without entering any username or password.
+
+
+### IdP initiated logout
+
+This is used by the IdP if the user logs out of a different SP connected to the IdP.
+In this case, the user should also be logged out of your application.
+
+The easiest way to test this is if you have two SPs connected to the IdP.
+You can then log out of one SP and check that you are also logged out of the other.
+
+
+Remove the old metadata from the IdP
+------------------------------------
+
+Once the new SP works correctly, you can remove the metadata for the old SP from the IdP.
+How you do that depends on the IdP.
+If you are running a simpleSAMLphp IdP, you can remove the entry for the old SP in `metadata/saml20-sp-remote.php`.
+
+
+Disable the old SAML 2 SP
+-------------------------
+
+You may also want to disable the old SP code in simpleSAMLphp.
+To do that, open `config/config.php`, and change the `enable.saml20-sp` option to `FALSE`.
+
--
GitLab