Page tree

Versions Compared

Key

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

Table of Contents

Overview

This document gives These are instructions for installing the simpleSAMLphp framework . simpleSAMLphp is an alternative to using the Internet2 Shibboleth service provider software. This means that if you want to use simpleSAMLphp, then you do not have to install the Internet2 shibd software.

Install simpleSAMLphp

Download SimpleSAMLphpand configuring it to work with MyAccess. If your application is written in PHP, you may prefer to use simpleSAMLphp rather than Shibboleth.

These instructions assume you are using the Apache web server on a UNIX-like operating system. simpleSAMLphp will also work on Windows, but you will need to adjust the instructions. They were written for simpleSAMLphp 1.10.0, but will probably work on other versions.

For simpleSAMLphp to work, your PHP install needs to have the mcrypt module loaded. If you intend to use simpleSAMLphp with Drupal, you will also need the sqlite PHP module.

Install simpleSAMLphp

Download the latest version of simpleSAMLphp:

http://code.google.com/p/simplesamlphp/downloads/

Unpack the archive into /opt and make a symbolic link without the version number:

Code Block
Installcd it in /var, then sym link it to simplesamlphp:
/opt
sudo tar -xvzf ~/simplsamlphp-x.x.x.tar.gz
sudo ln -s /var/simplesamlphp-1x.8x.1x /var/simplesamlphp

Configure Apache

Apache has to know where SimpleSAMLphp is located. So, in ssl.conf add the following in the VirtualHost sectionThe www directory in the simpleSAMLphp distribution needs to be accessible through the web server. To do that, add the following line to your Apache configuration:

Code Block
Alias /simplesaml /varopt/simplesamlphp/www

The restart Then reload your Apache configuration:

Code Block
sudo /sbin/service httpd restart

Configure SP

See the "Configuring the SP" section of the following doc:

http://simplesamlphp.org/docs/1.8/simplesamlphp-sp

After you generate the X509 cert, edit config/authsources.php and make 'default-sp' section look like this:

Code Block
// An authentication source which can authenticate against both SAML 2.0
// and Shibboleth 1.3 IdPs.
'default-sp' => array(
     'saml:SP',
     'privatekey' => 'saml.pem',
     'certificate' => 'saml.crt',
     // The entity ID of this SP.
     // Can be NULL/unset, in which case an entity ID is generated based on the metadata URL.
     'entityID' => 'https://hostname.ucsf.edu/simplesaml/module.php/saml/sp/metadata.php/default-sp',

     // The entity ID of the IdP this should SP should contact.
     // Can be NULL/unset, in which case the user will be shown a list of available IdPs.
     'idp' => 'https://idp-stage.ucsf.edu/idp/shibboleth',

     // The URL to the discovery service.
     // Can be NULL/unset, in which case a builtin discovery service will be used.
     'discoURL' => NULL,
),
Note
titleAttention

Be sure to replace hostname above with the name of your server. Also, if you are integrating with MyAccess production, replace idp-stage.ucsf.edu with dp.ucsf.edu. Of course, this is if you are just integrating with MyAccess. If this is a federated app and you need to integrate with multiple IdPs, then leave it as NULL.

Set Admin Password and Contact Info

Code Block
In /var/simplesamlphp/config/config.php set 'auth.adminpassword' to the password of your choosing, then set the following:

'technicalcontact_name'     => 'Your app or department name',
'technicalcontact_email'    => 'your.support.email@ucsf.edu',

Also, set oid2name attribute mapper in the authproc.sp section. It should look like this:

Code Block
'authproc.sp' => array(
        /*
        10 => array(
                'class' => 'core:AttributeMap', 'removeurnprefix'
        ),
        */

        /* When called without parameters, it will fallback to filter attributes ‹the old way›
         * by checking the 'attributes' parameter in metadata on SP hosted and IdP remote.
         */
        50 => 'core:AttributeLimit',
        /* Map OIDs to names, as we can remember names easier than numbers. */
        51 => array('class' => 'core:AttributeMap', 'oid2name'),
        /*
         * Generate the 'group' attribute populated from other variables, including eduPersonAffiliation.
         */
        60 => array('class' => 'core:GenerateGroups', 'eduPersonAffiliation'),
        // All users will be members of 'users' and 'members'   
        61 => array('class' => 'core:AttributeAdd', 'groups' => array('users', 'members')),
        
        // Adopts language from attribute to use in UI
        90 => 'core:LanguageAdaptor',

),
Note
titleAttention

