[ARCHIVED] Developer key or data access token?

[John_Lowe]

How does a developer key differ from a data access token for accessing the API?

[Stef_retired]

 @John_Lowe , I don't have an answer for your question. I'm posting to let you know that given the question's specialized subject matter I'm moving it to the Canvas Admins​ group where it will garner the attention of experts in developer keys, data access tokens, API, and the like.

[erinhmcmillan]

Hi John,

According to our integration engineers, a developer key uses Oauth2 to ask a user for permission to programmatically create an API access token. Once you have an Oauth2 access token, you can use it to make API requests. The new admin feature in Canvas allows admin to create their own developer keys so they can create their own access tokens. For info about OAuth see https://canvas.instructure.com/doc/api/file.oauth.html

Hope that helps,

Erin

[John_Lowe]

So when would you use one over the other?  What are some examples where this would be used instead of a regular data access token?  With a regular data access token, the token is valid for whatever that user can do only in whatever sub-account that user has privileges.  How does that play into the developer key process?

I've reviewed the documentation previously, but I asked here for a lay-person explanation.

[John_Lowe]

Bump.  Any more comments or thoughts?

[erinhmcmillan · Accepted solution]

Hi John,

Sorry for the delay on a response. Hopefully this information is more helpful:

Right now an external tool has two ways it can get an API key for a Canvas user. First, the external tool can ask the user to generate one manually in the user's profile, and copy and paste it into their application somewhere or. The second way is for the external tool to use a developer key to ask for one, server to server. In this server scenario, a user who starts the app or launches it from within Canvas will see a screen where "Tool ______ is requesting access to your account." Once the user selects the Authorize button, Canvas issues an API token for that user to the application. This second method is preferred and more secure due to the api token never been placed in a web page or put somewhere it could be easily intercepted or compromised.

Thanks,

Erin

[RobDitto]

erinhallmark​, your answer has proven helpful to me as our institution evaluates an LTI tool from Certified Partner - Poll Everywhere​.  For the first time in my experience, a partner has specified that a Canvas Cloud customer needs to have an admin create a developer key, and to supply the generated ID/key information to the partner's application.  (We've had other partners ask for API tokens to be used in their own application's configuration screens, but never developer keys before.)

Would anything from your answer have changed since the 2015-11-21​ change involving refresh tokens?  As part of assessing this tool's security and privacy factors, I'm trying to understand the specific level of Canvas API access provided by a Developer Key-based refresh token after that release.  Does the token's API access match that of the logged-in Canvas user who invokes the LTI tool, or is that token's access like what a root admin user's API token would provide?  I reviewed this API documentation, but I couldn't determine what exactly the refresh token has access to do using the API.

I'll be happy to ask this question elsewhere if it isn't appropriate here.

Also tagging Deactivated user​ since this issue came up in a related recent conversation.

[karl]

Rob, refresh tokens do not come into play regarding access for the API token issued for a user. A third party will use a developer key to ask users to approve their application and issue a token (server to server behind the scenes) when they first launch to tool to be used to make API calls to Canvas on their behalf. The API token that is issued using the Developer Key will inherit the permissions from the user who grants access.

What the refresh token does is change issued tokens (by a developer key) from being forever living to having an hour expiration. A third party can have an API token granted for example from a teacher and use it for up to an hour. If they want to continue using the token they need to refresh it extending out the expiration for another hour. The refresh token is only a mechanism of OAuth2 process and does not impact permissions for the granted API tokens.

[RobDitto]

 @karl ​, many thanks! This is fantastically helpful information.  Based on this I can press the partner we're working with for more implementation details on exactly what their tool does with the developer key.

[Adrienne_J_Gaut]

hi Rob --- I'm so happy I found your thread, and, will be keeping tabs on what you find out from Poll Ev. We had the exact same response to them and are investigating.

Would you mind sharing what you have found out and will be doing for Poll Ev? Either here or we can take this to email.

Thanks in advance!

[RobDitto]

