This topic focuses on configuring the Shibboleth environment specifically to enable JIT provisioning on your instance of Blackboard Learn. This form of authentication is part of Blackboard's membership in the Internet2 NET+ community, which focuses on extending the academic research and education community's networking and collaborative benefits to cloud-based technologies. The Internet2 community uses InCommon as its authentication network. Institutions who belong to the community are able to use single sign-on between their systems.

You may have already setup Shibboleth after installing Blackboard Learn. To learn more, see additional documentation on installing and using Shibboleth:

In order to fully implement JIT provisioning, you will need to modify Shibboleth server architecture and add an additional Apache server.

Before you begin

These beginning steps are important.

  1. Redirect firewall requests to port 8443/https.
  2. In /usr/local/blackboard/config/bb-config, change Blackboard Learn's https port to 8444.

Install the Apache Server

  1. In the command line, install Apache using the command yum install httpd-2.2.15-45.el6.centos
  2. Install mod_ssl and openssl using the commands yum install mod_ssl and yum install openssl
  3. Create a folder to store SSL-related files. In the command line, enter:
    mkdir $APACHE_HOME/ssl
    cd $APACHE_HOME/ssl
  4. Generate a private key using the command ssh-keygen -f server.key
  5. Generate request csr using the command openssl req -new -key server.key -out request.csr
  6. Generate the SSL certificate using the command openssl x509 -req -days 365 -in request.csr -signkey server.key -out server.crt
  7. Specify the certificate's path.

Notes

  • Apache will be installed to /etc/httpd
  • There will be a file named ssl.conf in $APACHE_HOME/conf.d/ after you install openssl & mod_ssl
  • Use the command apachectl start|stop|restart to manage Apache service.

You should restart Apache's service after you change any of its configuration files.

Configure Apache and OpenSSL

  1. Open Apache's SSL configuration file, titled $APACHE_HOME/conf.d/ssl.conf
  2. Locate the Certificate section, and make the following changes to SSLCertificateFile and SSLCertificateKeyFile:

    # Server Certificate:
    # Point SSLCertificateFile at a PEM encoded certificate. If
    # the certificate is encrypted, then you will be prompted for a
    # pass phrase. Note that a kill -HUP will prompt again. A new
    # certificate can be generated using the genkey(1) command.
    SSLCertificateFile /etc/httpd/ssl/server.crt

    # Server Private Key:
    # If the key is not combined with the certificate, use this
    # directive to point at the key file. Keep in mind that if
    # you've both a RSA and a DSA private key you can configure
    # both in parallel (to also allow the use of DSA ciphers, etc.)
    SSLCertificateKeyFile /etc/httpd/ssl/server.key

  3. Locate the VirtualHost section and make the following changes to <VirtualHost> and ServerName. To make the section appear as follows, you may need to add some lines:

    #If use https protocol
    Listen 8443
    <VirtualHost *:8443>
    ProxyRequests Off
    # General setup for the virtual host, inherited from global configuration
    #DocumentRoot "/var/www/html"
    ServerName saml_lnx.pd.local
    # SSL Engine Switch:
    # Enable/Disable SSL for this virtual host.
    SSLEngine on
    SSLProxyEngine on
    ProxyPass / https://saml_lnx.pd.local:8444/
    ProxyPassReverse / https://saml_lnx.pd.local:8444/

  4. Start Apache with the commands

    apachectl configtest
    apachectl start

Install Shibboleth

  1. Add shibboleth.repo to yum's repository. 
  2. In your terminal window, install Shibboleth using the yum install shibboleth command.
  3. After you've set up the Shibboleth server, install the IdP.