If you are setting up this simpleSAMLphp installation to work with Drupal, then you need to configure something other than phpsession as the session storage mechanism. The easiest thing to do is use sqlite (although, this may require you to configure the SQLite PHP module in php.ini). To do this, set the following in the "Configure the datastore for simpleSAMLphp" of config.php:

Code Block
'store.type' => 'sql'
'store.sql.dsn' => 'sqlite:/path/to/simplesamlsessiondb.sq3'

Make sure that Apache can write to the path and db file specified above.

MyAccess Metadata

Depending on whether or not you are integrating with MyAccess stage or production, you will want to take the code from one of the sections below and put it in the following file:

Code Block
/var/simplesamlphp/metadata/saml20-idp-remote.php

Below are simpleSAMLphp-friendly versions of the MyAccess IdP metadata.

Stage metadata

Code Block
<?php

$metadata['https://idp-stage.ucsf.edu/idp/shibboleth'] = array (
  'entityid' => 'https://idp-stage.ucsf.edu/idp/shibboleth',
  'contacts' => 
  array (
  ),
  'metadata-set' => 'saml20-idp-remote',
  'SingleSignOnService' => 
  array (
    0 => 
    array (
      'Binding' => 'urn:mace:shibboleth:1.0:profiles:AuthnRequest',
      'Location' => 'https://idp-stage.ucsf.edu/idp/profile/Shibboleth/SSO',
    ),
    1 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
      'Location' => 'https://idp-stage.ucsf.edu/idp/profile/SAML2/POST/SSO',
    ),
    2 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign',
      'Location' => 'apachectl graceful

On certain operating systems (Ubuntu, Debian) you may need to use "apache2ctl" instead of "apachectl".

Create SSL certificate

Generate an SSL certificate and key that simpleSAMLphp will use to secure communication with the UCSF MyAccess IdP. Run the following commands:

Code Block
cd /opt/simplesamlphp/cert
sudo openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Answer the questions, but don't worry too much about the answers. This information won't be visible to your users.

Configure simpleSAMLphp

Edit the file /opt/simplesamlphp/config/authsources.php and make the following changes.

Configure SSL cert

Let simpleSAMLphp know about the SSL certificate and key you just created. Find the "default-sp" section, and add these lines:

Code Block
'privatekey' => 'saml.pem',
'certificate' => 'saml.crt',

Set entityID

Still in the "default-sp" section, find the "entityID" line and set the value to the domain name of your app followed by "/simplesaml". For example:

Code Block
'entityID' => 'https://YOUR-DOMAIN-HERE.ucsf.edu/simplesaml',

Specify an Identity Provider

Still in the "default-sp" section, find the "idp" line and set the value to match the MyAccess IdP you want to use. Unless you've been told otherwise, use the staging IdP.

  • Production: urn:mace:incommon:ucsf.edu (https://dp.ucsf.edu/idp/shibboleth is deprecated and should no longer be used)
  • Staginghttps://idp-stage.ucsf.edu/idp/

...

  • shibboleth
  • Developmenthttps://idp-

...

  • dev.ucsf.edu/idp/

...

  • shibboleth

 For example:

Code Block
'idp' => 'https://idp-stage.ucsf.edu/idp/pre_logout.jsp?url=https://hostname.ucsf.edu',
  'ArtifactResolutionService' => 
  array (
    0 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding',
      'Location' => 'https://idp-stage.ucsf.edu:8443/idp/profile/SAML1/SOAP/ArtifactResolution',
      'index' => 1,
    ),
    1 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP',
      'Location' => 'https://idp-stage.ucsf.edu:8443/idp/profile/SAML2/SOAP/ArtifactResolution',
      'index' => 2,
    ),
  ),
  'keys' => 
  array (
    0 => 
    array (
      'encryption' => true,
      'signing' => true,
      'type' => 'X509Certificate',
      'X509Certificate' => '
MIICSTCCAbKgAwIBAgIES6G0XDANBgkqhkiG9w0BAQUFADBpMQswCQYDVQQGEwJVUzELMAkGA1UE
CBMCQ0ExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xDTALBgNVBAoTBFVDU0YxDjAMBgNVBAsTBU9B
QUlTMRYwFAYDVQQDEw1kNW4xLnVjc2YuZWR1MB4XDTEwMDMxODA1MDQyOFoXDTIwMDMxNTA1MDQy
OFowaTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1TYW4gRnJhbmNpc2NvMQ0w
CwYDVQQKEwRVQ1NGMQ4wDAYDVQQLEwVPQUFJUzEWMBQGA1UEAxMNZDVuMS51Y3NmLmVkdTCBnzAN
BgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAsOc8xqTk6GD3WIaw/qheJ+YTXWTKdt831hxcnSenjRg1
PwnXmfIOmO/sACyGUF3UWJiaboHZZTxVCsVziTB8y6g3fI88yE2hudJDRKEL90m9l3m/LKmWN6MZ
WiEnd5GvpfDU497hJkC3hemG7Vwq0Ui/1vSx9lFmQ7585yQAQQMCAwEAATANBgkqhkiG9w0BAQUF
AAOBgQA2aFehGkLM7C9xDWBmwqS2HdbMeYnmItkl7ye8bNjuNB6G80wAtER8KcPwEHElHThbMM0J
KBCPTzogMRseLFGsHKP1msFkZe1rYcwKt5Nkrkp6A5rLqxrioCvc+vNwod+R99RZz2gCZPJvaqM0
5WaQ9pcTT6yB31fqqd2xrLFEjA==
                    ',
    ),
  ),
  'scope' => 
  array (
    0 => 'ucsf.edu',
  ),
);

