Setting up a simpleSAMLphp SAML 2.0 IdP to use with Google Apps for Education
Table of Contents
- 1 simpleSAMLphp news and documentation
- 2 Introduction
- 3 Enabling the Identity Provider functionality
- 4 Setting up a SSL signing certificate
- 5 Authentication source
- 6 Configuring the authentication source
- 7 Configuring metadata for an SAML 2.0 IdP
- 8 Configure Google Apps for education
- 9 Test to login to Google Apps for education
- 10 Security Considerations
- 11 Support
This document is part of the simpleSAMLphp documentation suite.
- List of all simpleSAMLphp documentation
- Latest news about simpleSAMLphp. (Also conatins an RSS feed)
- simpleSAMLphp homepage
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:
config.php, and enable the SAML 2.0 IdP:
'enable.saml20-idp' => true, 'enable.shib13-idp' => false,
For test purposes, you can skip this section, and use the certificate included in the simpleSAMLphp distribution. For a production system, you MUST generate a new certificate for your IdP.
Here is an example of openssl commands to generate a new key and a self signed certificate to use for signing SAML messages:
openssl genrsa -des3 -out googleappsidp.key 2048 openssl rsa -in googleappsidp.key -out googleappsidp.pem openssl req -new -key googleappsidp.key -out googleappsidp.csr openssl x509 -req -days 9999 -in googleappsidp.csr -signkey googleappsidp.key -out googleappsidp.crt
The certificate above will be valid for 9999 days (27 years).
Here is an example of typical user input 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.
The next step is to configure the way users authenticate on your IdP. Various modules in the
modules/ directory provides methods for authenticating your users. This is an overview of those that are included in the simpleSAMLphp distribution:
- Authenticate against a list of usernames and passwords.
- Automatically log in as a user with a set of attributes.
- Authenticates an user to a LDAP server.
For more authentication modules, see SimpleSAMLphp Identity Provider QuickStart.
In this guide, we will use the
exampleauth:UserPass authentication module. This module does not have any dependencies, and is therefore simple to set up.
After you have successfuly tested that everything is working with the simple
exampleauth:UserPass, you are encouraged to setup simpleSAMLphp IdP towards your user storage, such as an LDAP directory. (Use the links on the authentication sources above to read more about these setups.
ldap:LDAP is the most common authentication source).
exampleauth:UserPass authentication source is part of the
exampleauth module. This module isn't enabled by default, so you will have to enable it. This is done by creating a file named
On unix, this can be done by running (from the simpleSAMLphp installation directory):
The next step is to create an authentication source with this module. An authentication source is an authentication module with a specific configuration. Each authentication source has a name, which is used to refer to this specific configuration in the IdP configuration. Configuration for authentication sources can be found in
In this example we will use the
example-userpass, and hence that section is what matters and will be used.
<?php $config = array( 'example-userpass' => array( 'exampleauth:UserPass', 'student:studentpass' => array( 'uid' => array('student'), ), 'employee:employeepass' => array( 'uid' => array('employee'), ), ), ); ?>
This configuration creates two users -
employee, with the passwords
employeepass. The username and password is stored in the array index
student:studentpass for the
student-user. The attributes (only
uid in this example) will be returned by the IdP when the user logs on.
If you want to setup a SAML 2.0 IdP for Google Apps, you need to configure two metadata files:
This is the configuration of the IdP itself. Here is some example config:
// The SAML entity ID is the index of this config. Dynamic:X will automatically generate an entity ID (Reccomended) '__DYNAMIC:1__' => array( // The hostname of the server (VHOST) that this SAML entity will use. 'host' => '__DEFAULT__', // X.509 key and certificate. Relative to the cert directory. 'privatekey' => 'googleappsidp.pem', 'certificate' => 'googleappsidp.crt', 'auth' => 'example-userpass', )
Note: You can only have one entry in the file with host equal
__DEFAULT__, therefore you should replace the existing entry with this one, instead of adding this entry as a new entry in the file.
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 local part of the email address * at Google Apps. E.g. if your google account is foo.com, and you have a user with email firstname.lastname@example.org, then you * must set the simplesaml.nameidattribute to be the name of an attribute that for this user has the value of 'john'. */ 'google.com' => array( 'AssertionConsumerService' => 'https://www.google.com/a/g.feide.no/acs', 'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:email', 'simplesaml.nameidattribute' => 'uid', 'simplesaml.attributes' => false );
You must also map some attributes received from the authentication module into email field sent to Google Apps. In this example, the
uid attribute is set. When you later configure the IdP to connect to a LDAP directory or some other authentication source, make sure that the
uid attribute is set properly, or you can configure another attribute to use here. The
uid attribute contains the local part of the user name.
For an e-mail address
uid should be set to
You should modify the
AssertionConsumerService to include your Google Apps domain name instead of
For an explanation of the parameters, see the SimpleSAMLphp Identity Provider QuickStart.
Start by logging in to our Google Apps for education account panel. Then select "Advanced tools":
Figure 1. We go to advanced tools
Then select "Set up single sign-on (SSO)":
Figure 2. We go to setup SSO
Upload a certificate, such as the googleappsidp.crt created above:
Figure 3. Uploading certificate
Fill out the remaining fields:
The most important field is the Sign-in page URL. Set it to something similar to:
using the hostname of your IdP server.
You must also configure the IdP initiated Single LogOut endpoint of your server. The RelayState parameter of the endpoint is the URL where the user is redirected after successfull logout. Recommended value:
again, using the host name of your IdP server.
The Sign-out page or change password url can be static pages on your server.
The network mask determines which IP addresses will be asked for SSO login. IP addresses not matching this mask will be presented with the normal Google Apps login page. I think you can leave this field empty to enable authentication for all URLs.
Figure 4. Fill out the remaining fields
Before we can test login, a new user must be defined in Google Apps. This user must have a mail field matching the email prefix mapped from the attribute as described above in the metadata section.
Go to the URL of your mail account for this domain, the URL is similar to the following:
replacing the last part with your own google apps domain name.
Make sure that your IdP server runs HTTPS (SSL). The Apache documentation contains information for how to configure HTTPS.
Make sure you have replaced the default certificate delivered with the simpleSAMLphp distribution with your own certificate.
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.