URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/reconfigure-idp.html
Author: Lukas Haemmerle - SWITCH
$Date: 2008/03/06 15:25:03 $
$Revision: 1.16 $ 

Reconfigure Shibboleth IdP 1.3 for AAI Test Federation

Table of Contents

Introduction

This guide describes how to configure your Identity Provider for the AAI Test Federation.

Note: For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the Deployment section of the SWITCHaai website (http://www.switch.ch/aai/).

Overview

The installation and configuration guides found in the technical information section were written specifically for the SWITCHaai Federation. However, if you want to do some tests or development work using Shibboleth, we strongly recommend to carry out these tests or development works in the AAI Test Federation, which mainly exists for this purpose. While SWITCHaai shouldn't contain any test users whatsoever, the AAI Test Federation is much less restrictive concerning this and other issues.

The example values used in this guide are:

www.example.ch

The DNS name of the Home Organization (Identity Provider) server, for real installations instead of "www", names like "aai-logon", "aai" or something similar are used. In the Tomcat connector configuration, the matching IP address is IP_ADDRESS_1.

aai-aa.example.ch

The DNS name of the server where the Home Organization's Attribute Authority is running. It is usually the same server as the one above, but the different name is needed for a Tomcat-only installation and also when using Apache 2 as a frontend for Tomcat. In the Tomcat connector configuration, the matching IP address is IP_ADDRESS_2.

Prerequisites

As indicated in the title, this guide assumes that you already configured your Identity Provider as described in the technical information section. It is assumed that the installation for the SWITCHaai Federation works, but chances are small that the IdP worked without testing. However, this is not much of a problem because the debugging procedure is the same in AAI Test as in SWITCHaai.

X.509 Server Certificates

Basically, you can use the same certificates in the AAI Test Federation as in the SWITCHaai Federation plus some additional ones. In the AAI Test Federation one for example also can use a certificate signed by the AAI Test CA, which is used for test purposes.
Read the AAI Test CA page on how to get a certificate signed by this CA.

Trust the AAI Test CA Root certificate

Depending on the installation you have, you will have to add the "AAI Test CA" certificate to a different place:

1. If you are running an IdP on Tomcat with Apache/mod_jk, add the certificate to Apache's ca-bundle configured with the SSLCACertificateFile directive. Then, go on with the instructions in the next section (Shibboleth IdP Configuration).
2. For an IdP on Tomcat only, the "AAI Test CA" certificate has to be added to a java truststore, which is described in the following subsection.

Add AAI Test CA to truststore

In addition to the CAs that are used in the SWITCHaai Federation you have to add the AAI Test CA Root certificate to the trust store as well.

$ keytool -import -trustcacerts -alias aaitest \
  -file aaitestca.PEM.crt -keystore truststore.jks

Omitting the -keystore option adds the CA certificates to Java's default certificate store (/opt/java/jre/lib/security/cacerts).

Shibboleth IdP 1.3 Configuration

Change all the red lines to the given values in the Shibboleth configuration file /etc/shibboleth/idp.xml. The blue lines show values that are specific for your Identity Provider or that are somehow specific for SWITCHaai.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- Shibboleth Identity Provider configuration 
     idp.xml TEMPLATE for the SWITCHaai federation
     see SWITCHaai installation guide -->

<IdPConfig 
  xmlns="urn:mace:shibboleth:idp:config:1.0" 
  xmlns:cred="urn:mace:shibboleth:credentials:1.0" 
  xmlns:name="urn:mace:shibboleth:namemapper:1.0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="urn:mace:shibboleth:idp:config:1.0 ../schemas/shibboleth-idpconfig-1.0.xsd" 
  AAUrl="https://aai-aa.example.ch/shibboleth-idp/AA" 
  resolverConfig="file:///etc/shibboleth/resolver.xml"
  defaultRelyingParty="urn:mace:switch.ch:aaitest" 
  providerId="urn:mace:switch.ch:aaitest:example.ch">


  <!-- This section contains configuration options that apply only to a site or group of sites
    This would normally be adjusted when a new federation or bilateral trust relationship is established -->
  <RelyingParty name="urn:mace:switch.ch:aaitest" signingCredential="switchaai_cred"> 
    <!-- (signingCredential) must correspond to a <Credential/> element below -->
    <NameID nameMapping="shm"/>
    <!-- (nameMapping) must correspond to a <NameMapping/> element below -->
  </RelyingParty>
  
  <!-- Configuration for the attribute release policy engine
    For most configurations this won't need adjustment -->
  <ReleasePolicyEngine>
    <ArpRepository implementation="edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository">
      <Path>file:///etc/shibboleth/arps</Path>
    </ArpRepository>
  </ReleasePolicyEngine>

  
  <!-- Logging Configuration
    The defaults work fine in this section, but it is sometimes helpful to use "DEBUG" as the level for 
    the <ErrorLog/> when trying to diagnose problems -->
  <Logging>
    <ErrorLog level="WARN" location="file:///var/log/shibboleth/shib-error.log" />
    <TransactionLog level="INFO" location="file:///var/log/shibboleth/shib-access.log" />
  </Logging>
  <!-- Uncomment the configuration section below and comment out the one above if you would 
     like to manually configure log4j -->
  <!--
  <Logging>
    <Log4JConfig location="file:///tmp/log4j.properties" />
  </Logging> 
  -->


  <!-- This configuration section determines how Shibboleth maps between SAML Subjects and local principals.
    The default mapping uses shibboleth handles, but other formats can be added.
    The mappings listed here are only active when they are referenced within a <RelyingParty/> element above -->
  <NameMapping 
    xmlns="urn:mace:shibboleth:namemapper:1.0" 
    id="shm" 
    format="urn:mace:shibboleth:1.0:nameIdentifier" 
    type="SharedMemoryShibHandle" 
    handleTTL="28800"/>


  <!-- Determines how SAML artifacts are stored and retrieved
    The (sourceLocation) attribute must be specified when using type 2 artifacts -->
  <ArtifactMapper implementation="edu.internet2.middleware.shibboleth.artifact.provider.MemoryArtifactMapper" />


  <!-- This configuration section determines the keys/certs to be used when signing SAML assertions -->
  <!-- The credentials listed here are used when referenced within <RelyingParty/> elements above -->
  <Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
    <FileResolver Id="switchaai_cred">
      <Key>
        <Path>file:///etc/shibboleth/www.example.ch.key</Path>
      </Key>
      <Certificate>
        <Path>file:///etc/shibboleth/www.example.ch.crt</Path>
      </Certificate>
    </FileResolver>

  <!-- this block may be used instead of the FileResolver - the IdP will then use the same keystore as Tomcat -->
  <!-- 
  <KeyStoreResolver Id="switchaai_cred" storeType="JKS">
      <Path>file:///etc/tomcat/www.example.ch.jks</Path>
      <KeyAlias>www.example.ch</KeyAlias>
      <CertAlias>www.example.ch</CertAlias>
      <StorePassword>STOREPASS</StorePassword>
      <KeyPassword>STOREPASS</KeyPassword>
    </KeyStoreResolver>
  -->

  </Credentials>


  <!-- Protocol handlers specify what type of requests the IdP can respond to.  The default set listed here should work 
    for most configurations.  Modifications to this section may require modifications to the deployment descriptor -->
  <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.ShibbolethV1SSOHandler">
    <Location>.+/shibboleth-idp/SSO</Location>
  </ProtocolHandler>
  <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_AttributeQueryHandler">
    <Location>.+/shibboleth-idp/AA</Location>
  </ProtocolHandler>
  <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_1ArtifactQueryHandler">
    <Location>.+/shibboleth-idp/Artifact</Location>
  </ProtocolHandler>
  <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.Shibboleth_StatusHandler">
    <!-- regex works when using default protocol ports -->
    <Location>https://[^:/]+(:443)?/shibboleth-idp/Status</Location>
  </ProtocolHandler>


  <!-- This section configures the loading of SAML2 metadata, which contains information about system entities and 
    how to authenticate them.  The metadatatool utility can be used to keep federation metadata files in synch.
    Metadata can also be placed directly within this these elements. -->
  <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
                uri="file:///etc/shibboleth/metadata.aaitest.xml"/>

</IdPConfig>

Metadata

The metadata for the Shibboleth SP and IdP both contain information about all the Resources and Home Organizations available in a federation. For the AAI Test Federation, the metadata.aaitest.xml file (for Shibboleth 1.3 SP and IdP) has to be updated on a regular basis. See http://www.switch.ch/aai/metadata/ for the latest version of the AAI Test metadata.

AAI Resource Registry

You are now ready to register your Identity Provider in the AAI Resource Registry. Doing this will allow you to download up-to data metadata and the customized ARP file for your IdP.

The AAI Resource Registry collects information about Resources (Service Providers) and Home Organizations (Identity Providers) which participate in the SWITCHaai and the AAI Test federations.

Links

SWITCH AAI project website

http://www.switch.ch/aai/

SWITCH AAI Resource Registry

https://aai-rr.switch.ch

--
$Id: reconfigure-idp.html,v 1.16 2008/03/06 15:25:03 haemmer Exp $