Production metadata

Code Block
<?php

$metadata['https://dp.ucsf.edu/idp/shibboleth'] = array (
  'entityid' => 'https://dp.ucsf.edu/idp/shibboleth',
  'contacts' => 
  array (
  ),
  'metadata-set' => 'saml20-idp-remote',
  'SingleSignOnService' => 
  array (
    0 => 
    array (
      'Binding' => 'urn:mace:shibboleth:1.0:profiles:AuthnRequest',
      'Location' => 'https://dp.ucsf.edu/idp/profile/Shibboleth/SSO',
    ),
    1 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
      'Location' => 'https://dp.ucsf.edu/idp/profile/SAML2/POST/SSO',
    ),
    2 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign',
      'Location' => 'https://dp.ucsf.edu/idp/profile/SAML2/POST-SimpleSign/SSO',
    ),
    3 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
      'Location' => 'https://dp.ucsf.edu/idp/profile/SAML2/Redirect/SSO',
    ),
  ),
  'SingleLogoutService' => 'https://dp.ucsf.edu/idp/pre_logout.jsp?url=https://hostname.ucsf.edu',
  'ArtifactResolutionService' => 
  array (
    0 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding',
      'Location' => 'https://dp.ucsf.edu:8443/idp/profile/SAML1/SOAP/ArtifactResolution',
      'index' => 1,
    ),
    1 => 
    array (
      'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP',
      'Location' => 'https://dp.ucsf.edu:8443/idp/profile/SAML2/SOAP/ArtifactResolution',
      'index' => 2,
    ),
  ),
  'keys' => 
  array (
    0 => 
    array (
      'encryption' => true,
      'signing' => true,
      'type' => 'X509Certificate',
      'X509Certificate' => '
MIIDFzCCAf+gAwIBAgIUW2hLRYSTq6yflHpRZ5ZBXty14rYwDQYJKoZIhvcNAQEFBQAwFjEUMBIG
A1UEAxMLZHAudWNzZi5lZHUwHhcNMDkwODI5MDQwMzU5WhcNMjkwODI5MDQwMzU5WjAWMRQwEgYD
VQQDEwtkcC51Y3NmLmVkdTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAK+WY9j/fuME
Q2u4mKKeU5LXO+mi7BKKkJP3PUN0Iz4whL/M9uTR+C7x6DCVbi4CXNia8hmoNbWIKCKto9UJT/e+
Y4y+dZjC4TLcIvdUog7x4/3qlcwI76jkomyL5uy2/7Ow+l/pmX99wph+K4/d8EpwE3NTXcFOVv1D
8M3pUrVEfT1aoAm7p4SXS3uohM7KDXTljqtxImt/Q+cRFBImNyp7YTFp37024eMwtNfLJxEajodI
FOCCYP6DmN5I1RWTF808BPPbkt7agjuz50pCdXHxfgnCfUmHeeUz4yLI6cgOWkB9JISN567vAH68
IInM9with782aIsVLf2Fs5pQqxECAwEAAaNdMFswOgYDVR0RBDMwMYILZHAudWNzZi5lZHWGImh0
dHBzOi8vZHAudWNzZi5lZHUvaWRwL3NoaWJib2xldGgwHQYDVR0OBBYEFDfsmZZFJeq4xHogyRDy
+1N69EEKMA0GCSqGSIb3DQEBBQUAA4IBAQBiK5W3RyQc/LL+FOy9mQIFzmobtJCGYUHwn/jMzZ+F
diV688MOA94AHGnxlvjjlVE7sjI83XgUK80IpLWz1QtCN9Pcwo5M0tNCxOFAkIe1xRadZmN4LpFO
enH8vd5TF7DjrozFivFC4+l/mTTW4hfl+RaR34zgrzBAv+fUNrq7cNrid11w0h17HNqD964TR4Qp
hmFyIrFR9skSs+41ScRMa4c7Svel8p4f+ptoATHSlSm0OZayjktgJp4o+Ld8xiH8Q5oLQ/qNG0hx
9IRMaum9h0HCnxwHKsrxcJW2/A/CVhaVlj4Jp/B3Zs13i2Wc6VGZGK1rfVetLqSnvfVPnT+h
                    ',
    ),
  ),
  'scope' => 
  array (
    0 => 'ucsf.edu',
  ),
);
Note
titleAttention