We're meeting internally on Friday to figure out our next steps.

[buddyhall]

 @RobDitto ‌,

Can you share what you decided to do in this instance? This LTI integration is asking for one, but they don't want it, they want us to provide the developer key to instructors so they can paste it into their applications. I'd consider entering a developer key into their software package, but sharing it publicly with instructors that want to use their product, doesn't seem very secure.

[Adrienne_J_Gaut]

Wow - what App is this?! That's crazysauce. We guard our Developer Keys with scrutiny (and multiple approvals.) For us and Poll Everywhere, we did an institutional subscription and we hold the login to that. That's where the developer key is. There's nothing on the Canvas side to install so it makes it easy. Instructors are given accounts under our blanket which gives them the access to Canvas as part of our subscription. They never or have access.

For other Apps, we will generally install them on a requested basis. Piazza for example --- we hold the secret/key info and put it into a course for the prof. Piazza doesn't give it to the profs, but to us admins.

What app?

I'm part of the movement that wants to hold App developers accountable for the security of the data, security of connection into/out of Canvas, etc. Things like App developers that use the Public setting or don't properly vet loopholes (i.e. Piazza and public courses!!) aren't doing us and faculty (and students) a disservice. Unfortunately things in the Edu Apps aren't vetted by Canvas like how Apple vets it's apps in the App Store. 

[buddyhall]

It's Poll Everywhere. We have a different polling solution on campus at the institution level. Currently there's an instructor that is interested in this integration with his account.

[Adrienne_J_Gaut]

Hmmm...conundrum for sure.

It's an Account level/root level developer key --- that's a pretty big deal, for us anyway. We also guard our institutional login for Poll Ev and have a randomly generated long/special character password to at least make that a bit more secure. Instructors under our account (we have a block of 10 instructor accounts) never see the developer key. Also, if someone hacks their Poll Ev account they'd get stopped at our WebAuth when Poll Ev tries to authenticate the user to get the class data. But the developer key - it's just there in the account settings for the integration.

I wonder if you can work out a 'trial' with Poll Ev and get an institutional license for 1 or 2 instructor-users so that you can all 'try out' the integration and think if you want a larger institutional license in the future. Then, the instructor can be put under that umbrella and can be secure.

[RobDitto]

 @buddyhall , to date our institution has not issued a Developer Key to Poll Everywhere or any other LTI tool provider.

[buddyhall]

Thanks for the follow up Rob!

[sonya_corcoran]

Hi erinhallmark‌, that is a helpful response.

Does anyone know if there is any way to restrict API endpoint access to 3rd party vendors?

Can this be done via sub-accounts / monitoring etc? Or is it a case that once you hand over an access token or developer key, that 3rd party has access to everything?

Cheers

Sonya

[buddyhall]

Hi Sonya,

Once they have a developer key they can request access tokens for any of your users. Your users have to click authorize when they access the tool. With access tokens developers can do anything that user can do and it will appear as that user has done the action. If the third party has simply requested an access token you can limit their access by the permissions on the user account that generates the access token. 

[sonya_corcoran]

Thanks Buddy, 

Do you know where in the docs this is outlined?

[buddyhall]

Not really  @sonya_corcoran . Most of this I got from awesome people in the developer community and googling access tokens. I did find this guide that talks about manually generating an access token that hits on some of it: https://community.canvaslms.com/docs/DOC-10806-4214724194 

[ja644]

How do you or anyone else on this thread handle the support of these applications that require developer keys when the person clicking on the application is an Admin in your Canvas environment?  Doesn't it then mean the application has an Admin level token with which to make API calls? 

We are less concerned with an instructor or student level token being generated, but we do not want admin level tokens getting generated, but then we are faced with this question -- how do we support them?  Do we need to make separate non-admin accounts?  

We also have a challenge with trusted vs. untrusted developer keys, Instructure only giving out trusted developer keys to their own developers, meaning we cannot masquerade as the instructor to see how it works, the app would still try to log us in as ourselves.

