1. How-To Connect a myVocs box instance to an external Identity Provider
    1. Background Concepts
      1. Architectural Overview
      2. External Interfaces
    2. Customizing VM Settings
    3. Change the root Password
    4. Bug Fixes/Work Arounds
    5. Change Hostname
    6. Change the IP address
    7. Change the Sendmail config
    8. Sympa Configuration
    9. Apache Configuration
    10. Reboot to reflect the hostname change
    11. Shibboleth Configuration
      1. Metadata
      2. External Identity
      3. Service Provider Configuration
      4. Internal System Configuration
    12. Ready for Testing
    13. Note for Updating System IdP Config

How-To Connect a myVocs box instance to an external Identity Provider

This how-to tries to cover the steps necessary to change the configuration in order to hook a myVocs box instance to an external identity provider. The steps are pretty much identical for connecting to a federation, you just need to deal with your federation metadata. In this example, we'll be hooking a myVocs box instance to openidp.org, the open identity provider.

Background Concepts

Architectural Overview

It's important to get clarify your understanding of the overall concept before we begin. We need to keep in mind what our architecture looks like so we don't get lost in the deep dark woods of XML configuration files.

The idea is simple. We have a system (myVocs box instance) that will act as a service provider (a.k.a. application) and accept identities from one or more identity providers. This isn't really any different than any other Shibboleth configration. It's a many (the identity providers) to one (the myVocs box instance acting as a service provider) relationship. It's really just like any system integration we would do with an external identity source be it htpasswd, LDAP, Pubcookie, or ... Shibboleth. The only difference with Shibboleth is that it supports federated identities (ie. inter-organizational or cross-domain identity trusts). In this example, the identities will be supplied by openidp.org.

The part that can get confusing when configuring myVocs box is that not only is Shibboleth used to get identity information from external identity sources into the system environment, but Shibboleth is also used within the system to transport identity information throughout the system. That is, Shibboleth is used internally to distribute system identity information (user and group information) from the central storage location to all applications. The confusion can come about when you're in the bowles of the Shibboleth configuration files since you essentially have two Shibboleth configurations sitting side-by-side on the same box.

As delivered in the first release, myVocs box only has the systems internal Shibboleth configuration defined. The "external" identity source in this release is simply the common Auth Basic Apache service. The goal of this how-to is to replace this default identity source with a Shibboleth-based identity source, i.e. openidp.org.

External Interfaces

Our system has two external interfaces, or rather two parts to it's external interface. These are standard parts found in all system access scenarios: login and registration. Login is performed as part of normal use of a system. Registration is typically done once and the method depends on the system environment. The registration process might be an email to the owner of a Unix box, joining an organization, or filling out a web form. The web form is the most common process found on the web today and is, naturally, the interface exposed by myVocs box.

Customizing VM Settings

Change the VM name (optional)

This is a completely optional step, it's helpful if you have multiple test instances or want to name the default VM differently. By default the myvocs-box vm tarball unpacks into a directory named "myvocs-box". You can change the VMs display name through VMware interfaces, but if you want the directory names and files to look different (and to help avoid confusion). You can run the mvb-rename.sh script from the directory where you unpacked the mvb vm tarball.

  1. Save the mvb-rename.sh script to the directory where you upacked the vm tarball.
  2. Run the script with the current and new names (much like the unix mv command): 
      bash ./mvb-rename.sh myvocs-box yourvocs-box

Note1: This script only impacts how you reference the VM instance on your file system with the VMware tools. It does not change any internal naming of the myVocs box instance itself. Please follow the reset of the instructions to make those changes.

Note2: If you change the name of an existing VM instance that is registered on a VM hosting platform like VMware Server you should remove the VM from the listing first and then re-add it after the rename is complete.

Change the VM Network Connection Type

If you're going to integrate myVocs box with an existing federation or other IdP you'll likely want it to be directly connected to the internet. As shipped, the myVocs box instance will use the VMware NAT network. To connect directly to the internet, you'll need to change that to the "bridged" network device (or do some configuration of your NAT, which is beyond scope.)

Changing to bridged networking is easy. Change to the directory containing the VM files and edit the file with the .vmx extension. Change the line: 

  Ethernet0.connectionType = "nat"

to 

 Ethernet0.connectionType = "bridged"