Configure Shibboleth

  1. Modify the contents of the Apache/Shibboleth configuration file, titled $APACHE_HOME/conf.d/shib.conf

    Add:

    TraceEnable off
    ProxyPass /Shibboleth.sso !
    ProxyPass /Shibboleth-sp !
    # If use http protocol
    ProxyPass / http://saml_lnx.pd.local:8080/

    Edit AuthType:

    <Location /Shibboleth.sso>
    AuthType None
    Require all granted
    </Location>

    Add:

    <Location /webapps/bb-auth-provider-shibboleth-BBLEARN/execute/shibbolethLogin>
    AuthType shibboleth
            ShibUseHeaders On
            ShibRequestSetting requireSession 1
            require valid-user
            RewriteEngine On
            RewriteCond %{LA-U:REMOTE_USER} (.*)
            RewriteRule . - [E=RU:%1]
            RequestHeader set remote-user "%{RU}e" env=RU
            RequestHeader set Shib-Spoof-Check "1afb3c2a-4060-445f-831c-d4aaea782a1e"
    </Location>

  2. To integrate Shibboleth with the Identity Provider (IdP), edit contents of the Shibboleth configuration file, $SHIBBOLETH_HOME/shibboleth2.xml as follows:

    Add the following, and edit spoofKey to match Shib-Spoof-Check:

    You can find the Shib-Spoof-Check value in Blackboard Learn. Navigate to System Admin > Authentication > Shibboleth Setting.

    <InProcess spoofKey="1afb3c2a-4060-445f-831c-d4aaea782a1e" />

    Edit as follows:

    <ApplicationDefaults entityID="https://saml_lnx.pd.local/shibboleth" REMOTE_USER="eppn">

    In the following code, replace "https://idpdomain/shibboleth" with the identity provider's entityID:

    <SSO entityID="https://idpdomain/shibboleth">SAML2 SAML1</SSO>

    In the following code, replace "https://idpdomain/metadata.xml" with the identity provider's metadata URI:

    <MetadataProvider type="XML" uri="https://idpdomain/metadata.xml" reloadInterval="180000"/>

  3. Add the following code to attribute-map.xml file:

    <Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
    </Attribute>

    <Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" id="affiliation">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
    </Attribute>

    <Attribute name="urn:mace:dir:attribute-def:eduPersonAffiliation" id="eduPersonAffiliation">
    <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="eduPersonAffiliation">
    <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>

    <Attribute name="urn:mace:dir:attribute-def:eduPersonEntitlement" id="entitlement"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="entitlement"/>
    <Attribute name="urn:mace:dir:attribute-def:mobile" id="mobile"/>
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.41" id="mobile"/>
    <Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
    <Attribute name="urn:oid:2.5.4.4" id="sn"/>
    <Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
    <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
    <Attribute name="urn:oid:2.5.4.12" id="title"/>
    <Attribute name="urn:mace:dir:attribute-def:title" id="title"/>
    <Attribute name="urn:oid:2.5.4.9" id="street"/>
    <Attribute name="urn:mace:dir:attribute-def:street" id="street"/>
    <Attribute name="urn:oid:2.5.4.17" id="postalCode"/>
    <Attribute name="urn:mace:dir:attribute-def:postalCode" id="postalCode"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.6.1.2" id="eduCourseMember"/>

  4. Start Shibboleth
    /sbin/service shibd start

Notes

  • Shibboleth will be installed to /etc/shibboleth
  • Use command /sbin/service shibd start|stop|restart to manage Shibboleth service.

You should restart Shibboleth's service after you change any of its configuration files.

  • There will be a file named shib.conf in $APACHE_HOME/conf.d/ after you complete installation of Shibboleth.
  • Shibboleth's log folder is /var/log/shibboleth

You can find the Shib-Spoof-Check value in Blackboard Learn. Navigate to System Admin > Authentication > Shibboleth Setting.

Attribute Mapping

To ensure accounts are created or updated with the appropriate roles and privileges, map attributes as desired in attribute-map.xml. Shibboleth loads these attributes from HTTP Header, the default setting.

Example XML

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
        <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
        <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
    </Attribute>
    <Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" id="affiliation">
        <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
        <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:mace:dir:attribute-def:eduPersonAffiliation" id="eduPersonAffiliation">
        <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="eduPersonAffiliation">
        <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:mace:dir:attribute-def:eduPersonEntitlement" id="entitlement"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="entitlement"/>
    <Attribute name="urn:mace:dir:attribute-def:mobile" id="mobile"/>
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.41" id="mobile"/>

The system creates accounts using the eduPersonPrincipalName (ePPN) or ePTID SAML attributes. When a user logs in to a new system, they are prompted to choose from a list of trusted identity providers, who hosts their external account. The identity provider communicates the ePPN to Blackboard Learn. If the ePPN does not already exist in your institution's Blackboard Learn, the system creates an entry and thereby creates a user account.

The system enrolls a student in a course through a SAML attribute release.

Users enroll themselves in an open course using a URL parameter.

Map user roles

Use the eduPersonAffiliation attribute in SAML to map a user's existing role to the role you would like them to have in Blackboard Learn. The default mappings are as follows:

SAML Role Blackboard Learn User Role
Student Student
Staff Staff
Faculty Faculty
  Guest
  Observer

You can find additional information about eduPerson Object Class Specification on the Internet2 website.

Map course roles

Use the eduCourseMember attribute in SAML to map a user's existing course role (instructor, student, etc.) to the role you would like them to have in courses in Blackboard Learn. The default mappings are as follows:

eduCourseMember Role Blackboard Learn Course Role
Learner Student
Instructor Instructor
ContentDeveloper Course Builder
Member Student
Manager Student
Administrator Student
TeachingAssistant Teaching Assistant
Mentor Instructor