Administrative guidelines for issuing Canvas Developer Keys

jpoulos
Instructure Alumni
Instructure Alumni
33
20974

24 Jan 2019 Update: This guide is still relevant, but you should also learn more about some new features that have been released since this was posted. Thanks for all the comments and feedback that helped me understand where the knowledge gaps and confusion are surrounding our new developer key features!
____________________________________________________________________________________________________________


When working with an integration provider (i.e. vendor, internal development, etc.), they will often ask for a developer key. Many integrations require Canvas API access to function correctly, and developer keys are currently the most secure way to allow integrations to access the API. This documentation covers some of my recommendations for how to decide whether issuing a developer key to a vendor is secure and safe. There is no general “best practice” for addressing this challenge since every institution has it’s own sets of requirements and procedures for security and privacy.

Developer keys can be issued by a Canvas Account Admin in order to allow an integration to request access on behalf of the user to the API. The user is prompted to approve access to the application and upon approving an API token is granted to the integration.



242489_pastedImage_1.png

     An example of the UI shown when a developer key to requests access to a user's Canvas API



After authorization, Canvas generates an access code that is later exchanged for an API token by the external application. The integration can then make API requests as if they were that user. In other words, they are able to make API requests to all of the same endpoints that the authorizing user has permission to.

Considering API tokens inherit the permissions of the granting user therefore granting that same level of access to the vendor, you might consider doing the following before issuing a developer key:

  • Ensure you have a formal written contract with the vendor and that your relationship with the vendor is in good standing.
  • Ask the vendor to explicitly document all of the API endpoints their integration will be using (this should be a list of all the data that is being read and written) and, optionally, why.
  • Reserve the right, in writing, to take any actions your team deems appropriate should the vendor make API calls outside of the scope that they defined without notifying your team.
    • NOTE: Developer keys can be disabled via the Admin UI which will invalidate all issued API tokens to the integration.
  • Ask the vendor to clearly state how it complies with FERPA and any other laws that apply to your students (e.g. COPPA, accessibility laws etc...).
  • Ensure you understand the vendor’s security policy surrounding how they store API tokens and developer keys (ex. they should never be exposing the developer key or API tokens in any kind of UI, including error reports; only their core engineering team should have access).
  • If available, ensure that your institution's security team has reviewed the application’s security.

Again, whether you follow some, all, or even more of these guidelines is up to your team to decide. Hopefully this discussion can help you make the best choice for your institution.

Discuss: What are some of the policies that your institution has taken to determine when to issue developer keys?

33 Comments
awilliams
Instructure Alumni
Instructure Alumni

Deactivated user Thank You for this. It is quite timely as we have been discussing various aspects of 3rd party integrations, including security and data privacy. I'm looking forward to hearing what other institutions are doing.

Before I accidentally hijack your blog post, how would you feel about us discussing other aspects related to 3rd party integrations here as well? Accessibility would be the next top item I'm interested in. FERPA / Accessibility are big issues for good reason and I think an institutional process for evaluation such as you outlined for security are a must moving forward but would, in most cases, include other aspects of review and compliance.

jenn_stevens
Community Contributor

Agreed, Deactivated user‌, this is fabulous!

jpoulos
Instructure Alumni
Instructure Alumni

awilliams, I agree that accessibility is probably another requirement that should be discussed. I'm going to update the main post to reflect that.

fosterl
Community Contributor

Deactivated user‌, another big thank you for posting this. We're about to issue a Developer Key to a vendor we have had a long relationship with, but so far have only installed their LTI. I hadn't really grokked the need to follow up some of the steps you outline above, due to this established relationship; but I will now! Better safe than sorry. Is this a great community, or what?

Sylvia_Ami
Community Contributor

Thank you Deactivated user‌ for posting this. Your list of questions/things to consider is very helpful. This is very timely for me as well.

Question for all - When you issue a developer key, do you do it as you? Or do you create another role with less access and generate the key logged in as the other user? I'm very leery of 3rd parties asking for full admin type access.

fosterl
Community Contributor

