Setting up a simpleSAMLphp SAML 2.

0 IdP to use with Google Apps for Education

Andreas kre Solberg <andreas.solberg@uninett.no>
Sun Oct 21 13:51:26 2007

Table of Contents
Introduction ....................................................................................................................... Setting up a SSL signing certificate ....................................................................................... Authentication modules ....................................................................................................... Configuring the LDAP authentication module .................................................................. Configuring the multi-LDAP authenticaiton module .......................................................... Configuring metadata for an SAML 2.0 IdP ............................................................................ Configuring SAML 2.0 IdP Hosted metadata ................................................................... Configuring SAML 2.0 SP Remote metadata ................................................................... Configure Google Apps for education .................................................................................... Add a user in Google Apps that is also in the IdP ............................................................ Test to login to Google Apps for education ............................................................................. Security Considerations ....................................................................................................... Support ............................................................................................................................. 1 1 2 2 3 3 3 4 4 8 8 8 8

Introduction
This article assumes that you have already read the simpleSAMLphp installation manual, and installed a version of simpleSAMLphp at your server. In this example we will setup this server as an IdP for Google Apps for Education: dev2.andreas.feide.no

Setting up a SSL signing certificate

For test purposes, you can skip this section, and use the included certificate. For a production system, uou must generate a new certificate for your IdP.

Warning
There is a certificate that follows this package that you can use for test purposes, but off course NEVER use this in production as the private key is also included in the package and can be downloaded by anyone. Here is an examples of openssl commands to generate a new key and a selfsigned certificate to use for signing SAML messages: openssl genrsa -des3 -out googleappsidp.key 1024

Setting up a simpleSAMLphp SAML 2.0 IdP to use with openssl rsa -in googleappsidp.key Education Google Apps for -out googleappsidp.pem openssl req -new -key googleappsidp.key -out googleappsidp.csr openssl x509 -req -days 1095 -in googleappsidp.csr -signkey googleappsidp.key -out The certificate above will be valid for 1095 days (3 years). Here is an example of what can be typed in when creating a certificate request: Country Name (2 letter code) [AU]:NO State or Province Name (full name) [Some-State]:Trondheim Locality Name (eg, city) []:Trondheim Organization Name (eg, company) [Internet Widgits Pty Ltd]:UNINETT Organizational Unit Name (eg, section) []: Common Name (eg, YOUR name) []:dev2.andreas.feide.no Email Address []: Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []:

Note
simpleSAMLphp will only work with RSA and not DSA certificates.

Authentication modules
You will need to connect the IdP to your existing user storage. For different technologies of user storage, there are different authentication modules. In the www/auth directory, you see multiple files, each representing an authentication module. In the IdP hosted metadata configuration you specify which authentication module that should be used for that specific IdP. You can implement your own authentication module, see the IdP documentation. These authentication modules are included: auth/login.php auth/login-ldapmulti.php auth/login-radius.php auth/login-auto.php This is the standard LDAP backend authentication module, it uses LDAP configuration from the config.php file. This authentication module lets you connect to multiple LDAPS depending on what organization the user selects in the login form. This authentication module will authenticate users against an RADIUS server instead of LDAP. This module will automatically login the user with some test details. You can use this to test the IdP functionality if you do not have This module is not completed yet. Work in progress.

Configuring the LDAP authentication module

The LDAP module is auth/login.php. If you want to perform local authentication on this server, and you want to use the LDAP authenticaiton plugin, then you need to configure the following parameters in config.php:

Setting up a simpleSAMLphp SAML 2.0 IdP to use with auth.ldap.dnpattern:Google Apps should you bind to? Replacing %username% with the What DN for Education username the user types in. auth.ldap.hostname: The hostname of the LDAP server auth.ldap.attributes: Search parameter to LDAP. What attributes should be extracted? objectclass=* gives you all.

Configuring the multi-LDAP authenticaiton module

The module is auth/login-ldapmulti.php.

Note
Documentation will be added later. For now, contact the author.

Configuring metadata for an SAML 2.0 IdP

If you want to setup a SAML 2.0 IdP for Google Apps, you need to configure two metadata files: saml20idp-hosted.php and saml20-sp-remote.php.

Configuring SAML 2.0 IdP Hosted metadata

This is the configuration of the IdP itself. Here is some example config: // The SAML entity ID is the index of this config. 'dev2.andreas.feide.no' => array( // The hostname of the server (VHOST) that this SAML entity will use. 'host' => 'sp.example.org', // X.509 key and certificate. Relative to the cert directory. 'privatekey' => 'googleappsidp.pem', 'certificate' => 'googleappsidp.crt',