Note: You may want to hold off on the bridged network device change until you are ready to move your machine to the public network. This could happen after you complete the Apache config section below. Add definitely after you have changed the root password.

Change the root Password

You should the root password from the default after your first boot. It's critical to do this before you put the machine on a public network. You've been warned.

Bug Fixes/Work Arounds

There are a couple of bug and configuration errors in the distributed v0.1 of myVocs box. Some impact the performance and operation when switching to fedarted authentication. Please apply these bug fixes manually:

  • Bug #15 workaround: cd /var/www/myvocs-box; mv dispatch.cgi dispatch.cgi-disable
  • Bug #25 workaround 1: cd /etc/mail/; ci -l -m"start local config" sendmail.mc
  • Bug #25 workaround 2: 
    cd /etc/apache/config; ci -l -m"start local config" \
  mod_ssl-01-myvocs-box.conf vhost-01-myvocs-box.conf \
  fastcgi.conf mod_shib.conf
  • Bug #25 workardoun 3: 
    cd /etc/shibboleth
ci -l -m"start local config" myvocs-box-metadata.xml
cd /etc/shibboleth-sp
ci -l -m"start local config" AAP.xml
  • Bug #26 workaround: cp /dev/null /etc/mail/sympa_aliases; make -C /etc/mail
  • Bug #27 workaround: Change the first redirect match rule in /etc/apache/conf.d/vhost_01_myvocs-box to: 
    RewriteCond %{SERVER_PORT} 80
RewriteRule ^/tools/secure/(.*) https://%{SERVER_NAME}/tools/secure/$1 [R,L]

and the second Redirect match to: 

RewriteRule ^/(sympa/sso_login/sso.*)$ https://%{SERVER_NAME}/$1 [R,L]
  • Bug #19 workaround: cp -rp /var/www/myvocs-box/tools/secure/ /var/www/myvocs-box/tools/secext

For the next two bug fixes you'll need to first install the patch command. It'll probably be best if you wait to fix these bugs until after you've renamed your host and put it on the network and are working through your shibboleth configuration. 

apt-get install patch
  • Bug #28 workaround: removing hard coded values from the resolver-myvocs.xml. In order to fix this you need to download the resolver-myvocs.xml.patch file. Save it to /etc/shibboleth/ then run apply the patch: 
    patch -p0 < resolver-myvocs.xml.patch
  • Bug #20: correct hard coded values in voms scripts. In order to fix this you need to download the scripts.patch file. Save it to /var/www/myvocs-box/voms then run apply the patch: 
    patch -p0 < scripts.patch

After the patches are applied you can update the scripts to reflect your new host name. 

cd /var/www/myvocs-box/voms/scripts
for file in `grep -rl _MVB_HOSTNAME_ *`
do
  sed -e 's/_MVB_HOSTNAME_/yourvocs-box/' $file $file.new
  mv $file.new $file
done

Change Hostname

myVocs box is built on a Debian distribution. For background, review the general overview of updating the hostname, ip address, and network routing configuration for Debian.

Changing the hostname according to Debian procedures is pretty easy.

echo new.host.name > /etc/hostname; /etc/init.d/hostname.sh restart

This will change the hostname but you should restart the box to make other services recognize the new name.

Change the IP address

Edit the file /etc/network/interfaces and change the address line to an appropriate address for your network. The default configuration is for DHCP so if you want to assign a static IP you'll need a file that looks similar to this: 

auto eth0
iface eth0 inet static
 address 10.0.0.128
 gateway 10.0.0.1
 netmask 255.255.0.0
 network 10.0.0.0
 broadcast 10.0.255.255

Use your own network numbers of course.

Change the Sendmail config

After changing the hostname, you'll need to update the sendmail masquerade. The sendmail config is needed to support accepting and sending messages for VO email lists and for registration communication

  • Edit /etc/mail/sendmail.mc.
  • Change the MASQUERADE_AS line to your new fully-qualified host name.
  • run make -C /etc/mail

Sympa Configuration

The /etc/sympa.conf file needs to be updated to reflect the new hostname. The follow set of commands should do the trick: 

cd /etc
sed -e "s/myvocs-box/yourvocs-box/" sympa.conf > sympa.conf.new
mv sympa.conf.new sympa.conf

