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 an MD5 MAC, which the UAS service can validate.

Configure the UAS Settings

1. Navigate to the UAS Settings screen.
2. Select Add Authentication Adapter.

3. 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;
}