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.
Add authentication adapter
AliasThis 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.
EnabledThis toggle determines whether the adapter is available for use.
Debug EnabledThis toggle determines whether debug statements are written to the logs for troubleshooting purposes.
TypeMAC
Restricted UsersEnter a comma-separated list of usernames that cannot use this adapter.
ParametersThis 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.
        AuthThe parameter that contains the MAC authentication signature. Recommended value: auth
        TimestampThe parameter which contains the timestamp. Recommended value: timestamp
        User IDThe 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 Learn). Recommended value: userId
        Course IDThe parameter that contains the course ID. This can be the Learn 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
        ForwardThe parameter that contains the URL to forward within Learn. This may or may not contain the Learn host name. Recommended value: forward
Timestamp DeltaThe 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 ParamsAny 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, you cannot see the value that is saved but you may change it.

Disable Nonce TrackingSelect this toggle for troubleshooting purposes so you can re-use authentication requests. For security purposes, we recommend you keep this toggle deselected to keep nonce tracking enabled.

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