You wouldn't want to create an access token as you (Admin) and give it to anyone, but a Developer Key only gets the permissions of the user running the tool. As tr_jbates‌ mentioned in his presentation at #instructurecon 2017‌, you wouldn't really want to run a tool using a Developer Key as yourself because THEN the tool does have full Admin privileges (as you). But the Developer Key just lets the tool using it prompt each user for their permission to run, and uses that user's credentials and level of access.

Anyone more knowledgeable, please correct me if I'm wrong! I'm just regurgitating what I've heard here and from the InstCon 0017 prezzie.

sonya_corcoran
Community Novice

Thanks for elaborating Lindy.

It would be helpful if this was covered clearly within the documentation. It seems like figuring out the permissions/restrictions on API access within Canvas is a little trial and error.  @justinball ‌ would you have any intel on this ('scuse the InstructureCon0017 pun).

justinball
Community Member

I agree with  @fosterl  that you don't want to create a API token and give that out especially if you are a Canvas Admin. If you really do need to issue an API token for some reason then create a new user with limited permissions and issue a token under that user. That way you can easily track what that user is doing and shut down access if the application misbehaves.

As far as a developer id and key (also known as an OAuth key and secret) you'll still want to be careful who you give those out to - make sure it's a vendor that you trust and have a relationship with. Using the developer id and key an application can ask for permission to access the Canvas API on behalf of the current user. Once the application has that API token it can do anything the user can do. I'm pretty sure the API team is working on some enhancements to lock down access and LTI 2 comes with services that reduce the need for an API token at all.

I'm on the vendor side of things and it can be a challenge to make things simple for users, but I think that security wins over simplicity. We build our tools using the Atomic Jolt LTI Starter App (it's open source if anyone wants to play with it) which handles the LTI and Canvas API integration. That application requires that all API endpoints used be whitelisted so that we know exactly which API endpoints are allowed and we can provide that list to a customer so that the Canvas admin knows exactly what the application is allowed to do. Typically, we'll only need access to around 5-10 API endpoints so it's easy to review and it's easy to lock down API access on our end.

I know it's a challenge but I would say be sure to talk to the tool vendor before providing a developer id and key so that you know what they are going to do with it. Better yet have a contract in place so that you make them back up their claims in writing.

jpoulos
Instructure Alumni
Instructure Alumni

It should be noted, however, that admins can disable a developer key and doing so will de-active all the tokens that have been generated from that key. This is just as effective (and easy) shutting down a single token that has restricted permissions. Furthermore, the OAuth2 - Canvas LMS REST API Documentation also states that "Applications in use by multiple users MUST use OAuth to obtain tokens". This is primarily due to the fact that there is no security framework surrounding how a manually generated token should be send between client and vendor so Canvas cannot ensure that the token won't be hijacked.

anna_lamb
Community Participant

Thank you everyone for the valuable information.  I attended the InstructureCon session also, but API is new to me.

I got our first request for developer keys for Globalyceum, but we don't have any procedure setup or form setup yet.

I am looking for something that help us get start.

I'm wondering if anyone already have a security form (questions you ask the vendors) that you are using and willing to share the form?  And what procedure do you have in placed for approval?

bchen
Community Participant

Thank you Deactivated user‌ for this posting. Information provided is very helpful, since we are about to give out a developer key to a 3rd party vendor.

In your post you mentioned "Developer keys can be issued by a Canvas Account Admin in order to allow an integration to request access on behalf of the user to the API." Does that mean I can create a user with lower admin permission and use that user to generate the developer key, that way our 3rd party vendor will only have the level of access as the user who generated the developer key? If that's the case when the user permission gets changed, will it also changed the developer key's level of access; or a new developer key needs to be generated to reflect the change of permission?

fosterl
Community Contributor

Hi Benson,

You can do what you describe with Access Tokens; we do this from time to time (create a user with limited admin permissions, then create at access token as that user). We do this almost exclusively for internal purposes, although we do have one vendor we've handled this way. The Developer Key is only issued at the root level of your Canvas account, and uses OAuth to permit any of your Canvas users to consent to using it; this gives the vendor with that Developer Key the permission of THAT USER ONLY (by providing a access token behind the scenes, I'm pretty sure).

I hope this helps!

