=== Integrating Blackboard Connect with Shibboleth for institutional authentication of users and SSO ===
University of Alaska Identity & Access Management November 2012
University of Alaska has implemented central authentication and "single sign-on" (SSO) using [[https://shibboleth.net/ https://iam.alaska.edu|Shibboleth]]. The following is a brief description of the steps taken by UA to have services from [[http://www.blackboard.com/Platforms/Connect/Products/Blackboard-Connect.aspx|Blackboard Connect]] rely on our central authentication to log in users. This description does not attempt to be a general guide to either Shibboleth or Blackboard Connect. It is focused merely on the specific steps to integrate vendor-hosted Blackboard Connect services with a working campus-based Shibboleth Identity Provider (IdP). ''These steps are a little different than a prototypical integration because''[[BR]]
 (1) Blackboard CONNECT entity id's depend on an X509 certificate the customer uploads to the hosted service, [[BR]]
 (2) Blackboard CONNECT does not as of this writing participate in the [[http://www.incommon.org|InCommon federation]], requiring manual addition of metadata and certificates, and most important [[BR]]
 (3) Blackboard CONNECT uses "unsolicited" or "IdP-initiated" SSO, which entails a work flow that differs from the norm.

Below are set-up details for these three steps.

=== Step 1:  Determine the entity id for BBC service(s) ===
The Blackboard Connect administrative interface provides a setting to configure the service for Single Sign-On (SSO). You will of course need to have been provided administrative-level access and credentials by Blackboard Connect. You will also need to upload your IdP certificate. You need to do this step first because later steps will need the custom entity id generated in this process.[[BR]]

1.1 Have a copy of your IdP certificate ready to upload[[BR]]

1.2 Login to the admin interface https://www.blackboardconnect.com/signin/default.aspx# with credentials provided by Blackboard Connect.

[[Image(https://iam.alaska.edu/shib/attachment/wiki/BBCShibIntegration/Bbimage1.png)]]

1.3 As documented in Connect SSO Implementation Manual, open the ADMIN tab, Choose "Settings" then "Single Sign On Configuration Setup"

[[Image(https://iam.alaska.edu/shib/attachment/wiki/BBCShibIntegration/Bbimage2.png)]]

to bring up the dialog to enable SSO and upload your certificate in this dialog:

[[Image(https://iam.alaska.edu/shib/attachment/wiki/BBCShibIntegration/Bbimage3.png)]]

1.4 Upload your IdP's X509 certificate using the controls in the web form. 

1.5 Determine the unique entity id ("url") for your SSO-enabled service(s).
[BBC will have to describe just how you find that url in the interface!]
The entity id for the staging (testing) service will have a format like:
https://ssostg.blackboardconnect.com/SAML/Connect/B46C75BF139144349190F775C38F05A9
The entity id for your production portal for end users will have a format like:
https://sso.blackboardconnect.com/SAML/Portal/E0D069C2563D4D63A14CBB95D6845C25
The entity id for your production instance of Connect (at UA we call this the "Sender Portal" available only to those who can trigger alerts) will have a format like https://sso.blackboardconnect.com/SAML/Connect/9F95200F70EB4E8F844320653CCD97A8

=== Step 2:  Configure your IdP for BBC service(s). ===
The Shibboleth IdP relies on several xml files for knowing whether and how to communicate with services to assert authentication and attributes for authenticated users. Metadata for service providers (SPs) in the !InCommon federation can be consumed automatically, but BBC services are not in !InCommon, so you must add metadata specifically for BBC. In addition, you will likely have to generate specific attributes for BBC (in attribute-resolver.xml) and set an appropriate release policy to send those attributes to BBC (in attribute-filter.xml).


(2.1) Add descriptors and certificates for BBC services into the metadata used by your IdP. Your IdP will be configured to consume metadata from one or more files. Add !EntityDescriptor elements - including the entityIDs from step 1 and a certificate for each of the BBC services to be integrated to one of these files (order in which !EntityDescriptors are listed or read is immaterial). As of this writing, the certificate itself is not actually used, so any certificate will do! Even though not actively used, a certificate must be present. The entityID must exactly match the entityID from step 1.[[BR]]

''example (fragment)'':
{{{
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
entityID="https://ssostg.blackboardconnect.com/SAML/Connect/
B46C75BF139144349190F775C38F05A9">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:
2.0:protocol">
    <md:KeyDescriptor>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>
MIIC3zCCAcegAwIBAgIJAJ21e7iR+TNiMA0GCSqGSIb3DQEBBQUAMBMxETAPBgNV
H9uAnnFzNljGLT/EFIy2zDT/lCYetRT5kEthGjc1j4/9XfB85o75isrYcDAMdxrz
...
POST"
Location="https://ssostg.blackboardconnect.com/SAML/Connect/
B46C75BF139144349190F775C38F05A9" index="1"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
}}}
(2.2) Add "profile" data for BBC service(s) into relying-party.xml configuration file. [[BR]]
''example fragment of relying-party.xml to support BBC services:
''
{{{
<!-- BlackBoard Connect Staging -->
    <RelyingParty id="https://ssostg.blackboardconnect.com/SAML/Connect/
B46C75BF139144349190F775C38F05A9"
          provider="urn:mace:incommon:alaska.edu"
          defaultAuthenticationMethod="urn:oasis:names:tc:SAML:
2.0:ac:classes:PasswordProtectedTransport"
          defaultSigningCredentialRef="IdPCredential">
  </ds:X509Certificate>
</ds:X509Data>
  </ds:KeyInfo>
</md:KeyDescriptor>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-
<ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
encryptAssertions="never" encryptNameIds="never" />
    </RelyingParty>
  <!-- BlackBoard Connect Sender Portal -->
    <RelyingParty id="https://sso.blackboardconnect.com/SAML/Connect/
6F0CEAB5A3704F84A767DFA3CC6CEBF7"
          provider="urn:mace:incommon:alaska.edu"
          defaultAuthenticationMethod="urn:oasis:names:tc:SAML:
2.0:ac:classes:PasswordProtectedTransport"
          defaultSigningCredentialRef="IdPCredential">
        <ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
encryptAssertions="never" encryptNameIds="never" />
    </RelyingParty>
  <!-- BlackBoard Connect Recipient Portal -->
    <RelyingParty id="https://sso.blackboardconnect.com/SAML/Portal/
7B9070E4D2DE4195A8B530EE72266AB0"
          provider="urn:mace:incommon:alaska.edu"
          defaultAuthenticationMethod="urn:oasis:names:tc:SAML:
2.0:ac:classes:PasswordProtectedTransport"
          defaultSigningCredentialRef="IdPCredential">
        <ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
encryptAssertions="never" encryptNameIds="never" />
}}}
(2.3) Define and encode attributes needed by BBC in attribute-resolver.xml configuration file. You will need to understand what attributes are required for your customized implementation of BBC service(s) and how to obtain that data from the data sources available to your IdP. Our implementation specified, for each user:
first name, last name, unique "!RefCode," and a logout URL. The example below assumes the name and unique identifier are available in an Active Directory and that the IdP and Active Directory have been configured to enable the IdP to retrieve that data from AD. The logout URL is the same for all users; it relies on a static data connector.
BBC required that these attributes be passed with particular attribute names in the SAML assertion (different from the names commonly used in our Directores), so this fragment also associates those specific attribute names.


''example fragments of attribute-resolver.xml to support BBC'':
{{{
<!-- RefCode is the Banner ID# released with attribute name required by Blackboard
Connect   -->
<!-- Sourced from UA Domain AD attribute uaIdentifier -->
     <resolver:AttributeDefinition id="ContactRefCode" xsi:type="Simple"
xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="uaIdentifier">
     <resolver:Dependency ref="uaADLDAP" />
     <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:
2.0:attribute:encoder" name="urn:mace:alaska.edu:attributes:ContactRefCode"
friendlyName="ContactRefCode"/>
     </resolver:AttributeDefinition>
<!-- DATA CONNECTOR STATIC LogoutURL for BBC -->
  <resolver:DataConnector id="staticValueAttributes" xsi:type="Static"
xmlns="urn:mace:shibboleth:2.0:resolver:dc">
        <Attribute id="LogoutURL">
           <Value>https://www.alaska.edu/uaalerts/</Value>
        </Attribute>
</resolver:DataConnector>
<!-- ATTRIBUTE DEF LogoutURL uses staticValueAttributes data connector -->
  <resolver:AttributeDefinition xsi:type="ad:Simple" id="LogoutURL">
       <resolver:Dependency ref="staticValueAttributes" />
       <resolver:AttributeEncoder xsi:type="enc:SAML2String"
xmlns="urn:mace:shibboleth:2.0:resolver:ad" name="https://iam.alaska.edu/trac/wiki/
IamUaArp" friendlyName="LogoutURL" />
   </resolver:AttributeDefinition>
<!-- BBC-named attributes: FirstName is givenName ; LastName is sn -->
     <resolver:AttributeDefinition id="FirstName" xsi:type="Simple"
xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="givenName">
     <resolver:Dependency ref="uaADLDAP" />
     <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:
2.0:attribute:encoder" name="urn:oid:2.5.4.42" friendlyName="FirstName"/>
     </resolver:AttributeDefinition>
     <resolver:AttributeDefinition id="LastName" xsi:type="Simple"
xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="sn">
     <resolver:Dependency ref="uaADLDAP" />
     <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:
2.0:attribute:encoder" name="urn:oid:2.5.4.4" friendlyName="LastName"/>
}}}

(2.4) Configure policies to release appropriate attributes to BBC service(s). Configure the specific named attributes are released to the entityIDs of BBC service(s) in the attribute-filter.xml configuration file.


''example attribute release policy for BBC'':
{{{
<AttributeFilterPolicy id="releaseToBBConnect">
<PolicyRequirementRule xsi:type="basic:OR">
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://
sso.blackboardconnect.com/SAML/Portal/E0D069C2563D4D63A14CBB95D6845C25" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://
sso.blackboardconnect.com/SAML/Connect/9F95200F70EB4E8F844320653CCD97A8" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://
ssostg.blackboardconnect.com/SAML/Connect/B46C75BF139144349190F775C38F05A9" />
</PolicyRequirementRule>
   <AttributeRule attributeID="FirstName">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="LastName">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="ContactRefCode">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="LogoutURL">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
</AttributeFilterPolicy>
}}}
=== Step 3:  Configure unsolicited SSO for BBC ===

BBC uses "unsolicited" or "IdP initiated" SSO. That means that, rather than the normal workflow of responding to a request from the SP that redirects the user's browser to the IdP for authentication and attributes, BBC requires us to send a SAML assertion with user authentication and required attributes without BBC having initiated that request. This is accomplished in the Shibboleth IdP by setting up a URL that invokes a profile (or "end point") specifically for unsolicited SSO ("idp/profile.SAML2/Unsolicited/SSO") and includes the (encoded) relying party entity id above. While it is possible to enter that link directly into a browser address bar, you will want to embed that long URL behind a button or text link on a web page you own. When the user clicks on the link, that initiates the request to your IdP to contact the BBC service. Additional information on
unsolicited SSO with Shib
boleth is at Shibboleth wiki IdPUnsolicitedSSO.


(3.1) Your IdP must be able to accept unsolicited requests to a specific end point at the IdP. If your IdP configuration files were installed from Shibboleth 2.3.0 or later, the profile should already be there, but it's worth checking the configuration files and adding the following if not already present:
The unsolicited or idp-initiated profile handler should be in handler.xml:
{{{
<ProfileHandler xsi:type="SAML2SSO"
    inboundBinding="urn:mace:shibboleth:2.0:profiles:AuthnRequest"
    outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign
                                urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
                                urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact">
  <RequestPath>/SAML2/Unsolicited/SSO</RequestPath>
</ProfileHandler>
}}}
Also needed is the message decoder in internal.xml:
{{{
<entry>
  <key>
    <value>urn:mace:shibboleth:2.0:profiles:AuthnRequest</value>
  </key>
  <bean id="shibboleth.UnsolicitedSSODecoder"
        class="edu.internet2.middleware.shibboleth.idp.profile.saml2.UnsolicitedSSODecoder">
    <constructor-arg ref="shibboleth.IdGenerator"/>
  </bean>
</entry>
}}}
(3.2) Determine the URL that triggers the IdP-initiated SSO session with BBC. Recall that we have to forge the request to the IdP rather than the SP re-directing the user's browser. That's done with a link to your IdP that references the Unsolicited SSO profile and includes the subsequent BBC entityID to which the user's browser will be re- directed upon successful authentication by the IdP. Of course you will substitute your own !IdPs location for idp.alaska.edu and the entityIDs for BBC from step 1 (suitably encoded as here).
''
examples of URLs for SSO to BBC using the entityIDs from step 1:''

Staging service:
{{{
https://idp.alaska.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=https%3A%2F%2F ssostg.blackboardconnect.com%2FSAML%2FConnect%2FB46C75BF139144349190F775C38F05A9
}}}
Recipient Portal:
{{{
https://idp.alaska.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=https%3A%2F%2F sso.blackboardconnect.com%2FSAML%2FPortal%2FE0D069C2563D4D63A14CBB95D6845C25
}}}
Sender Portal:
{{{
https://idp.alaska.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=https%3A%2F%2Fsso.blackboardconnect.com%2FSAML%2FConnect%2F9F95200F70EB4E8F844320653CCD97A8
}}}

(3.3) You can test the integration by directly pasting those URLs into a browser, but you will want to have users click on a link on a web site you manage. That's your last task - to set up a web page with a description of the service and a button or text link behind which is one of the URLs for unsolicited SSO to BBC from (3.2).