Apache Configuration

The distributed Apache configuration with the bug #27 work-around applied can survive host name changes. There are other references to the string "myvocs-box" in the configuration but these point to directory spaces that don't change with hostname changes and to the certificates which can be changed to match the requirements of your federation. You'll want to adjust SSLCertificateFile and SSLCertificateKeyFile in mod_ssl-01-myvocs-box.conf to change your hostname certs.

Note: If you are working through the config prior to November 10, 2007 and configuring your instance against openidp.org or other open identity provider, you should be able to use the default certificate. If you are configuring against different IdPs? in stricter federations, you will need to update certificates during the shibboleth configuration described below.

Reboot to reflect the hostname change

At this point the host should be ready to reboot to make the hostname changes take place. The shibboleth configuration will still need updating, but this is a good point to get it to recognize its new name.

Remember to change your root password from the default.

Shibboleth Configuration

This is the heart of the configuration of myVocs box and the is the only element that controls federation versus isolation. The above configuration steps mearly serve to put myVocs box on the right footing and fix some unintended bugs.

Metadata

The metadata is the Shibboleth/SAML-specific identity record for your instance of myVocs box. It is needed whenever a SAML conversation is conducted. As described above in the architectural reveiw, myVocs box exchanges data in two identity realms: idenity information is gathered from external sources and identity information distributed to the system environment. In order to exchange data in both of these realms, myVocs box needs an appropriate end point identity in each realm. That end point identity is defined using metadata.

External Identity

As distributed in v0.1, myVocs box is not configured to leverage federated identity. It still has an "external" identity source, though it's not accessed using Shibboleth. The "external" source in the v0.1 distribution is just a classic identity source, the /etc/passwd database of the underlying Linux system. It is hooked into the web-based authentication sequence using the simple HTTP Basic Authentication mechanism integrated with the systems /etc/passwd data. This service has been termed the "short-circuit" identity provider because it loops back to a locally administered identity source rather than relying on a federated identity source (ie. a remotely administered or one not under your control). This approach was taken for a couple of reasons: it's easy to implement and provides the one piece of data needed by the collaboration system of myVocs box, an identity; and it supports running myvocs box in isolation while still allowing all sample applications to operate, specifically the local account definitions implicitly provide an email mailbox for the defined user identity. This short-circuit IdP is useful and will be retained in future versions, though it the plans are to fully integrate it with Shibboleth.

In order change this configuration and integrate your instance of myVocs box with other identity providers you need to define an end point identity for you instance of myVocs box (ie. the metadata) and change your externally facing Shibboleth configuration so it can act as the authentication service in place of the BasicAuth? service in the default config.

We'll break configuration change into a couple of steps. First, we'll change the Shibboleth configuration, and second, we'll describe the steps needed to create a unique end point identity. (The second step is optional and is not needed for initial functionality.)

Service Provider Configuration

Definging trusted identity sources is done via the service provider configuration of Shibboleth. This is the component that is integrated with the Apache server as a module and manages Shibboleth's SAML-based authentication sequence by coordinating the request for and processing of identity data from external sources.

A point of configuration confusion can occur here because the myVocs box instance will consume external identity information and, because it also hosts the sample VO applications, it also consumes the collaboration systems identity information (users and groups) used by the sample VO applications. In other words, it needs to act as a Shibboleth service provider when consuming the federated identity sources and as a distinct Shibboleth service provider when consuming the collaboration system's identities. The confusion stems from the fact that there is only one Shibboleth SP software instance on myVocs box and its configuration is contained in a single file. This file defines both the external facing SP configuration and the collaboration system's (or internal) SP configuration. Visualizing the external identity realm and internal collaboration system identity realm as distinct data spaces is relatively easy. It can be confusing to see these spaces described side-by-side in the shibboleth SP configuration file, though.

The Shibboleth SP configuration on myVocs box is contained in the directory /etc/shibboleth-sp. The standard file shibboleth.xml is the primary focus of the configuration changes. In that file are to primary sections: the RequestMap section that defines what part of the local URL namespace is integrated with Shibboleth services and the Applications section that defines specific Shibboleth configurations available to applications.