Adrienne_J_Gaut
Community Champion

This is a good discussion, thank you for posting your recommendations. I'm trying to understand/learn more as we define our own App approval process, policies, and flowcharts.

Here's one I haven't seen before and I'm more than a little leery. 

Vendor asks for a Developer Key (ID and Key) information. Then the directions are to add the App with By URL. They then give directions to use the Developer Key ID as the Consumer ID and the Developer Key as the Shared secret.

Ummmmm....no....right? That kinda puts the Dev Key right out there, doesn't it? 

Other integrations we have that use a Dev Key, then have a different Consumer ID/Shared secret generated by that vendor for the App install.

I'm taking the stance that I'm misunderstanding something about the risk of re-using the Dev Key into in the App ID/secret. Though, my spidey-sense is going off so I don't think my instincts on this are off. We haven't done anything yet with this vendor.

Help? Thoughts?

Thanks in advance!

kmeeusen
Community Champion

I do not think you are missing anything,  @Adrienne_J_Gaut ‌, and would insist on an explanation from the vendor.

Typically Dev Keys are used by the vendor so that the product can make API calls to your Canvas instance for whatever reason.

I just find the whole thing suspicious.

Kelley

Adrienne_J_Gaut
Community Champion

Thank you for the confirmation Kelley! I think...they just don't know how to do it. Their prior method was a bit off too.

kmeeusen
Community Champion

I was going to say that, Adrienne, but I did not want to hurt anyone's feeling - the big crybabies!

Because of it's very structure, which easily permits customization by integration of external tools, coupled with it phenomenal market-share growth, everybody wants to jump on the Canvas LTI tool bandwagon, whether they know what they are doing or not. We are seeing integrations, and then we are seeing "integrations."

When I investigate a vendor, almost the first thing I ask them is, "does it integrate with Canvas?" I am guessing I am not the only one. However, we are seeing many vendors saying yes, and yet their so-called integrations are truly a mess. A vendor for a course evaluation tool (I will not say who), sold our VPI a real boondoggle that was supposed to integrate - by "Integrate" they meant it would create a link, that we would then have to manually add to every course, every term, and we also needed to upload mass flat files to provide this "integration" with information it could have gotten out of our Canvas account if it had been a true integration. She learned her lesson, and now always asks eLearning before signing the P.O.

Buyer beware, and all that jazz!

Kelley

kbickell
Community Contributor

Kelly, we learned that lesson a while ago too - now we always ask for a demo first, or at the very least some instructions that shows what "integration" really means...

kmeeusen
Community Champion

Hi Kris:

We do same, and we also ask for schools that are using their product so that we can talk to both the integration team and the end users.

Kelley

Adrienne_J_Gaut
Community Champion

Indeed!

We have a list and flowchart for integrations/apps and various levels of questioning depending on if it's the course, sub-account, or account level install. Then of course the usual questions (mentioned all above in prior posts) about FERPA, data security, security of the data communication between their tool/Canvas, the endpoints, etc.

We have not yet installed anything with this vendor, their prior method raised eyebrows and they were on the path to correcting. It'll end up being a really sweet integration when it's all built out. They just have to get their act together on understanding dev keys, API tokens, and the like. Before I approached them I wanted some community feedback. I'm the one who suggested they look into a Dev Key as the first handshake as that is the method promoted by Instructure as being the most secure (if all the ducks are in a row). 

kmeeusen
Community Champion

Boy, we are just a bunch of negative nannies! How's a poor fly-by-night vendor supposed to make a buck? Going back to being used-car salesmen would be a great start.

Adrienne_J_Gaut
Community Champion

Want to give a shout out to Jacob Bates InstructureCon presentation and Q&A:

 

anna_lamb
Community Participant

Adrienne,

You mentioned that you have a list and flowchart for integrations/apps and various levels of questions.

Would you willing to share that list?  We don't have anything for our district and it would be very helpful if

there is a sample list to help us get started.  Thanks in advance!

phanley
Community Contributor

Jessie, would you mind commenting on how this advice might have changed with the release of scoped developer keys, specifically with regards to the fairly large number (~60) of inherited keys?

