From aa976285c2f9ea06f03ef4bfcde1bf6ed852934a Mon Sep 17 00:00:00 2001
From: Thijs Kinkhorst <thijs@kinkhorst.com>
Date: Wed, 18 Oct 2017 15:08:37 +0000
Subject: [PATCH] Update Google Apps / G Suite tutorial a bit.
Might not be complete, needs check with current G Suite interfaces.
But improves on the current situation.
---
docs/index.md | 2 +-
docs/simplesamlphp-googleapps.md | 71 ++++++++++++-------------
docs/simplesamlphp-install.md | 2 +-
docs/simplesamlphp-maintenance.md | 2 +-
metadata-templates/saml20-sp-remote.php | 4 +-
5 files changed, 39 insertions(+), 42 deletions(-)
diff --git a/docs/index.md b/docs/index.md
index 78010008b..8bb3cea22 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -25,7 +25,7 @@ SimpleSAMLphp Documentation
* [Identity Provider QuickStart](simplesamlphp-idp)
* [IdP hosted reference](simplesamlphp-reference-idp-hosted)
* [SP remote reference](simplesamlphp-reference-sp-remote)
- * [Use case: Setting up an IdP for Google Apps](simplesamlphp-googleapps)
+ * [Use case: Setting up an IdP for G Suite (Google Apps)](simplesamlphp-googleapps)
* [Configuring HTTP-Artifact](./simplesamlphp-artifact-idp)
* [Identity Provider Advanced Topics](simplesamlphp-idp-more)
* [Holder-of-Key profile](simplesamlphp-hok-idp)
diff --git a/docs/simplesamlphp-googleapps.md b/docs/simplesamlphp-googleapps.md
index 1a11a171d..775e71ee1 100644
--- a/docs/simplesamlphp-googleapps.md
+++ b/docs/simplesamlphp-googleapps.md
@@ -1,4 +1,4 @@
-Setting up a SimpleSAMLphp SAML 2.0 IdP to use with Google Apps for Education
+Setting up a SimpleSAMLphp SAML 2.0 IdP to use with Google Apps / G Suite for Education
============================================
<!--
@@ -16,7 +16,7 @@ SimpleSAMLphp news and documentation
This document is part of the SimpleSAMLphp documentation suite.
- * [List of all SimpleSAMLphp documentation](http://simplesamlphp.org/docs)
+ * [List of all SimpleSAMLphp documentation](https://simplesamlphp.org/docs)
* [SimpleSAMLphp homepage](https://simplesamlphp.org)
@@ -37,10 +37,9 @@ Edit `config.php`, and enable the SAML 2.0 IdP:
'enable.saml20-idp' => true,
'enable.shib13-idp' => false,
-## Setting up a SSL signing certificate
-
-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.
+## Setting up a signing certificate
+You must generate a certificate for your IdP.
Here is an example of an openssl command to generate a new key and a self signed certificate to use for signing SAML messages:
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out googleappsidp.crt -keyout googleappsidp.pem
@@ -65,8 +64,6 @@ Here is an example of typical user input when creating a certificate request:
**Note**: SimpleSAMLphp will only work with RSA and not DSA certificates.
-
-
Authentication source
---------------------
@@ -86,7 +83,7 @@ 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).
+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.)
Configuring the authentication source
@@ -100,7 +97,7 @@ On unix, this can be done by running (from the SimpleSAMLphp installation direct
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 `config/authsources.php`.
-In this example we will use the `example-userpass`, and hence that section is what matters and will be used.
+In this example we will use `example-userpass`, and hence that section is what matters and will be used.
<?php
$config = array(
@@ -116,11 +113,7 @@ In this example we will use the `example-userpass`, and hence that section is wh
);
?>
-This configuration creates two users - `student` and `employee`, with the passwords `studentpass` and `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.
-
-
-
-
+This configuration creates two users - `student` and `employee`, with the passwords `studentpass` and `employeepass`. The username and password are 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.
@@ -133,7 +126,7 @@ If you want to setup a SAML 2.0 IdP for Google Apps, you need to configure two m
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)
+ // The SAML entity ID is the index of this config. Dynamic:X will automatically generate an entity ID (recommended)
$metadata['__DYNAMIC:1__'] => array(
// The hostname of the server (VHOST) that this SAML entity will use.
@@ -146,17 +139,17 @@ This is the configuration of the IdP itself. Here is some example config:
'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.
+**Note**: You can only have one entry in the file with host equal to `__DEFAULT__`, therefore you should replace the existing entry with this one, instead of adding this entry as a new entry in the file.
### 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:
+In the `saml20-sp-remote.php` file we will configure an entry for G Suite (Google Apps) for Education. There is already an entry for G Suite in the template, but we will change the domain name:
/*
- * This example shows an example config that works with Google Apps for education.
+ * This example shows an example config that works with G Suite (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 john@foo.com, then you
+ * at G Suite. E.g. if your google account is foo.com, and you have a user with email john@foo.com, then you
* must set the simplesaml.nameidattribute to be the name of an attribute that for this user has the value of 'john'.
*/
$metadata['google.com'] => array(
@@ -170,14 +163,14 @@ You must also map some attributes received from the authentication module into e
For an e-mail address `student@g.feide.no`, the `uid` should be set to `student`.
-You should modify the `AssertionConsumerService` to include your Google Apps domain name instead of `g.feide.no`.
+You should modify the `AssertionConsumerService` to include your G Suite domain name instead of `g.feide.no`.
For an explanation of the parameters, see the
[SimpleSAMLphp Identity Provider QuickStart](simplesamlphp-idp).
-## Configure Google Apps for education
+## Configure G Suite for education
-Start by logging in to our Google Apps for education account panel.
+Start by logging in to our G SUite for education account panel.
Then select "Advanced tools":
**Figure 1. We go to advanced tools**
@@ -196,44 +189,49 @@ Upload a certificate, such as the googleappsidp.crt created above:
Fill out the remaining fields:
-The most important field is the Sign-in page URL. Set it to
-something similar to:
+The most important field is the Sign-in page URL. You can find the
+correct value in your IdP metadata. Browse to your simpleSAMLphp installation,
+go to the "Federation" tab, under "SAML 2.0 IdP Metadata" select "show metadata".
- http://dev2.andreas.feide.no/simplesaml/saml2/idp/SSOService.php
+You will find in the metadata the XML tag `<md:SingleSignOnService>`
+which contains the right URL to input in the field, it will look something
+like this:
-using the hostname of your IdP server.
+ https://dev2.andreas.feide.no/simplesaml/saml2/idp/SSOService.php
-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:
+You must also configure the IdP initiated Single LogOut endpoint of your server.
+You will find this in your metadata XML in the tag
+`<md:SingleLogoutService>`. It will look something like:
- http://dev2.andreas.feide.no/simplesaml/saml2/idp/initSLO.php?RelayState=/simplesaml/logout.php
+ http://dev2.andreas.feide.no/simplesaml/saml2/idp/SingleLogoutService.php
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.
+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 G Suite login page.
+It is normally best to leave this field empty to enable authentication for all URLs.
**Figure 4. Fill out the remaining fields**
-### Add a user in Google Apps that is known to the IdP
+### Add a user in G Suite that is known to the IdP
-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.
+Before we can test login, a new user must be defined in G Suite. This user must have a mail field matching the email prefix mapped from the attribute as described above in the metadata section.
-## Test to login to Google Apps for education
+## Test to login to G Suite 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
-replacing the last part with your own google apps domain name.
+replacing the last part with your own G Suite domain name.
## Security Considerations
-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.
+Make sure that your IdP server runs HTTPS (TLS). The Apache documentation contains information for how to configure HTTPS.
Support
-------
@@ -244,4 +242,3 @@ If you need help to make this work, or want to discuss SimpleSAMLphp with other
- [List of all available SimpleSAMLphp documentation](https://simplesamlphp.org/docs/)
- [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)
-
diff --git a/docs/simplesamlphp-install.md b/docs/simplesamlphp-install.md
index ee573309c..1f127a549 100644
--- a/docs/simplesamlphp-install.md
+++ b/docs/simplesamlphp-install.md
@@ -261,7 +261,7 @@ You have now successfully installed SimpleSAMLphp, and the next steps depends on
* [Identity Provider QuickStart](simplesamlphp-idp)
* [IdP hosted reference](simplesamlphp-reference-idp-hosted)
* [SP remote reference](simplesamlphp-reference-sp-remote)
- * [Use case: Setting up an IdP for Google Apps](simplesamlphp-googleapps)
+ * [Use case: Setting up an IdP for G Suite (Google Apps)](simplesamlphp-googleapps)
* [Identity Provider Advanced Topics](simplesamlphp-idp-more)
* [Automated Metadata Management](simplesamlphp-automated_metadata)
* [Maintenance and configuration](simplesamlphp-maintenance)
diff --git a/docs/simplesamlphp-maintenance.md b/docs/simplesamlphp-maintenance.md
index cd78803e5..ab38566e9 100644
--- a/docs/simplesamlphp-maintenance.md
+++ b/docs/simplesamlphp-maintenance.md
@@ -205,7 +205,7 @@ alternative, you may log to flat files.
## Apache configuration
-Basic Apache configruation is described in [SimpleSAMLphp Installation](simplesamlphp-install#section_6).
+Basic Apache configuration is described in [SimpleSAMLphp Installation](simplesamlphp-install#section_6).
However, your IdP or SP is most likely a valuable website that you want to configure securely. Here are some checks.
* Make sure you use HTTPS with a proper certificate. The best way is to not
diff --git a/metadata-templates/saml20-sp-remote.php b/metadata-templates/saml20-sp-remote.php
index a691fcf25..46262cee1 100644
--- a/metadata-templates/saml20-sp-remote.php
+++ b/metadata-templates/saml20-sp-remote.php
@@ -14,9 +14,9 @@ $metadata['https://saml2sp.example.org'] = array(
);
/*
- * This example shows an example config that works with Google Apps for education.
+ * This example shows an example config that works with G Suite (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. In example, if your google account is foo.com, and you have a user that has an email john@foo.com, then you
+ * at G Suite. In example, if your Google account is foo.com, and you have a user that has an email john@foo.com, then you
* must set the simplesaml.nameidattribute to be the name of an attribute that for this user has the value of 'john'.
*/
$metadata['google.com'] = array(
--
GitLab