Using JSON Web Tokens to Authorize and Authenticate To Blackboard Collaborate

Version 3

    Blackboard Collaborate relies on JSON Web Tokens (JWT) to authenticate and authorize incoming REST API calls. JWT is self-contained and yet quite compact open standard, as defined here. Because JWT relies on JSON rather than XML, the resulting token is much smaller than in other XML-based standards like SAML, and it is built so that the payload contains all the information the recipient needs with each call reducing the number of database calls necessary to validate the incoming message, as well as the necessity to maintain state on the Server. Lastly, it is designed to be flexible; the Token may be signed with either RSA or HMAC. RSA allows the REST Client to sign the JWT with public and private keys via x.509 Certificates, while HMAC allows the JWT to be signed with a shared secret. Either way, the data can be trusted because it is digitally signed with mutually known credentials.

     

    JWT Assertion

    The JWT Assertion is the JSON Web Token request for access. These are built with a consistent structure, as defined below:

    • Header
    • Payload
    • Signature

     

     

    The Header and Payload are each Bas64 Encoded and the three parts are separated with a dot (.), resulting in a token that resembles the following:

     

    encodedheader.encodedpayload.signature

     

    JWT Header

     

    The header is a small JSON object containing two key pieces of information: the algorithm used to generate the signature and the type of token being created. This will generally always be the same in any given application. In this example, the application is signing the data with HMAC-SHA 256 and requesting a JSON Web Token.

     

    {
       "alg": "HS256",
       "typ": "JWT"
    }

     

    To create the first part of the token, simply base64 encode this JSON and save to a string.

     

    JWT Payload

     

    The next piece of the puzzle is the payload. The payload contains information about the calling application that uniquely identifies the client to the REST server. There are many data points that can be sent as part of the payload, but for the Blackboard Collaborate REST APIs, there are only three pieces of information expected: the issuer of the request, the subject of the request, and the expiration time of the assertion.

     

    The issuer should always be the REST API key provided by Blackboard. The Subject should also be the REST API Key. The expiration time must within 5 minutes of the time of the request, and should be expressed as the number of seconds since 1970-01-01T0:0:0Z measured in UTC.

     

    {
       "iss": "my-collab-rest-key",
       "sub": "my-collab-rest-key",
       "exp": "1480457763988"
    }

     

    As with the headers, simply base64 encode the payload and append a dot followed by the payload to the previously created string.

     

    JWT Signature

     

    The last thing that must be included in the assertion is the signature. The signature is basically the string created above(encodedheader.encodedpayload), signed using the algorithm specified in the header and the REST API secret provided by Blackboard. The resulting string must then be appended to the assertion following a dot.

     

    Building a JWT Request

     

    The assertion is the main point of contention in requesting access to the Collaborate API set, but there are other factors, as well. As defined in the JWT standard, the request must also include a grant_type parameter. The grant_type should always be set to 'urn:ietf:params:oauth:grant-type:jwt-bearer' in Collaborate requests. This grant_type and the assertion above should be added as query parameters to the Collaborate token endpoint and POSTed as a form/urlencoded.

     

    Here is an example of a request for a token, containing an assertion based on the example payload and header in this document and the REST API shared secret of 'secret':

     

    POST /token?grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJteS1jb2xsYWItcmVzd
    C1rZXkiLCJzdWIiOiJteS1jb2xsYWItcmVzdC1rZXkiLCJleHAiOiIxNDgwNDU3NzYzOTg4In0.7eElTSzDRfWaQlKeVaMDJlN0-_7dmNq7nRP82pm47kY
    HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Host: xx-csa.bbcollab.com
    Connection: close
    User-Agent: Paw/3.0.13 (Macintosh; OS X/10.12.0) GCDHTTPRequest
    Content-Length: 0

     

    Using the JWT Token

     

    The result of all this work is a token returned from Collaborate that allows the application to make authorized calls into Collaborate to perform operations. This token is then appended to corresponding API calls in the form of an Authorization header in the HTTP message set equal to Bearer returnedToken. As an example, below is a HTTP GET requesting all the users on the Collab server:

     

    GET /users
    HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODAzNzM2ODEsInN1YiI6ImJiQ29sbGFiQXBpIiwiaXNzIjoiYmJDb2xsYWJBcGkiLCJ0eXBlIjoxLCJjb25zdW
    1lciI6IjkxRjA1RENEODhGQzQzRkMwMUY0NjI5MDEwQzNFQjc3IiwiaWF0IjoxNDgwMzczMzIxfQ.Vi7jejTo380R_DYWO202q3dvd0XYsQbmpFd3DCgku64
    Host: xx-csa.bbcollab.com
    Connection: close
    User-Agent: Paw/3.0.13 (Macintosh; OS X/10.12.0) GCDHTTPRequest

     

    Additional Resources

     

    JSON Web Tokens are a widely adopted standard in modern applications, and thus, there are a ton of resources available for developers interested in JWT beyond the scope of Blackboard Collaborate.

    • JWT.io: This site is dedicated to assisting developers trying to build JWT-enabled applications. There is a debugger that allows you to manually input your secret and your header and payload and generate an assertion. There is also an extensive list of available libraries in multiple languages that handle the bulk of the JWT creation.
    • RFC 7519: This is the actual standard specification document.