As distributed in v0.1, myVocs box defines only one Application in the Applications section. This is the application named default. It is available to the entire URL namespace on the myVocs box and is configured to consume the collaboration system's identity information (the user and group information). It is configured to talk to the collaboration system's internal identity information source, i.e. the IdP shipped with myVocs box. It should not be necassary to change this configuration at all unless we want to expand our collaboration tool collection beyond the sample applications hosted directly on myVocs box. Naturally, this is probably what you want to do, but the configuration is irrelavent at this point. It's described later in this document.

There are two interfaces to myVocs box that need to be able to consume external identities. The registration interface lets users from federated identity sources register to be a part of the collaboration environment, ie. they announce their identity to the myVocs box instance. The login interface lets returning users identify themselves to the sytem environment during future sessions with the collaboration enviroment. Note: these to interfaces are ripe for integration but at this time they are still treated seperately.

The RequestMap configuration requires that you identitfy the URL namespace elements served by the external application configuration. The RequestMap needs to modified to contain the following elements: 

<Host name="yourvocs-box">
...
   <!-- Begin external IdP configuration -->

   <!-- Login Internface -->
   <Path name="shibboleth-idp">
      <Path name="SSO" applicationId="myVocs-box-external"
          authType="shibboleth" requireSession="true"/>
   </Path>

   <!-- Registration Interface -->
   <Path name="sympa" applicationId="myVocs-box-external"
      authType="shibboleth" requireSession="true" />

   <!-- Tool for sanity checks-->
   <Path name="tools">
      <Path name="secext" applicationId="myVocs-box-external"
          authType="shibboleth" requireSession="true"/>
   </Path>

   <!-- End external IdP configuration -->
...
</Host>

Note that the RequestMap host name attribute was also changed from the default myVocs-box to the hostname you assigned to your instance, indicated as yourvocs-box.

A distinct application definition versus just defining a unique session intiator is desirable. You need a session to be established with the shib-sso service application and not for any of the other (internal) applications on this host. That is, the shib-authn process for all the other applications should still take place. If you don't do a distinct application, then the authn will ultimately fail because since there will be confusion between the authn state for the external idps and the authn state for the apps in the system.

You can add the myVocs-box-external application definition to the end of the Applications section, right before the close of the section </Applications>: 

<Application id="myVocs-box-external">
   <Sessions
      lifetime="7200"
      timeout="3600"
      checkAddress="true"
      consistentAddress="true"
      handlerURL="/shibboleth-idp/SSO/Shibboleth.sso"
      handlerSSL="true"
      cookieProps="; path=/; secure" >

      <SessionInitiator id="external" Location="/WAYF/external"
         Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
         wayfURL="https://sso.openidp.org/shibboleth-idp/SSO"
         wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

         <md:AssertionConsumerService Location="/SAML/POST" isDefault="true" index="1"
             Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/>
         <md:AssertionConsumerService Location="/SAML/Artifact" isDefault="false" index="2"
             Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/>
      </Sessions>

      <AAPProvider type="edu.internet2.middleware.shibboleth.aap.provider.XMLAAP"
         uri="/etc/shibboleth-sp/AAP-external.xml"/>

      <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
          uri="/etc/shibboleth-sp/openidp-metadata.xml"/>

      <saml:Audience>https://openidp.org/default</saml:Audience>

</Application>

Note the direct interfacing of the WAYF url with openidp.org. This will make openidp.org the sole external identity provider, as described in this example. Multiple IdPs? can be support by setting up a local WAYF, eg. the myVocs box login service.

It's worth also noting the definition of the HandlerURL. This is the interface that the SP provides to process identity assertions from external sources. It must be distinct from the handler used to process identity assertions within the collaboration system, as defined in the default application. The value in this example does not need to be changed. The setting is just pointed out for clarity.

The myVocs-box-external application defines it's own attribute acceptance policy file (AAP-external.xml) that can be used to control the basic attributes accepted from federated identity providers. The only attributes that are potentially used in v0.1 of myVocs-box are the ePPN and mail attributes. As such a basic AAP is sufficient. Create a file AAP-external.xml in the /etc/shibboleth-sp directory with the following contents: 