When the feature was released we disabled all of the inherited keys - in part due to the fact that we did not have any of the things you advised, and in part because we didn't even know what most of the products that had inherited keys did.  Before disabling the keys we checked with our rep, who agreed the advice you've given here and in your presentation on the subject was sound, and also agreed that any entity we didn't have an arrangement with should not have an active developer key. So we disabled all of them, since we hadn't configured any LTIs that depended on them (as far as we knew). 

Almost immediately, we discovered that (I think) all of our publishers were using those inherited keys with their LTIs, which was a slightly irritating surprise. We re-enabled the developer keys for integrations that stopped working, and left the rest off, so we were at about 9 keys enabled. 

But today, we've discovered that they've all been re-enabled, and we're unable to disable any of them - which is prompting some concern about security, as well as making us wonder what the use of putting a vendor we're talking to through a bunch of hoops when they could contact Instructure and arrange a globally installed developer key instead?

Sorry to put you on the spot, but the way the inherited developer keys aspect was revealed has been a bit mystifying when measured against the guidelines laid out here.

Has Instructure taken care of this in a way that we're not aware of, e.g. are all of these companies bound by contracts with Instructure that follow the basic principles outlined in your OP above?

Adrienne_J_Gaut
Community Champion

...we just discovered the inherited keys, otherwise-known-as Global Developer Keys when a vendor told us they already had a developer key. Say what?! We will be turning off access to vendors we don't already have a relationship with or their apps are installed (like textbook publishers).

It would be great if Instructure shared with us the information on their criteria/vetting in order to give a Global Developer Key to a vendor. We will be asking out CSM as I couldn't find any info besides "working closely with Instructure".

rebecca_william
Community Participant

I can no longer turn off the Inherited Keys either. They are all on and locked. Kind of freaking me out!!

fosterl
Community Contributor

Hmm, our inherited keys are NOT all on and locked. Maybe this is because we already had the Feature Option enabled to allow management and scoping before this was enforced on 10/27. Make sure that the role you're in (if not full Account Admin, and maybe even then) includes the Permission "Developer Keys - manage".

phanley
Community Contributor

Interesting - I can confirm that this afternoon I was logged in as a full admin and couldn't change anything, but I just checked again and now I can turn them off -- however all but the top 3 were still on, so I'm assuming there was some sort of problem.

Adrienne_J_Gaut
Community Champion

Yesterday I emailed our awesome CSM -- she wrote back that the Partnership team identified a bug and were onto a fix. Looks like are working on it.  She also said the Partnership team would be sending out a communication with more info.

fosterl
Community Contributor

 @phanley ‌, now that you mention it, we too have just the top three OFF and the rest ON. Do other institutions have VitalSource, iClicker Sync, and Derivita OFF? We're going to have to do some testing before we can turn others off. I don't know, for example, if the various publishers we have integrated actually use these, or if the integration we have created handles this (we have several publishers: Pearson, McGraw-Hill, Cengage, MacMillan). I'm pretty sure TopHat has told us they are no longer using the Global Dev Key (back in April 2018), but I'll confirm with them before I turn it off and break things. I would love to be able to just turn them all off, but we permit instructors to add apps in their own courses, so we might mess them up if we do.

rebecca_william
Community Participant

Did anyone see any communication about this bug yet? 

awilliams
Instructure Alumni
Instructure Alumni

If anyone has a support case number for this that would be helpful.

atcarver
Community Contributor

 @fosterl  "I would love to be able to just turn them all off, but we permit instructors to add apps in their own courses, so we might mess them up if we do."

This is the dilemma at my institution. If we disable these inherited keys, do we in effect become a gatekeeper to individual instructors being able to install an app for their course? It seems so.

Any Instructure documentation on the possible apps impacted by the toggling of these inherited keys would be quite useful to have. Since these are applied by default by Instructure, it would seem logical they would provide documentation that can help with decisions on toggling inherited dev keys.

jk224
Community Explorer

Hello! This post and comments have been really helpful. Does anyone have any examples of questionnaires they've shared with these vendors to get this information in writing? Our team is looking for examples so we can put something together when we have possible new integrations. 

Thank you!