== [[https://iam.alaska.edu/shib|Shibboleth]] / Shibboleth IdP Setup ==

=== IdP2Upgrade ===

[[https://wiki.shibboleth.net/confluence/display/SHIB2/IdP2Upgrade|Shibb documentation wiki, Added by lajoie@idp.protectnetwork.org, last edited by Sara Hopkins on Oct 03, 2012]]
=== Upgrading from Shibboleth IdP 2.x ===

These instructions are for upgrading a currently operational version 2.x Shibboleth IdP. 

1. Stop the IdP (by stopping the Tomcat servlet container); stop Apache httpd too.
2. Make a back-up copy of /opt/shibboleth-idp/conf directory (recent versions of the IdP installer should not overwrite config unless you answer "yes" in point 7 below).
3. Download the .zip archive of the most recent Shibboleth IdP 2.x and unzip the archive. Do not use the .msi installer for upgrading an existing IdP 2.x installation.
4. Create a source directory specifically for storing the IdP unzipped archives. This makes it easier to manage any additional libraries or branding.  Record the directory path here:_____________________________
5. Copy additional libraries (e.g. JDBC drivers or plugins and/or filters, like uApprove) into the lib/ directory (i.e. lib/ inside the source directory where you unzipped the archive; not $IDP_HOME/lib/, which is inside the deployment directory).
6. Reapply any branding: ie. copy the previously customised login.jsp etc. pages into the /src/main/webapp subdirectory of the unzipped archive.
7. Run the install script from the command line in the top-level directory of the unzipped archive (install.sh on Unix machines, install.bat on Windows).
 * Provide the location of your $IDP_HOME directory: /opt/shiobboleth-idp
 * Answer "no" when the installer asks if you wish to overwrite your configuration files.
8. If the config files have been overwritten (eg. due to human error) copy the files from the back-up back into /opt/shibboleth-idp/conf directory.
9. Start the IdP (or the servlet container), and start Apache httpd too, if you're using it.


=== UA localization ===

==== Local !DataConnectors ====
UA IdP is configured to use both the DSEE enterprise LDAP directory ("EDIR") and UA Domain AD for attribute resolution.  

The edir LDAP directories are behind a hardware equalizer, providing redundancy; the cluster is addressed by:
{{{
<resolver:DataConnector id="myLDAP" xsi:type="LDAPDirectory" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
        ldapURL="ldaps://edir.alaska.edu:636" baseDN="ou=people,dc=alaska,dc=edu" 
        principal="uid=shibboleth03,ou=resource,dc=alaska,dc=edu"
        principalCredential="•••••••••">
        <FilterTemplate>
            <![CDATA[
                (|(uid=$requestContext.principalName)(uasystemid=$requestContext.principalName)(bannerid=$requestContext.principalName))
            ]]>
        </FilterTemplate>
</resolver:DataConnector>

}}}
The !FilterTemplate supports user login with their UA Username (in uasystemid) or their ID # (in bannerid) or their edir UID.

The UA Domain AD as of 2013-04 is defined as a single node connection:
{{{
<resolver:DataConnector id="uaADLDAP" xsi:type="LDAPDirectory" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
        ldapURL="ldaps://fbk-adua02.ua.ad.alaska.edu:3269" baseDN="ou=useraccounts,dc=ua,dc=ad,dc=alaska,dc=edu"  
        principal="cn=uashib,ou=uaf_service,ou=uaf,dc=ua,dc=ad,dc=alaska,dc=edu" principalCredential="•••••••••">
        <FilterTemplate>
            <![CDATA[
                (|(sAMAccountName=$requestContext.principalName)(uaIdentifier=$requestContext.principalName))
            ]]>
        </FilterTemplate>
</resolver:DataConnector>
}}}
The !FilterTemplate supports user login with their UA Username (in sAMAcountName) or their UA ID# (in uaidentifier).

In the future, a subset of the UA AD servers might be put into a equalizer cluster, providing redundancy similar to edir.
As a fall-back, this !DataConnector might be configured with failover (see below).
==== Customize login.jsp ====
2012: IdP distribution is at howkan:/home/sxjpm/Shib/shibboleth-identityprovider-2.3.0/src...

The java login page for branding & customization is in that src directory at .../main/webapp/login.jsp

production !IdPs (heald, hanin) do not have 2.3.0 src...
==== Import private CAs as needed ====
As of 2013-04-01 UA AD is using certificates signed by a local private CA.  Unless that CA's certificate is imported, the IdP will fail to establish connection to the AD server, potentially causing authN failure, but certainly causing a failure in attribute resolution.

Import the CA certificate, per https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAuthUserPass with the following command that MUST be run by root (to write the cacerts file):
{{{

keytool -import -trustcacerts -alias "sensible-name-for-ca"
        -file directory.crt -keystore $JAVA_HOME/lib/security/cacerts
}}}

==== !DataConnector Failover ====
If the data connector encounters an error when trying to retrieve attribute information from the database, one or more failover data connectors can be defined. These connectors are only invoked if this data connector fails (not if simply finds no results) and they are invoked in the order they are listed until one succeeds.

N.B.: if the !DataConnector as a whole fails, UA experience has been that the attribute resolution process aborts and the SAML assertion has no attributes.  A possible more robust solution is to define a failover "static data connector" that will return no attributes or static-value attributes, but not abort the attribute resolver.

Failover connectors are defined by the <resolver:FailoverDataConnector> element with a ref attribute whose value is the unique ID of the data connector to use in the event that this one fails.

Basic Relational Database Data Connector Definition with Dependencies
{{{
<resolver:DataConnector xsi:type="dc:RelationalDatabase" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
                                          id="UNIQUE_ID">
 ...
     <resolver:FailoverDataConnector ref="FailoverStaticConnector" />
 ...
 
</resolver:DataConnector>
}}}
Basic Format of Static Data Connector
{{{
<resolver:DataConnector id="FailoverStaticConnector" xsi:type="Static" xmlns="urn:mace:shibboleth:2.0:resolver:dc">
     <Attribute id="uausername">
          <Value>nobody</Value>
     </Attribute>
     <Attribute id="eduPersonAffiliation">
          <Value>affiliate</Value>
          <Value>member</Value>
     </Attribute>
</resolver:DataConnector>
}}}
=== IdP Install (not upgrade) Recipe ===

See https://iam.alaska.edu/trac/raw-attachment/wiki/WikiStart/idpinstall.pdf