<AttributeAcceptancePolicy xmlns="urn:mace:shibboleth:1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"          
xsi:schemaLocation="urn:mace:shibboleth:1.0 /opt/shibboleth-1.3/share/xml/shibboleth/shibboleth.xsd">

        <AttributeRule Name="urn:mace:dir:attribute-def:eduPersonPrincipalName" Scoped="true" Header="REMOTE_USER" Alias="user">
        <!-- Basic rule to pass through any value. -->
        <AnySite>
            <Value Type="regexp">^[^@]+$</Value>
        </AnySite>
        </AttributeRule>

        <AttributeRule Name="urn:mace:dir:attribute-def:mail" Header="Shib-Person-email" Alias="email">
                <AnySite>
            <AnyValue/>
        </AnySite>
        </AttributeRule>

</AttributeAcceptancePolicy>

Finally, to trust openidp.org to supply identities, you need to record its metadata, which is referenced in the application config above. In the /etc/shibboleth-sp directory create a file named openidp-metadata.xml with the following content: 

<EntitiesDescriptor
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:shibmd="urn:mace:shibboleth:metadata:1.0"
    xsi:schemaLocation="urn:oasis:names:tc:SAML:2.0:metadata ../schemas/saml-schema-metadata-2.0.xsd urn:mace:shibboleth:metadata:1.0 ../schemas/shibboleth-metadata-1.0.xsd http://www.w3.org/2000/09/xmldsig# ../schemas/xmldsig-core-schema.xsd"
    Name="http://openidp.org"
    validUntil="2010-01-01T00:00:00Z">

<EntityDescriptor
   xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
   xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
   xmlns:shibmd="urn:mace:shibboleth:metadata:1.0"
   xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
   entityID="https://openidp.org"
   validUntil="2010-01-01T00:00:00Z">

   <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:mace:shibboleth:1.0">
      <Extensions>
         <shib:Scope xmlns:shib="urn:mace:shibboleth:metadata:1.0">openidp.org</shib:Scope>
      </Extensions>
      <KeyDescriptor use="signing">
         <ds:KeyInfo>
            <ds:X509Data>
               <ds:X509Certificate>
MIIC0jCCAjugAwIBAgICBwcwDQYJKoZIhvcNAQEEBQAwgakxCzAJBgNVBAYTAlVT
MRIwEAYDVQQIEwlXaXNjb25zaW4xEDAOBgNVBAcTB01hZGlzb24xIDAeBgNVBAoT
F1VuaXZlcnNpdHkgb2YgV2lzY29uc2luMSswKQYDVQQLEyJEaXZpc2lvbiBvZiBJ
bmZvcm1hdGlvbiBUZWNobm9sb2d5MSUwIwYDVQQDExxIRVBLSSBTZXJ2ZXIgQ0Eg
LS0gMjAwMjA3MDFBMB4XDTA2MDEwOTAxMTgzOFoXDTEwMDIxODAxMTgzOFowgZMx
CzAJBgNVBAYTAlVTMRAwDgYDVQQIEwdBbGFiYW1hMRMwEQYDVQQHEwpCaXJtaW5n
aGFtMSMwIQYDVQQKExpUaGUgT3BlbiBJZGVudGl0eSBQcm92aWRlcjEXMBUGA1UE
AxMOYWEub3BlbmlkcC5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvb3RAb3BlbmlkcC5v
cmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJmUMps46BWU1kK4NxDa1CLY
/1uTE6sXqPcrS2hjkrvwrqp6Zg3ykeH9OrsfbRlsaaA+S0znB+wFoIhudz4hSTsR
xgNEbMDuZGSis+tYt7FF8dSlMoH8Uwp5Sl6ODWHJ+Q0uFqTofQY039MA9xpBRr7Z
Ix2YsBzJ3d0a3LloDA2XAgMBAAGjHTAbMAwGA1UdEwEB/wQCMAAwCwYDVR0PBAQD
AgWgMA0GCSqGSIb3DQEBBAUAA4GBAB2PEMeCg1sHfc3/MjlWkGf97n30FVUJo4cx
lEX02kC4iwtm6y3BBu0C5EZI3W/iNF8PVDcy3L321HbI5ROvrf7TnyDuNDc52hKy
jILhXobH/ZN9pfLHvhaRcqVZ+zcSJV+9kLt+UMkfw85YWZ1Kd6LFwzlghLFhcIpW
IWGsKJsE
               </ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </KeyDescriptor>
      <ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding" Location="https://aa.openidp.org/shibboleth-idp/Artifact" index="1"/>
      <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
      <SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" Location="https://sso.openidp.org/shibboleth-idp/SSO"/>
   </IDPSSODescriptor>

   <AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol">
      <Extensions>
         <shib:Scope xmlns:shib="urn:mace:shibboleth:metadata:1.0">openidp.org</shib:Scope>
      </Extensions>
      <KeyDescriptor use="signing">
         <ds:KeyInfo>
            <ds:X509Data>
               <ds:X509Certificate>
