Three-Legged OAuth

Document created by scott.hurrey on Aug 22, 2017Last modified by mkauffman on May 30, 2018
Version 6Show Document
  • View in full screen mode

One of the drawbacks associated with Basic Authentication is that the application requires broad access, as the tool is acting as a system-level user and enacting for the user. Three-legged OAuth (3LO) allows an application to act as a user. This sounds scary, but it actually allows for much more granular access control. Rather than a system user acting as someone that can modify all courses, the application is now acting as Professor X, and as such, only has access to his or her courses.


As of Blackboard Learn 3200.7 (SaaS deployed release), third-party REST applications now have the ability to implement 3LO to authorize a user against the APIs and act as that user. In the spirit of sharing pretty pictures, here is a nice diagram displaying the workflow:



So let's talk a bit about what is happening here. Let's pretend that we have built a mobile app that allows a student to get his or her grades. Today, we will be Marlee. Marlee picks up her iPhone and opens the GetMyGrades app. The first time Marlee opens the app, the app will send a GET request to /learn/api/public/v1/oauth2/authorizationcode with the Content-Type set to form/urlencoded and the following data as query parameters:


redirect_uriWhere to redirect the user once they have authorized the applicationredirect_uri=
response_typeMust be set to code. Tells the endpoint to return an authorization coderesponse_type=code
client_idThe application's OAuth key, from the key/secret pair as registered in the developer portal.client_id=8DBBA050-B830-414F-B7F1-0B448A6320C9

The application's permissions: read, write, delete, and/or offline. Offline is required to use Refresh Tokens

CAUTION: If you do not set the scope appropriately you will still be able to get an access_token, but when using the access_token you will not be able to GET, POST, or UPDATE as expected. Instead you will get error responses.

stateOpaque value used to prevent Cross Site Request Forgerystate=DC1067EE-63B9-40FE-A0AD-B9AC069BF4B0


So in this example, my request would look like:


GET /learn/api/public/v1/oauth2/authorizationcode?redirect_uri=


The result of this action is that Marlee is presented with her school's Blackboard Learn login screen. She logs in and is presented with the following screen, asking her to authorize the application.




Once Marlee clicks 'Allow', the URL sent as the redirect uri is called with the authorization code as a query parameter, for example:


Now the application is able to talk server-to-server as Marlee. The next step is to get an access token from Learn based on the authorization code Marlee granted. From here the workflow is very similar to the Basic Authentication method. The token is requested as a POST request from /learn/api/public/v1/oauth2/token. This is also a form/urlencoded. The body of the request contains the text grant_type=authorization_code, and the URL is parameterized with the code (code=1234567890) and the redirect_uri (redirect_uri= So the request looks like:


     POST /learn/api/public/v1/oauth2/token?code=1234567890&redirect_uri=


The endpoint responds with the standard token (access_token, expires_in, and token_type), but also has a couple of new fields. If offline mode is granted, a refresh_token is returned. This allows the application to get a new token on behalf of the user, even if that user isn't explicitly asking for it. In addition, the scope requested in the initial request is returned, as well as the UUID for the user in the user_id field.


From this point forward, the access_token is used just as it is when using Basic Authentication, but instead of acting as the system user, it is acting as Marlee.


Refresh Tokens


As mentioned above, one of the available scopes that an application can request is offline. Essentially, the offline scope allows an application to access Blackboard Learn as a user without requiring the user to login each time. This might be especially useful in a mobile application to prevent the unnecessary redirects each time an application is loaded. The way this works is through the use of refresh tokens.


The first time a user accesses the application and the normal 3LO process takes place. The user is redirected to Blackboard, they login and authorize, and then the application is off an running. The difference is that a refresh token is returned in addition to the Bearer token. From this point forward, the third party application can automatically request a new bearer token by sending the request with the refresh token without involving the user at all.


The HTTP message might look like this:


     POST /learn/api/public/v1/oauth2/token?refresh_token=8DBBA050-B830-414F-B7F1-0B448A6320C9&redirect_uri=


From this point forward, the access_token is used just as it is when using Basic Authentication, but instead of acting as the system user, it is acting as Marlee.



GitHub - blackboard/BBDN-3LO-REST-Swift: A sample application written in Swift demonstrating the new three-legged OAuth …

4 people found this helpful