[jpoulos]

ja644‌

Good questions. I've written a blog post on this topic and did a webinar as well. Hopefully they answer your questions.

Blog post: https://community.canvaslms.com/groups/admins/blog/2017/07/19/administrative-guidelines-for-issuing-...

Webinar: https://community.canvaslms.com/videos/3345-partner-day-keynote-building-safe-and-secure-integration...

Regarding masquerading, we are rolling back a change that was introduced in the last release that sent the logged-in user ID for OAuth2, rather than the masqueradee user-ID. The rollback is currently deployed into our beta environment if you'd like to test it out. The production-level rollback is queued for deployment, so any day now it will be released.

Jesse Poulos

Assoc. Technical Product Manager, Platform
Instructure

[marco_divittori]

Thanks for providing these links Deactivated user, helpful resources. In your webinar you talk about the benefits of using developer keys. We're one of the institutions considering issuing an access token for an admin account with scoped down permissions. The main reason being that with the developer key approach, if a root account admin like myself needs to interact with an integrated tool (e.g. for testing, support), the tool provider would then have full API access through use of my token. I agree with the concerns you raised around transmission and storage of an access token but we feel full API access is in even larger risk. We have many ed techs that are also sub-account admins so they too would be regularly providing authorization to external tools and passing tokens with elevated permissions.

[buddyhall]

Yes, an authorization token generated by an admin would have access to do anything with the API that the admin user could. I like to request a list of all the API calls that the LTI provider vendor is making with their application. This does a few things. First, if they struggle to provide these, they either outsourced the integration, do not support it, and have no idea exactly how it works, or they don't know how to talk to you and their developers. Either way, it's a big red flag that they aren't someone I want to be partnering with. Second, based on the API calls they are making, you can see exactly what data they plan to access and if that differs from what they have told you they are using, you can have a conversation about it. Finally, you can make an account in Canvas that you only use this integration with and by viewing the page views, you can confirm they are only accessing the data they say they are.

Creating non-admin accounts is an option and I have one, but I mostly use it for testing things as a non-admin user. If I don't trust the LTI tool provider that is requesting an authorization token, I don't click authorize. Often I will also go into my account settings and revoke the access token as soon as I've completed whatever tasks needed with the tool. This means I have to click authorize a lot more often, but as a bonus, it's nice whenever I'm doing a workshop on UDOIT if I get the authorization screen that most everyone in the workshop is getting too as they have never accessed the tool. This is also nice for checking the tools unauthorized event handling. I'm a Canvas Admin though, and not an instructor so I don't have anything that might be wanting to batch upload grade data or something on a schedule. If you revoke the token, naturally that scheduled task is going to fail.

[Adrienne_J_Gaut]

We are in the "developer key and then user-level access token authorize" camp and are happy apps are using that method instead of an admin level access token (which we flat out refuse to do). 

To answer one of your questions on what we do --- any admin is told to use Masquerade when clicking through apps, which for many, take us through AS that user into the tool to offer support. This prevents the admin level access token. We'll also go back and 'clean up' and remove the user-level access token if needed after.

It happens of course, that admin level access tokens are granted either by accident or by a direct need. The rule is after an admin is done, to revoke the access token. It works for us.

As a campus-wide operations lead, I periodically pull the report of 'who has an access token and for what'. We are a small institution with under 3 dozen admins (at any admin level - account or sub-account). It's easy to look through and email folks to revoke a token if they are an admin. We have 3 main sub-accounts (med school, engineering, business school) that are on-board with this too. It works for us.

[marco_divittori]

Interesting idea to use the masquerade feature, though we have it disabled. We considered a similar approach around use of additional regular user accounts for each admin but it's unmanageable for a variety of reasons. We're a large institution (80K students, 10 main sub-accounts, 97 admins) so trying to enforce a standard workflow practice or token cleanup process is challenging.

What we really need is the ability to further scope API calls which I understand is coming. In the meantime, we've been trying to push tool providers to use LTI framework as much as possible.