/* If base64attributes is set to true, then all attributes will be base64 encoded * that you set the SP to have the same value for this. */ 'base64attributes' => false, // Authentication plugin to use. login.php is the default one that uses LDAP. 'auth' => 'auth/login.php' ) Here are some details of each of the parameters: index (index of array) host privatekey The entity ID of the IdP. In this example this value is set to: dev2.andreas.feide.no. The hostname of the server running this IdP, in this case: dev2.andreas.feide.no. Pointing to the private key in PEM format, in the certs directory. Remeber we created the googleappsidp key?

certificate base64attributes auth

Setting up a simpleSAMLphp SAML 2.0 IdP to use with Pointing to the certificate Google Apps for Education file in PEM format, in the certs directory. Remeber we created the googleappsidp key? Google Apps do not want us to base64encode any attributes, so we set it to false. Which authentication module to use? Default is: auth/login.php which is the LDAP authentication module. See the the section called Authentication modules for more information on the authentication modules.

Configuring SAML 2.0 SP Remote metadata

In the (saml20-sp-remote.php) file we will configure an entry for Google Apps for education. There is already an entry for Google Apps in the template, but we will change the domain name:

/* * This example shows an example config that works with Google Apps for education. * What is important is that you have an attribute in your IdP that maps to the lo * at Google Apps. In example, if your google account is foo.com, and you have a u * must set the simplesaml.nameidattribute to be the name of an attribute that for */ 'google.com' => array( 'AssertionConsumerService' => 'https://www.google.com/a/g.feide.no/acs', 'spNameQualifier' => 'google.com', 'ForceAuthn' => 'false', 'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:email', 'simplesaml.nameidattribute' => 'uid', 'simplesaml.attributes' => false ), You also need to map some attribute from the IdP into the email field sent to Google Apps. The attributes comes from the authentication module, and in this example we have an LDAP that returns the uid attribute. The uid attribute contains the local part of What you need to do is modify the AssertionConsumerService to include your Google Apps domain name instead of g.feide.no. To understand what the different parameters mean, see in the simpleSAMLphp IdP documentation [simplesamlphp-idp.html].

Configure Google Apps for education

Now, we are ready to configure Google Apps to use our IdP. We start by logging in to our Google Apps for education account panel. We then go to "Advanced tools":

Figure 1. We go to advanced tools

Setting up a simpleSAMLphp SAML 2.0 IdP to use with Then we go to "Set up single sign-on (SSO)": for Education Google Apps

Figure 2. We go to setup SSO

Then, we start off by uploading a certificate, and we upload the certificate we created in an earlier section, the googleappsidp.crt file:

Figure 3. Uploading

Setting up a simpleSAMLphp SAML 2.0 IdP to use with certificate Apps for Education Google

Then we need to fill out the remaining fields: The important field to fill out is the Sign-in page URL. Set it to something similar to: http://dev2.andreas.feide.no/simplesaml/saml2/idp/SSOService.php but use the hostname of your IdP server. The Sign-out page or change password url can be static pages on your server.

Warning

Setting up a simpleSAMLphp SAML 2.0 IdP to use with Google Apps for Education

Single Logout functionality with SAML 2.0 in simpleSAMlphp and Google Apps is not yet fully tested. We will do more testing about that, and then include a detailed descrition in this document. The network mask, is which IP addresses that will be asked for SSO login. IP addresses that do not match this mask will be presented with the normal Google Apps login page.

Figure 4. Fill out the remaining fields

Add a user in Google Apps that is also in the IdP

Add a new user in Google Apps, before we can test login. This user needs to have the mail field to match the email prefix mapped from the attribute as described in the metadata section.

Setting up a simpleSAMLphp SAML 2.0 IdP to use with Google Apps for Education

Test to login to Google Apps for education

Go to the URL of your mail account for this domain, the URL is similar to the following: http://mail.google.com/a/yourgoogleappsdomain.com but remember to replace with your own google apps domain name.

Security Considerations
You should make sure that your IdP server runs on HTTPS (SSL). Check the Apache documentation if you need to know how to configure that. And make sure you have switched away from the default certificate that follows the simpleSAMLphp distribution.

Support
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. Visit the project page of simpleSAMLphp at: http://code.google.com/p/simplesamlphp/ And please join the mailinglist: https://postlister.uninett.no/sympa/subscribe/simplesaml [???]