MIIC0jCCAjugAwIBAgICBwcwDQYJKoZIhvcNAQEEBQAwgakxCzAJBgNVBAYTAlVT
MRIwEAYDVQQIEwlXaXNjb25zaW4xEDAOBgNVBAcTB01hZGlzb24xIDAeBgNVBAoT
F1VuaXZlcnNpdHkgb2YgV2lzY29uc2luMSswKQYDVQQLEyJEaXZpc2lvbiBvZiBJ
bmZvcm1hdGlvbiBUZWNobm9sb2d5MSUwIwYDVQQDExxIRVBLSSBTZXJ2ZXIgQ0Eg
LS0gMjAwMjA3MDFBMB4XDTA2MDEwOTAxMTgzOFoXDTEwMDIxODAxMTgzOFowgZMx
CzAJBgNVBAYTAlVTMRAwDgYDVQQIEwdBbGFiYW1hMRMwEQYDVQQHEwpCaXJtaW5n
aGFtMSMwIQYDVQQKExpUaGUgT3BlbiBJZGVudGl0eSBQcm92aWRlcjEXMBUGA1UE
AxMOYWEub3BlbmlkcC5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvb3RAb3BlbmlkcC5v
cmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJmUMps46BWU1kK4NxDa1CLY
/1uTE6sXqPcrS2hjkrvwrqp6Zg3ykeH9OrsfbRlsaaA+S0znB+wFoIhudz4hSTsR
xgNEbMDuZGSis+tYt7FF8dSlMoH8Uwp5Sl6ODWHJ+Q0uFqTofQY039MA9xpBRr7Z
Ix2YsBzJ3d0a3LloDA2XAgMBAAGjHTAbMAwGA1UdEwEB/wQCMAAwCwYDVR0PBAQD
AgWgMA0GCSqGSIb3DQEBBAUAA4GBAB2PEMeCg1sHfc3/MjlWkGf97n30FVUJo4cx
lEX02kC4iwtm6y3BBu0C5EZI3W/iNF8PVDcy3L321HbI5ROvrf7TnyDuNDc52hKy
jILhXobH/ZN9pfLHvhaRcqVZ+zcSJV+9kLt+UMkfw85YWZ1Kd6LFwzlghLFhcIpW
IWGsKJsE
               </ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </KeyDescriptor>
      <AttributeService Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding" Location="https://aa.openidp.org/shibboleth-idp/AA"/>
      <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
   </AttributeAuthorityDescriptor>

   <Organization>
      <OrganizationName xml:lang="en">openidp.org | The Open Identity Provider</OrganizationName>
      <OrganizationDisplayName xml:lang="en">openidp.org | The Open Identity Provider</OrganizationDisplayName>
      <OrganizationURL xml:lang="en">http://www.openidp.org/</OrganizationURL>
   </Organization>
   <ContactPerson contactType="technical">
      <SurName>Root</SurName>
      <EmailAddress>root@openidp.org</EmailAddress>
   </ContactPerson>

</EntityDescriptor>

</EntitiesDescriptor>

By default, openidp.org is configured to share user identities with any client (known or unknown) but it will only share the email address of the user with registered SPs. Since all a myVocs box instance needs in order to get started is an ePPN, the configuration to this point is sufficient to get operational. It is not necessary to supply metadata to openidp.org to get the ePPN. Information on preparing metadata for your instance of myvocs box to register with openidp.org or other IdPs? will be given later.

At this point you should be able to point your browser to https://yourvocs-box/tools/secext/printenv.pl (make sure you've applied the bug fix for bug #19 above). You should then see the openidp.org authentication page. After successful authentication, you will see a debug page at the URL you entered that displays the current set of attributes available to your instance of myVocs box. You should expect to see the REMOTE_USER variable populated with the identity of the user account at openidp.org which was used during authentication.

