Social/SAML Gateway to enable social media identity provision -- Fall 2013 corrections

Preparatory steps

• These instructions were tested on a CentOS server; CentOS or RedHat substrates may therefore be most compatible with these instructions.
• The following packages must be installed:
  • httpd server (Apache web server easiest to work with, but any httpd that supports PHP should do; these instructions assume Apache httpd)
  • PHP, version >= 5.2.0
  • Support for the following PHP extensions:
    • Always required: date, dom, hash, libxml, openssl, pcre, SPL, zlib
    • When using database:
      • Always: PDO
      • Database driver: (mysql, pgsql, ...)
• The simplesamlphp package from U Texas (attached as a zip) should be unzipped into the /var directory on the server, which will result in a /var/simplesamlphp directory
  • Note: above referenced package has the root of the directory as simplesamlphp.scrubbed

Set up two sets of certificates and private keys

Two sets keys are needed: one set for SSL and one for use by SimpleSAMLphp (SSP) for signing and encryption.

 

Note from Bridget: We need something here that highlights the role  of the SimpleSAML IdP in relationship to the rest of the Bamboo IAM components, so that we know whether we can/should reuse certificates from elsewhere in the infrastructure. 

Up until now we may already have the following certificates and keys in the ecosystem:

1. CA-signed certificate and corresponding private key for Apache SSL Proxy to BSP
2. Self-signed certs and corresponding private keys for each client application to the BSP (per https://wikihub.berkeley.edu/display/pbamboo/Configure+Apache+Web+Server+for+Client+Auth#ConfigureApacheWebServerforClientAuth-ClientsarerequiredtosupplyanX.509Certificate,whichmaybeself-signed)
3. CA-signed certificate and corresponding private key for Apache SSL proxy to a protected application in the ecosystem (i.e. an application not residing on the BSP)
4. Self-or CA-signed certificate and corresponding private key for interaction between above-mentioned (3) Shibboleth/SAML SP protected application and the IdP(s) allowed for it (of which the SimpleSAML IdP would be one)
   1. According to the SimpleSAML IdP instructions the IdP should reside on a different hostname than any SP that talks to it - although technical subdomains could share the same cert it seems unlikely that it's a good idea for the SP and the IdP to share the same certificate.

Conclusion? Since we don't currently run a Shibboleth SP on the BSP, it's possible that we could put the SimpleSAML IdP on the same host as the BSP and share certificates with it (i.e. the certificate in item #1 above). This seems like it might be not the best idea though, and it would be better to keep the SimpleSAML idp on a separate domain with its own certificate.

Reply from Keith, email of 12/05/2013:

I would definitely mint cert/key pairs specific to the SimpleSamlphp (SSP) IdP. As for whether you can run other Bamboo components on the same box, I'd guess that depends on whether anything other than SSP uses the Apache web server. If there are other services using Apache, you just need to be careful that there are no incompatible configuration requirements. If the host is running any http services other than Apache, I think it's mainly an issue of making sure there are no conflicting port listener assignments.

In an ideal world, I'd opt to keep the SSP IdP on a separate host during dev and test, and making sure it's working properly there. Then consider consolidating on a single host as an optimization step. That would give you a baseline of a working SSP IdP deployment which should help in the analysis of any emergent problems when you consolidate.

 

In high level overview, the following steps accomplish these goals:

• Generate two certificates and private keys, one set for SSL and one for use by SimpleSAMLphp (SSP) for signing and encryption.
• Configure apache for https, including placement of key pair and cert in the traditional directories for httpd
• Place the SimpleSAMLphp key and cert in the expected location, then edit the configuration file to point to them

For the SSL key (assuming name of server is mydomain.org)

# openssl req -x509 -nodes -days 3660 -newkey rsa:2048 -keyout /etc/pki/tls/private/mydomain.key -out /etc/pki/tls/certs/mydomain.pem
Generating a 2048 bit RSA private key
...............+++
..............................+++
writing new private key to '/etc/pki/tls/private/mydomain.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:MyState
Locality Name (eg, city) [Default City]:MyCity
Organization Name (eg, company) [Default Company Ltd]:MyOrganization
Organizational Unit Name (eg, section) []:Security
Common Name (eg, your name or your server's hostname) []:mydomain.org
Email Address []:myaddress@myemailprovider.com
[root@li569-172 html]# cd /etc/pki/tls
[root@li569-172 tls]# ls -la certs
total 1228
drwxr-xr-x 2 root root 4096 Nov 21 15:55 .
drwxr-xr-x 5 root root 4096 Apr 10 2012 ..
-rw-r--r-- 1 root root 571450 Apr 7 2010 ca-bundle.crt
-rw-r--r-- 1 root root 651083 Apr 7 2010 ca-bundle.trust.crt
-rw-r--r-- 1 root root 1436 Nov 21 15:55 mydomain.pem
-rw------- 1 root root 1123 Nov 21 15:51 localhost.crt
-rwxr-xr-x 1 root root 610 Mar 28 2012 make-dummy-cert
-rw-r--r-- 1 root root 2242 Mar 28 2012 Makefile

Then confirm contents of cert:

# openssl x509 -text -in certs/cerif.pem
Certificate:
 Data:
 Version: 3 (0x2)
 Serial Number:
 c5:53:e0:89:8f:8a:ec:d3
 Signature Algorithm: sha1WithRSAEncryption
 Issuer: C=US, ST=MyState, L=MyCity, O=MyOrganization, OU=Security, CN=mydomain.org/emailAddress=myaddress@myemailprovider.com
 Not Before: Nov 21 15:55:54 2012 GMT
 Not After : Nov 29 15:55:54 2022 GMT
 Subject: C=US, ST=MyState, L=MyCity, O=MyOrganization, OU=Security, CN=mydomain.org/emailAddress=myaddress@myemailprovider.com
 Subject Public Key Info:
 Public Key Algorithm: rsaEncryption
 Public-Key: (2048 bit)
 Modulus:
 [...]
 Exponent: 65537 (0x10001)
 X509v3 extensions:
 X509v3 Subject Key Identifier: 
 58:9D:54:1F:A4:D8:72:19:51:12:01:82:73:0A:DD:7C:F7:15:8B:A8
 X509v3 Authority Key Identifier: 
 keyid:58:9D:54:1F:A4:D8:72:19:51:12:01:82:73:0A:DD:7C:F7:15:8B:A8
 X509v3 Basic Constraints: 
 CA:TRUE
 Signature Algorithm: sha1WithRSAEncryption
 [...]
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----

Make sure httpd configuration points to the key and cert just generated. In /etc/httpd/conf.d/ssl.conf

# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A new
# certificate can be generated using the genkey(1) command.
SSLCertificateFile /etc/pki/tls/certs/mydomain.pem
# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /etc/pki/tls/private/mydomain.key

Now, generate a key pair and cert for SimpleSAMLphp (SSP) use (signing and encryption), point SSP configuration at appropriate location.

Generate key pair and cert:

# openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out mydomain.org.crt -keyout mydomain.org.pem

Generating a 2048 bit RSA private key
.......................................................................+++
...+++
writing new private key to 'mydomain.org.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:MyState
Locality Name (eg, city) [Default City]:MyCity
Organization Name (eg, company) [Default Company Ltd]:MyOrganization
Organizational Unit Name (eg, section) []:Security
Common Name (eg, your name or your server's hostname) []:mydomain.org
Email Address []:myaddress@myemailprovider.com

Move to cert directory in location where simplesamlphp is installed (here /var/simplesamlphp/cert)

mv mydomain* cert /var/simplesamlphp/cert

Change ownership and permissions:

# chown apache:apache /var/simplesamlphp/cert/mydomain.org.pem
# chmod 600 /var/simplesamlphp/cert/mydomain.org.pem
# ls -la /var/simplesamlphp/cert
total 16
drwxr-xr-x 2 root root 4096 Aug 1 21:36 .
drwxr-xr-x 19 root root 4096 Aug 2 22:42 ..
-rw-r--r-- 1 root root 1415 Aug 1 21:36 mydomain.org.crt
-rw------- 1 apache apache 1704 Aug 1 21:36 mydomain.org.pem

Next, change the simplesamlphp config to point to the new key and cert just generated:

# vim metadata/saml20-idp-hosted.php

...
$metadata['__DYNAMIC:1__'] = array(
 /*
 * The hostname of the server (VHOST) that will use this SAML entity.
 *
 * Can be '__DEFAULT__', to use this entry by default.
 */
 'host' => '__DEFAULT__',

 /* X.509 key and certificate. Relative to the cert directory. */
 'privatekey' => 'mydomain.org.pem',
 'certificate' => 'mydomain.org.crt',
...

Additional configuration

Edit Apache Web Server ssl configuration

Edit /etc/httpd/conf.d/ssl.conf

Just before the end of the virtual host element definition, insert the following alias lines (depending on the social IdPs to be used):

# ==> add aliases to configure for simplesamlphp operation
Alias /simplesaml /var/simplesamlphp/www
Alias /google /var/simplesamlphp/www
Alias /twitter /var/simplesamlphp/www
# <== end adds

Other aliases that could optionally be defined if the corresponding IdP is to be supported in your deployment:

Alias /glwmulti /var/simplesamlphp/www
Alias /ficam1 /var/simplesamlphp/www
Alias /linkedin /var/simplesamlphp/www
Alias /windowslive /var/simplesamlphp/www
Alias /facebook /var/simplesamlphp/www
Alias /twitter /var/simplesamlphp/www
Alias /paypal /var/simplesamlphp/www
Alias /yahoo /var/simplesamlphp/www
Alias /verisign /var/simplesamlphp/www
Alias /Incommon /util

Generate secret salt value for generating secure hashes

tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo

Save the resulting string someplace where it can be copy-pasted into the simplesamlphp file config.php (next step).

Edit simplesamlphp file config.php

Edit /var/simplesamlphp/config/config.php

Set password for admin login to SSP IdP web console by editing this line in the config.php file:

'auth.adminpassword' => '***',

Copy/paste secret salt generated in the previous step into the following line in the config.php file:

'secretsalt' => '***',

Set the technical contact information for the SSP IdP:

'technicalcontact_name' => '***',
'technicalcontact_email' => '***',

Edit simplesamlphp metadata config file saml20-idp-hosted.php

If you did not do this already as described above, edit /var/simplesamlphp/metadata/saml20-idp-hosted.php

point at the cert/key pair that were generated for SSP (see above) in the following two lines in the file:

'privatekey' => 'mydomain.org.pem',
'certificate' => 'mydomain.org.crt',

Configure attribute mapping to release eduPersonPrincipalName

In the Bamboo security domain, eduPersonPrincipalName (ePPN) is used as the unique user identifier asserted by an IdP (this is the attribute that is encrypted via one-way SHA-256 hash to become the unique user identifier component of the "SourcedId" discussed on the Identity and Access Management - Authentication and Authorization wiki page, see the section "SourcedId requirements in calls to the Person Service" on that page).

The Social/SAML gateway must be configured to properly construct an ePPN from attributes asserted by a given Social IdP. While a discussion of how to write the necessary configurations is beyond the scope of this document (cf. documentation at simplesaml.org for more info), configuration files for a number of commonly-used Social IdPs are available in the attributemaps/ directory of the simplesamlphp v1.10.0 distribution attached to this page. For some of these, mapping to ePPN is already configured by default (e.g., see attributemap/linkedin2name.php). For others, such as Google, the mapping needs to be uncommented in the relevant configuration file. So, for example, in the file attributemap/google2name.php, the following line:

 // 'openid' => 'eduPersonPrincipalName',

needs to be uncommented by removing the leading "// ":

'openid' => 'eduPersonPrincipalName',

Configuration files for each Social IdP to be used should map the appropriate social provider attributes to eduPersonPrincipalName.

Bounce Apache Web Server

/sbin/service httpd restart

Review and test

Log into the SSP IdP web console as admin with the password configured in config.php above by browsing to

https://mydomain.org/simplesaml

You should see a welcome page and a tabbed header that also includes Configuration, Authentication and Federation tabs

Click the Configuration tab and confirm that things are working as expected (the bullets under Configuration are live links)

Test configured authentication sources

Click the Authentication tab, select "Test configured authentication sources" and click on the social IdPs you have configured above

For each chosen IdP you should be prompted to authenticate and then returned to a "SAML 2.0 SP Demo Example" page that displays the attributes returned from the SSP IdP Gateway

Test your SSP IdP against Testshib's SP

At this point, revisit https://mydomain.org/simplesaml

• Click on the Federation tab, then on the "Show metadata" link under SAML 2.0 IdP METADATA

• Select and copy the metadata – everything between (and including) the following lines:

<?xml version="1.0"?>
</md:EntityDescriptor>

Paste and save this IdP metadata into a file (e.g., some-social-idp.metadata). You will need it later, to configure external SPs to use this metadata information; procedures will depend on the model of federation in use by those SPs

Next, follow the instructions provided at http://testshib.org starting at "Register" under the heading "General Steps"

• At the Register step, you will be asked to upload the SSP IdP metadata file you saved earlier (see previous step). If the upload is successful, you should see a web page that displays the verified contents of your metadata file.
• Copy and save the entityId string inside the quotation marks on the line near the top that looks like this:

entityID="https://mydomain.org/simplesaml/saml2/idp/metadata.php">

That entityId string will be needed when you test against Testshib's SP later.

• Get and save a local copy of the Testshib metadata file from https://www.testshib.org/metadata/testshib-providers.xml
• Convert that file to the metadata format used by SSP by using the tool on the SSP admin web console under the Federation tab "XML to simpleSAMLphp metadata converter"
• Select/copy the data under the heading "saml20-sp-remote" between (and including) the lines

$metadata['https://sp.testshib.org/shibboleth-sp'] = array (
...
...
),
),
),
);

• Save a renamed copy of the original /var/simplesamlphp/metadata/saml20-sp-remote.php file
• Create a new /var/simplesamlphp/metadata/saml20-sp-remote.php file that contains the converted Testshib metadata from the previous step
  • Note: don't forget the code block must be inserted in a  wrapping <?php ?> tag

• Bounce the web server on the SSP IdP:

/sbin/service httpd restart

• Browse to the Testshib SP: https://sp.testshib.org/
• Paste the SSP IdP entityId (found above) into the textbox and click Go.
• You should be redirected to a SSP IdP discovery page where you can select your social provider, and after successfully authenticating there, you should be redirected to a page headed "Shibboleth-protected TestShib Content". If so, your configuration is correct and your SSP IdP is operational.