Be sure to replace hostname in the SingleLogoutService section with with the name of your server.

Configure PHP

PHP needs to have mcrypt enabled, to do this, do the following (assuming you are on a Linux RedHat or CentOS system):

Code Block
sudo yum -y install php-mcrypt.x86_64
sudo /sbin/service httpd restart

Integrate With MyAccess

At this point you are ready to integrate with MyAccess. You should open up a service ticket with ITS (http://help.ucsf.edu/ then click on "Submit a ticket for ITS or School of Nursing IT") and include the following information:

Subject indicating that the request is for "MyAccess Shibboleth test or production"
Attributes you want to get back from their IdP (and if you want ones that were not covered above, then you need to ask them for the OID for the attribute and configure it in attribute-map.xml)
URL for your metadata (so that they can download the metadata, or attach the metadata file to the ticket)
Indicate which attributes you would like to receive from MyAccess

...

shibboleth',

 

Set Admin Password

Close authconfig.php and open config.php. Find the auth.adminpassword line, and set it to a value of your choice. Please do not use the same password you use elsewhere at UCSF. For example: 

Code Block
'auth.adminpassword' => 'not a good password', 

Set Contact Information

Find the lines for technicalcontact_name and technicalcontact_email and set them to your name and email address, or those of the person who will be maintaining the application. For example:

Code Block
'technicalcontact_name'     => 'Joe Schmo',
'technicalcontact_email'    => 'joe.schmo@ucsf.edu',

Convert Attribute Names

You'd probably rather deal with attribute names like "givenName" and "email" than "urn:oid:2.5.4.42" and "urn:oid:1.2.840.113549.1.9.1", wouldn't you? simpleSAMLphp will convert them for you, but you have to tell it to. Find the "authproc.sp" section, and add this line:

Code Block
51 => array('class' => 'core:AttributeMap', 'oid2name'),

Drupal Only: Change Session Store

If you are going to use simpleSAMLphp with Drupal, you need to change the way that simpleSAMLphp stores its session data. Find the store.type and store.sql.dsn lines and change them to this:

Code Block
'store.type' => 'sql'
'store.sql.dsn' => 'sqlite:/tmp/simplesamlsessiondb.sq3'

For this to work, you will also need to have the SQLite PHP module installed.

Load Metadata

Download the attached saml20-idp-remote.php and shib13-idp-remote.php files and save them into /opt/simplesamlphp/metadata/. 

Save SP Metadata

To integrate with MyAccess, you will need to send us a copy of your SP's metadata. You can get that by visiting this URL, replacing "hostname.ucsf.edu" with your site's domain name:

https://hostname.ucsf.edu/simplesaml/module.php/saml/sp/metadata.php/default-sp