uConnect API

Documentation

Basics

To connect to the API you need a PUBLIC KEY and a PRIVATE KEY. Please contact the uConnect Team to obtain a keypair.

The API uses basic authorization. Your PUBLIC KEY is the username and you must contruct a request signature for the password. The API also expects you to pass a header value X-UTIMESTAMP with every request.

Signature

Your request signature is composed of three parts:

These three parts are then combined ("GET:1567859520:YOUR_PUBLIC_KEY") and hashed with your PRIVATE KEY. Your application's private key should never be exposed to the public and should be regenerated if you believe it has been compromised.

FAQ

  • Test - https://ws.uinform-test.ucdavis.edu/
  • Production - https://ws.uinform.ucdavis.edu/
NOTE: Your API keys for the test environment will NOT work in production.

ALSO NOTE: The API will only be served via HTTPS and will not respond/redirect from HTTP. This is per design and by Microsoft's direction - MSDN - Enforce HTTPS in ASP.NET Core

Please contact Matt Wilson @mwilson on IET Slack or @Matt Wilson on the UCD Slack.

No. However, I've included some basic code samples to get you started.

Since the API is new, nobody has asked ANY questions yet, let alone frequently asked them.

Api connection examples

C#


    var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
    var encoding = new System.Text.ASCIIEncoding();
    byte[] keyByte = encoding.GetBytes(YOUR_PRIVATE_KEY);
    byte[] messageBytes = encoding.GetBytes($"GET:{timestamp}:{YOUR_PUBLIC_KEY}");
    using var hmacsha1 = new HMACSHA1(keyByte);
    byte[] hashmessage = hmacsha1.ComputeHash(messageBytes);
    var signature = Convert.ToBase64String(hashmessage);
    var authBytes = System.Text.Encoding.UTF8.GetBytes($"{YOUR_PUBLIC_KEY}:{signature}");
    var auth = Convert.ToBase64String(authBytes);
    var person = "https://api-url.com"
        .AppendPathSegments("adusers", "upn", "upn@domain.edu")
        .WithHeaders(
            new Dictionary()
                {
            { "X-UTIMESTAMP", timestamp },
            { "Authorization", $"Basic {auth}" }
                })
        .AllowAnyHttpStatus()
        //.GetJsonAsync().Result;
        .GetJsonAsync
    ().Result;

Powershell


    #force tls12 connection
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

    $pubKey = "YOUR_PUBLIC_KEY"
    $privateKey = "YOUR_PRIVATE_KEY"

    $method = "GET"
    $timestamp =[int][double]::Parse($(Get-Date -date (Get-Date).ToUniversalTime()-uformat %s))
    $sig = $method + ":" + $timestamp + ":" + $pubKey

    $sha = [System.Security.Cryptography.KeyedHashAlgorithm]::Create("HMACSHA1")
    $sha.Key = [System.Text.Encoding]::UTF8.Getbytes($privateKey)
    $enc = [Convert]::Tobase64String($sha.ComputeHash([System.Text.Encoding]::UTF8.Getbytes($sig)))

    $url = "https://ws.uinform-test.ucdavis.edu/adusers/guid/ce2f2ce1-378b-450b-9ba0-16d68144a6b6"

    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $headers.Add('Accept','Application/Json')
    $headers.Add('X-UTIMESTAMP', $timestamp)

    # Create a credential object for HTTP basic auth
    $p = $enc | ConvertTo-SecureString -asPlainText -Force
    $credential = New-Object System.Management.Automation.PSCredential($pubKey, $p)

    # Make API request, selecting JSON properties from response
    $user = Invoke-WebRequest $url -Method $method -Headers $headers -Credential $credential -UseBasicParsing | ConvertFrom-Json

Postman Postman is a popular API development tool - https://www.postman.com/ 


    var privateKey = pm.environment.get("private-key");
    var publicKey = pm.environment.get("public-key");    
    var method = request.method;

    var tStamp = Math.floor((new Date()).getTime() / 1000);
    pm.environment.set("uxtimestamp", tStamp);

    var sigRaw = method + ':' + tStamp + ':' + publicKey;    
    var sigEnc = CryptoJS.HmacSHA1(sigRaw, privateKey);
    var encoded = CryptoJS.enc.Base64.stringify(sigEnc);
    pm.environment.set("enc", encoded);

    var authStr = btoa(publicKey + ':' + encoded);
    pm.environment.set("auth", 'Basic ' + authStr );

Python (v3.8.3) Disclaimer: A python developer did not write this 


    import requests
    import hmac
    import base64
    import time 
    from hashlib import sha1

    privateKey = b'YOUR_PRIVATE_KEY'
    publicKey = 'YOUR_PUBLIC_KEY'

    timestamp = int(time.time())    
    rawSignature = f'GET:{timestamp}:{publicKey}'.encode('utf-8')
    hashed = hmac.new(privateKey, rawSignature, sha1)
    signature = base64.b64encode(hashed.digest())

    url = 'https://ws.uinform-test.ucdavis.edu/adusers/sam/matwilso'
    headers = {'X-UTIMESTAMP': f'{timestamp}'}

    resp = requests.get(url, headers=headers, auth=(publicKey, signature))
    if resp.status_code != 200:
        # This means something went wrong.
        raise ValueError('Could not connect to api')
    print(resp.json())