If this test succeeds, you instance of myVocs box is ready to use with openidp.org. Similar proceedures should enable you to hook in any number of external identity providers simply by configuring a proper WAYF service (and defining it for the WAYF url) and then adding the appropriate metadata entries. The specific rules governing other IdPs? should be documented by those IdPs?.

Internal System Configuration

The collaboration system environments, or internal, metadata is shared with the applications that will make up the your system environment. It already exists in the distributed myVocs box but needs to be updated to reflect the new network identity (hostname) of the myVocs box. While completely replacing the default internal metadata is the ultimate goal, as you build up the trusts and operating policies for your system environment, in these instructions we'll continue to use the provided sample applications. This means we can get away with some minimal changes.

Both the internal identity provider and service provider configuration need minor updates. First the service provider configuration needs to specify the new wayfURL for the system's IdP. This change is made to /etc/shibboleth-sp/shibboleht.xml in the default Application section. 

cd /etc/shibboleth-sp
sed -e '/wayfURL/s/myvocs-box/yourvocs-box/' shibboleth.xml > shibboleth.xml.new
mv shibboleth.xml.new shibboleth.xml

The next change is to the IdP's version of the metadata. A shibboleth IdP uses the metadata for SP's to validate some of the data supplied by the incoming requests. One of those items is the AssertionConsumerService? URL. The default references the myvocs-box hostname. It needs to be changed to reflect your new hostname. Edit the /etc/shibboleth/myvocs-box-metadata.xml and replace the Location attribute of the two AssertionConsumerService elements from myvocs-box` to your new hostname.

The final step is to fix the attribute acceptance policy of for the system environment so that it accepts un-scoped eduPersonPrincipleNames. The values are un-scoped because the system IdP has received a scoped value from the external IdP and converted that to a simple string. (The default config does scoping because the authn source doesn't provide a domain. See Bug #29 for details.) The work around is to apply the following patch to /etc/shibboleth-sp/AAP.xml. 

--- AAP.xml     2007/07/27 21:04:12     1.3
+++ AAP.xml     2007/07/30 18:19:13
@@ -66,11 +66,11 @@
         </AnySite>
        </AttributeRule>

-    <AttributeRule Name="urn:mace:dir:attribute-def:eduPersonPrincipalName" Scoped="true" Header="REMOTE_USER" Alias="user">
+    <AttributeRule Name="urn:mace:dir:attribute-def:eduPersonPrincipalName" Scoped="false" Header="REMOTE_USER" Alias="user">
                <!-- Basic rule to pass through any value. -->
         <AnySite>
             <!-- <Value Type="regexp">^[^@]+$</Value> -->
-           <Scope Accept="true">myvocs-box</Scope>
+           <!-- <Scope Accept="true">myvocs-box</Scope> -->
            <AnyValue/>
         </AnySite>
     </AttributeRule>

Save it to the file AAP.xml.patch and apply it with patch -p0 < AAP.xml.patch.

Ready for Testing

At this point you should be ready to go with your converted myVocs box. Restart the shibboleth services and the verify your operations: 

/etc/init.d/tomcat restart
/etc/init.d/shibboleth restart

There are two test URLs that will print the attributes visible to myVocs box and to the VO applications. The first URL shows the attributes provided to myvocs box by openidp.org (or any external idp) 

https://yourvocs-box/tools/secext

The second one shows the attributes available to the VO applications, ie. the ones that are part of your internal system environment. 

https://yourvocs-box/tools/secure

Since the default web front end to the myVocs box instance was disabled ealier (the dispatch.cgi) you won't see anything grand if you just point your browser at the box. You'll want to start you exploration (and VO definition and management) by going directly to the sympa interface: 

http://yourvocs-box/sympa

The first login becomes the default site owner and will be able to create VOs (lists) and otherwise manage the mailling list features of Sympa. Once a list is created you can connect to any of the three VO sample apps from the list's administration overview page.

Note for Updating System IdP Config

When you go to build your own system environment, you'll want to essentially build up a federation that defines the rules for apps being added to your system environment and the policies that govern attribute release. This involves defining your system's metadata and updating the identity providers configuration and (if you plan on using any apps on the local box) the service provider's configuration. Examples of these changes are beyond the scope of this document.