Skip to main content

Add an Incoming MAC Adapter

MAC (message authentication code) is a method that is used to determine the integrity of an SSO request. You must develop the logic on your source system to generate a MAC, which the UAS service can validate.

Configure the UAS Settings

From the UAS Settings screen, select Add Authentication Adapter. Fill out the fields as follows:

Field

Description

Alias

This is a unique name for the adapter and is used in URLs. The alias will be stored as all lowercase letters and should not contain any special URL characters.

Enabled

This toggle determines whether the adapter is available for use.

Auth Type

MAC

Use Outbound Adapter

Select the authentication adapter which will be used for outbound authentication to the external service. If you do not select one, the default outbound adapter will be used.

Debug Enabled

This toggle determines whether debug statements are written to the logs for troubleshooting purposes.

Restricted Users

Enter a comma-separated list of usernames that cannot use this adapter.

Algorithm

  • MD5: Select to use the legacy MD5 algorithm

  • SHA256: Select to use the more secure SHA-256 algorithm

Parameters

This is the mapping between your parameter names and the standard values. For example, the query string you provide has a parameter value named "time" and this should map to the expected "Timestamp" value.

Auth

The parameter that contains the MAC authentication signature. Recommended value: auth

Timestamp GMT

The parameter which contains the timestamp. Recommended value: timestamp

User ID

The parameter that contains the User ID (the user's username or batch_uid/external ID; this is dependent on how you configure the SAML authentication provider in Blackboard). Recommended value: userId

Course ID

The parameter that contains the course ID. This can be the Blackboard internal course identifier (_9999_1 format) or the batch_uid/external ID. The system will treat anything that looks like an internal course identifier as such and anything else as an external ID. Recommended value: courseId

Forward

The parameter that contains the URL to forward within Learn. This may or may not contain the Blackboard host name. Recommended value: forward

Timestamp Delta

The allowable difference (in milliseconds) between the timestamps from when the request was generated and when it was received by the Authentication Adapter service. Recommended value: 10,000 - 60,000

MAC Params

Any additional parameters listed here will be included in the MAC calculation (User ID and Timestamp are always included).

Secret

The shared key that will be used to calculate the MAC.

  • The secret cannot exceed 255 characters.

  • The secret cannot contain tabs, control characters, or end-of-line characters.

  • Shared secrets are case-sensitive.

  • We recommend you change your shared secret at regular intervals.

  • Make your shared secrets difficult to guess by making them long and including a combination of numbers and upper- and lower-case characters.

On remote systems, place the shared secret in secure directories.

Once saved, the value will be masked and you cannot access it but you may change it.

Error Page Help Text

Input the text that will appear on the error page displayed when there is a problem with authentication or provisioning.

Disable Nonce Tracking

Turn on this toggle for troubleshooting purposes so you can re-use authentication requests. For security reasons, we recommend you keep this toggle turned off so that nonce tracking is enabled.

Enable User Provisioning

Turn on this toggle to allow users to be automatically created from information provided in the MAC request.

Enable Enrollment Provisioning

Turn on this toggle to allow enrollments to be automatically created if the enrollment does not exist and a courseID is provided.

Allow Enrollment Availability to be Changed

Turn on this toggle to allow the system to enable enrollments that already exist and are disabled.

Select Save to save your configuration.

The URL for the configured adapter is https://{region}.extensions.blackboard.com/api/v2/authadapters/sites/{siteId}/auth/{alias}.

Generating MACs on the Trusted System

To properly authenticate users, the trusted system must be able to generate a valid MAC (message authentication code) to send with the SSO request. This MAC is used to determine the integrity of an SSO request. To generate a secure MAC:

  1. Sort the parameters (Timestamp, User Id, any additional parameters defined in Request Parameters used for MAC setting) alphabetically by parameter name.

  2. Concatenate the parameter values by the sorted parameter names into a single string.

  3. Append the Shared Secret to the string obtained from Step 2.

  4. Encrypt the string into a 16-byte string using the MD5 algorithm.

  5. Convert the 16-byte string into a 32-byte alphanumeric (hexadecimal) string to make it URL-friendly.

Example

This example uses default values for request parameter strings and a Shared Secret value of "blackboard," and "courseId" is also defined as an additional parameter in Request Parameters used for Mac.

  1. Sorted parameters (parameter values in parentheses): courseId (TC-101), timestamp (1268769454017), userId (test01)

  2. Parameter values concatenated: TC-1011268769454017test01

  3. Shared secret appended: TC-1011268769454017test01blackboard

  4. Encrypted string: ŒIV¨Báƒež©dxºvqâ

  5. Converted string: 8c4956a842e183659ea96478ba7671e2

Mac Script Examples

Java Example

Secure Algorithm:

    /**
     * Calculates a secure MAC (message authentication code) from an array of strings and shared secret.
     * @param values – Parameters must first be sorted alphabetically by parameter name, then the                values of these sorted parameters passed to calculateSecureMac
     * @param secret - the shared secret
     * @return The calculated MAC
     */

    private String calculateSecureMAC (final String[]
      values, final String secret) throws
      NoSuchAlgorithmException
    {

      // concatenate param values
      final int size = values.length;
      String paramString = "";
      for(int i=0; i<size; i++)
      {

        paramString += values[i];
      }

      // get md5 hash from ascii value and secret
      final MessageDigest md = MessageDigest.getInstance("MD5");
      final byte[] hashBytes = md.digest((paramString + secret).getBytes());
      md.reset();

      // convert to hex
      String mac = "";
      String hexByte;
      for (int k=0; k<hashBytes.length; k++)
      {

        hexByte = Integer.toHexString(hashBytes[k] < 0 ? hashBytes[k] + 256 : hashBytes[k]);
        mac += (hexByte.length()==1) ? "0" + hexByte : hexByte;
      }

      return mac;
    }

PHP Example

Secure Algorithm:

/* Calculates a MAC (message authentication code) from an array of strings and a secret.
   Sort request parameters alphabetically by parameter name first, then pass values of sorted
   parameters and shared secret to calculateSecureMac */

function calculateSecureMac($params, $secret)
{

  // concatenate param values
  $data = implode('', $params);

  // get md5 of concatenated param values and secret
  $mac = md5($data . $secret);
  return $mac;
}

Perl Example

Secure Algorithm:

use Digest::MD5;

# Calculates a MAC (message authentication code) from an array of strings and a secret. Sort request      parameters alphabetically by parameter name first, then pass values of sorted parameters and shared      secret to calculateSecureMac

sub calculateSecureMac

{
  my @args = @_;
  $secret = pop(@args);

  # concatenate param values
  $data = join("", @args);

  # get md5 of concatenated param values and secret
  $ctx = Digest::MD5->new;
  $ctx->add($data . $secret);
  $mac = $ctx->hexdigest;
  return $mac;
}