== [[https://iam.alaska.edu/|IAM]] / [[https://iam.alaska.edu/projects|Projects]] / [[https://iam.alaska.edu/shib|Shibboleth]] / [[ServiceCandidates|Service Integrations]] / Blackboard Transact ==

Blackboard Transact is to be used with eAccounts to support Tapingo - online meal order and payment.

Transact used for payment transactions with web clients; eAccounts (LDAP enabled, not Shibb) on mobile devices.

David !DeWolfe is primary technical contact with these vendors.

=== 2015.02 problem description ===
While we thought we had this integration working with the configuration notes below, as of 2015-02 the return query for attributes identifies the user with the scoped UA Username (UAUsername@alaska.edu) which the IdP cannot translate to a principal for which to return attributes. 

Note from David !DeWolfe:
{{{
You can log on to the eAccounts Management Portal at:

    https://mgmt-ualaska-sp.blackboard.com/mgmt/login.aspx

Your account name is "dabantz". Stop by and I'll reset your password for you. Once logged on you select:

    "Identity Service Query" under the "Identity Service Setup" heading on the top right of the page

then select:

    "Edit" next to "UA Shib"

then click on the "Test" button. After being taken to our login page and entering  your credentials you are supposed to end up back on the "Identity Service Detail" page where it should display your 30M# and email address. 
}}}

=== Nearly but not quite correct configuration notes! ===

Transact Service Provider (SP) is configured and tested through an administrative portal at Blackboard.  For the UA integration, David !DeWolfe used this console in consultation with Blackboard and IAM.  Transact integration was unique to UA IAM (as of 2014) in using TWO IdP profiles; it took several weeks of conversation to realize that the SP requests authentication  per usual, receives the SAML assertion from the IdP, BUT THEN ignores or discards the attributes and makes a SECOND call to the IdP using !AttributeQueryProfile to retrieve attributes.  The configuration below reflects this SP behavior.

1. Custom relying party for Transact in relying-party.xml in the relying parties section:

{{{
<!-- BlackBoard Transact does not support encryption; uses AttributeQuery 2014-10-23 -->
   <RelyingParty id="https://sp.transactsp.com/shibboleth-sp/mgmt-ualaska-sp.blackboard.com/mgmt"
       provider="urn:mace:incommon:alaska.edu"
       defaultSigningCredentialRef="IdPCredential"
       defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport">
       <ProfileConfiguration xsi:type="saml:SAML2SSOProfile" encryptAssertions="never" encryptNameIds="never" />
       <ProfileConfiguration xsi:type="saml:SAML2AttributeQueryProfile" encryptAssertions="never" encryptNameIds="never" />
   </RelyingParty>
}}}

2.  Blackboard metadata provider is also configured in relying-party.xml in the metadata provider section:

{{{
      <!-- other metadata from other providers goes here -->  

      <metadata:MetadataProvider id="TransactSP" xsi:type="metadata:FileBackedHTTPMetadataProvider" 
                        metadataURL="https://mgmt-ualaska-sp.blackboard.com/mgmt/rest/MetadataRequest"
                        backingFile="/opt/shibboleth-idp/metadata/TransactSP-metadata.xml" />
      </MetadataProvider>

}}}

3. Blackboard Transact relies on a NameID with particular format to identify the user (rather than ePPN or other usual attributes).  A previous integration (Okta) relied on a similar NameID, so we are re-using the NameID constructed for Okta in attribute-resolver.xml:


{{{
<!-- Okta and Bb Transact require something like ePPN in the SAML Subject -->
<resolver:AttributeDefinition
       id="oktanameid"
       xsi:type="Script"
       xmlns="urn:mace:shibboleth:2.0:resolver:ad"
       sourceAttributeID="UASystemID"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:resolver="urn:mace:shibboleth:2.0:resolver">
<!-- use UA Username = uasystemid iff it was retrieved from MyLDAP=EDIR; if no value, try using uaadsytemid from UA AD -->
       <resolver:Dependency ref="uasystemid" />
       <resolver:Dependency ref="uaadsystemid" />
       <resolver:AttributeEncoder
         xsi:type="SAML2StringNameID"
         xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
         nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" />
       <resolver:AttributeEncoder
         xsi:type="SAML2String"
         xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
         name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
         friendlyName="username" />
        <Script>
        <![CDATA[
        importPackage(Packages.edu.internet2.middleware.shibboleth.common.attribute.provider);
        importPackage(Packages.org.slf4j);

        logger = LoggerFactory.getLogger("edu.internet2.middleware.shibboleth.resolver.Script.scriptTest");
 logger.debug("Starting oktanameid Resolver Script:");

        if (null == oktanameid) {oktanameid = new BasicAttribute("oktanameid");}
        if (typeof uasystemid != "undefined" && uasystemid != null && uasystemid.getValues().size() != 0){
        oktausername = uasystemid.getValues().get(0);
        oktanameid.getValues().add(oktausername + "@alaska.edu");}
 else { if (typeof uaadsystemid != "undefined" && uaadsystemid != null && uaadsystemid.getValues().size() != 0){
        oktausername = uaadsystemid.getValues().get(0);
        oktanameid.getValues().add(oktausername + "@alaska.edu");}
      }
 logger.debug("adding scope to UA Username; result is oktanameid = " + oktanameid.getValues() );
        ]]>
        </Script>
    </resolver:AttributeDefinition>
}}}


4. Blackboard Transact processes attributes based on their !FriendlyNames rather than actual names, and also requires specific !FriendlyNames for the attributes consumed.  So these custom attributes are encoded in attribute-resolver.xml:

{{{
<!-- Bb Transact requires its own unique FriendlyNames so add definitions and encoders with those FriendlyNames -->

    <resolver:AttributeDefinition id="BbTemail" xmlns="urn:mace:shibboleth:2.0:resolver:ad" xsi:type="Simple" sourceAttributeID="onemail">
       <resolver:Dependency ref="onemail" />
       <resolver:AttributeEncoder xmlns="urn:mace:shibboleth:2.0:attribute:encoder" xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="BbSPEmailAddress" />
    </resolver:AttributeDefinition>

    <resolver:AttributeDefinition id="BbTFirstName" xmlns="urn:mace:shibboleth:2.0:resolver:ad" xsi:type="Simple" sourceAttributeID="FirstName" >
       <resolver:Dependency ref="FirstName" />
       <resolver:AttributeEncoder xmlns="urn:mace:shibboleth:2.0:attribute:encoder" xsi:type="SAML2String" name="urn:oid:2.5.4.42" friendlyName="BbSPFirstName" />
    </resolver:AttributeDefinition>

    <resolver:AttributeDefinition id="BbTLastName" xmlns="urn:mace:shibboleth:2.0:resolver:ad" xsi:type="Simple" sourceAttributeID="LastName">
       <resolver:Dependency ref="LastName" />
       <resolver:AttributeEncoder xmlns="urn:mace:shibboleth:2.0:attribute:encoder" xsi:type="SAML2String" name="urn:oid:2.5.4.4" friendlyName="BbSPLastName" />
    </resolver:AttributeDefinition>

    <resolver:AttributeDefinition id="BbTusername" xmlns="urn:mace:shibboleth:2.0:resolver:ad" xsi:type="Simple" sourceAttributeID="oktanameid">
       <resolver:Dependency ref="oktanameid" />
       <resolver:AttributeEncoder xmlns="urn:mace:shibboleth:2.0:attribute:encoder" xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" friendlyName="BbSPUserName" />
    </resolver:AttributeDefinition>

    <resolver:AttributeDefinition id="BbTbannerID" xmlns="urn:mace:shibboleth:2.0:resolver:ad" xsi:type="Simple" sourceAttributeID="uakPersonID">
       <resolver:Dependency ref="uakPersonID" />
       <resolver:AttributeEncoder xmlns="urn:mace:shibboleth:2.0:attribute:encoder" xsi:type="SAML2String" name="https://iam.alaska.edu/trac/wiki/IamUaArp#uakPersonID" friendlyName="BbSPCustomerNumber" />
    </resolver:AttributeDefinition>
}}}

5. Finally, to release these unique attributes to Bb Transact, the following policy was added to attribute-filter.xml:

{{{
<AttributeFilterPolicy id="releaseToTransact">
    <PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://sp.transactsp.com/shibboleth-sp/mgmt-ualaska-sp.blackboard.com/mgmt" />

    <AttributeRule attributeID="oktanameid">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>

    <AttributeRule attributeID="BbTLastName">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>

    <AttributeRule attributeID="BbTFirstName">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>

    <AttributeRule attributeID="BbTbannerID">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>

    <AttributeRule attributeID="BbTemail">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>

    <AttributeRule attributeID="BbTusername">
        <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>

</AttributeFilterPolicy>
}}}