Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Social/SAML Gateway to enable social media identity provision

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Table of Contents

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

 

Tip

The U Texas implementation is based on SimpleSAMLphp (SSP) version 1.10.0. The official documentation for the SSP IdP is at http://simplesamlphp.org/docs/stable/simplesamlphp-idp

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.

 

Warning

Add note here re: role of simplesaml IdP in relation to rest of IAM components, esp. vis-a-vis guidance regarding re-use (or not) of certificates from elsewhere in the infrastructure

 

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)

Code Block
# 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:

Code Block
# 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

Code Block
# 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

Anchor
ssp-cert-generation
ssp-cert-generation

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:

Code Block
# 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)

Code Block
mv mydomain* cert /var/simplesamlphp/cert

 

Change ownership and permissions:

Code Block
# 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:

Code Block
# 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

Anchor
social-idp-configuration
social-idp-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):

Code Block
# ==> 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:

 

Code Block
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

Code Block
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:

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

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

Code Block
'secretsalt' => '***',

Set the technical contact information for the SSP IdP:

Code Block
'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:

Code Block
'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:

Code Block
 // 'openid' => 'eduPersonPrincipalName',

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

Code Block
'openid' => 'eduPersonPrincipalName',

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

 

Bounce Apache Web Server

Code Block
/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

Code Block
https://mydomain.org/simplesaml

You should see a welcome page and a tabbed header that also includes ConfigurationAuthentication 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:

 

Code Block
<?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:
Code Block
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

 

Code Block
$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

 

Tip

When you add real SPs, you will need to append their corresponding converted metadata to the end of the saml20-sp-remote.php file for your IdP to recognize them as valid SP endpoints

  • Bounce the web server on the SSP IdP:

 

Code Block
/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.