Administrative guidelines for managing Inherited Developer Keys

[jpoulos]

There have been some important changes to developer keys (see the 14 Jul 2018 and 10 Oct. 2017 release notes) since my last blog post about what administrators should consider when issuing developer keys. Through feedback from the community and from our clients, I’ve noticed there is a lot of confusion surrounding developer keys in general, and specifically surrounding the Instructure-issued developer keys that appear in the “Inherited” tab of the Developer Key Management UI. This blog post should hopefully answer many of the frequently asked questions surrounding developer keys and give Canvas Account Administrators a deeper understanding of how to best manage developer keys.

Dev Keys overview

A developer key allows an application to request access to a users API information. In all cases, the user must authorize the application to act on his/her behalf. If the user authorizes an app, Canvas generates an API token and securely responds to a request from the external application with the generated token. The app can then store that token and use it to perform the API requests that it has access to. You’ve probably seen this in the UI (see image below), but may not realize that a developer key is involved:

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

Types of Developer Keys

There are two types of API developer keys: account-bound or inherited (this may also be referred to as a global developer key).

Account-bound developer keys are issued by the Account Admin and will only be able to request API access from users that belong to that account.

Inherited developer keys are issued by Instructure based on a basic set of criteria (see our API docs under the “What management features are available?” section) and can access any account where they have been enabled.

History

Understanding the history of developer keys in Canvas will help you understand your current list of inherited developer keys.

Before October 2015

Account-bound Developer Keys did not exist, so if a vendor wanted API access, we had to work with them to issue a global/inherited developer key. As you can imagine, this raised concerns, so a series of releases (19 Sept 2015, 10 Oct 2015, and 31 Oct 2015) allowed developer keys to be account-bound and managed by the Canvas Account Administrator for each institution.

October 2015 to July 2018
Vendors had to work with each institution they integrated with to obtain a developer key. They also had to manage multiple developer keys inside of their application. Instructure severely limited its issuance of developer keys and pressured vendors to work with individual institutions to obtain an account-bound developer key. Inherited developer keys were only issued In rare cases where they seemed like only reasonable option and where Instructure had a very strong partnership in place.

Canvas Account Administrators raised legitimate concerns over the level of access that developer keys had (the API token issued had access to every API endpoint the user had permission to access). Furthermore, they had no way to know which inherited developer keys had access to their accounts, let alone the approval process by which Canvas issued the developer keys, without reaching out to their CSM.

July 2018-present
In response to the concerns raised by our customers, we released a set of features (14 July 2018 and 10 Oct. 2017 releases) that allow for admins to manage which inherited keys have access to their accounts. Furthermore, developer keys can now have their access restricted through the use of developer key scoping.

Instructure began issuing inherited developer keys, simplifying both the management of developer keys for application owners and reducing the steps required to enabling developer key access for Canvas Account Administrators.

Default settings for inherited keys

Simply put, developer keys issued prior to July 2018 were defaulted to ON, since we wanted to avoid breaking any existing integrations. Developer keys issued after that default of OFF so that a Canvas Account Admin must approve and enable the developer key to have access to their account.

Instructure’s approval process/vetting for Inherited Developer Keys
Many admins have been surprised at the number of developer keys that they find in their “Inherited” tab, spurring (rightly) many questions related to how they got there and what processes are in place for approval. The previous section should help understand the how they got there aspect for anything issued before July 2018, but may want to know more about the current policy that Instructure takes when issuing a new developer key.

As mentioned previously, we (the Partnerships/Platform team) issue developer keys based on a basic set of criteria (see our API docs under the “What management features are available?” section).  I’ll flesh this out in a bit more detail here:

What Instructure does:

• Requires scope enforcement for newly issued inherited developer keys.
• Requires justifications for why those scopes are needed.
• Requires explanations of how developer keys and tokens are securely stored.

• Expects Canvas Account Admins to determine their own vetting policies and apply them when enabling an inherited developer key.

What Instructure likes to have:

• A basic product demo showing the integration. This is pretty much required for anyone who doesn’t have a partnership with us.
• Links to relevant documentation about the integration.

What Instructure does not do:

• Thoroughly examine the application’s code base
• Audit security. privacy, or storage policies for the application. As noted above, Instructure expects Canvas Account Admins to determine their own vetting policies.
• Ensure that the application will comply with all of our customers various integration policies.

Best practices for managing inherited developer keys as a Canvas Account Administrator

As a Canvas Account Administrator, you are the gatekeeper for which applications have the ability to request API access from users in your account. That’s a lot of responsibility, but fear not, I can help.

The first thing your should do is audit which developer keys have already been used to issue tokens in your account. The best way I have found to do this is by running the User Access Tokens report. You can then look at the “dev key id” column and make sure those are all turned on.

Next, Once you have the report, use whatever internal policies or processes you may have to determine if each of the developer keys is appropriate for your organization. You might consider doing the following:

• Determine who (at your organization) requires these developer keys / access tokens
• Check if these are still actively being used, and why
• Determine why these are being used (and document these reasons)
• Approve the continual use of these

Next, You can turn off any of the inherited keys that don’t appear in the report, but you may want to check with any of your internal teams to verify. There may even be someone who already knows which integrations are currently being used. Just know that if you turn off a developer key for an integration that depends on it, you will be limiting it or completely breaking its functionality. Note that a key can be turned on again in case of error.

Last (optional) you may want to reach out to others (admins, teachers, students etc) to keep an eye out for any errors related to integrations that throw authorization errors just in case you made a mistake.

That’s it! You’ve now limited access to only those keys that your account is dependant on. When you work with a new vendor that has an inherited key, you can now push them through whatever vetting processes your institution may have in place and then enable their inherited dev key.

A note about scope enforcement

Using scoped developer keys requires some work by the vendor that uses the developer key. They must determine the scopes they need access to and modify their OAuth2 request to include the scopes they want access to. Furthermore, some applications use “include” query parameters in their API requests. Canvas scoping ignores these parameters, so they must come up with alternatives API endpoints to more explicitly obtaining the same information. Our Partner Support team is happy to help our partners create a roadmap toward this end, but it’s up to our clients to put the heat on while understanding the technical challenges that they face.

Roadmap: Developer Key Experience Improvements

The Canvas API integration experience can be better. I’m currently scoping out requirements to enhance the developer key experience. I have some ideas in mind (ex: exposing the scopes for Inherited developer keys to Canvas Account Admins), but I’d rather hear your ideas to make sure mine are as good as I think they are! If you have an idea for an experience enhancement or any other ideas related to developer keys, please follow the Feature Idea creation process and throw a link to the feature idea in the comments! Make sure to review the comments and open feature ideas to make sure there isn’t one already open that addresses your idea.

Conclusion
I hope that this blog post has helped our Canvas Account Administrators understand more about all the recent changes to dev keys and how best to user their new shiny developer key management UI. Happy vetting!

FAQ

Q: "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?”
A: Yes. Instructors must work with their Canvas Account Administrator to turn on any inherited developer keys before their course-level integration that depends on it will work.

Q: "Where do the Inherited Developer Keys originate?"

A: Instructure issues them. See the “History” section above for more info.

Q: "Are there any best practices recommended for ensuring a higher degree of security?“
A: The same recommendations that are outlined in my previous blog post should help here, but there are no specific Instructure defined “best practices” that will work for everyone. Talk to your technical folks at your Institution, or your network of professionals to see what they think is best on top of what I’m presenting here.

Q: “Does allowing the inherited keys to remain enabled cause any unintended data to be sent to these vendors?“
A: Only if the vendors requests access to data and the end-user authorizes access. Most vendors have an LTI integration that is required before the app will even ask for authorization, so if it’s not installed, chances are you can safely turn the integration off. That said, there are API based integrations that don’t require an LTI component.

Q: “How do I know which developer keys are being used in my account?”

A: Run the User Access Tokens report and examine the “dev key id” column. If a dev key has been used to issue an API token for your account, it should appear here.

[Adrienne_J_Gaut]

Fantastic info and post, Jesse.  Many thanks!

[kedmison]

While I appreciate the post, I can't say it makes me feel any better. I'm still trying to figure out why Instructure is still issuing global keys to start with, given that the bar to get one of these appears to be pretty low. This seems like a really bad idea, as it is essentially a single credential, that if compromised, would provide a bad actor with access to data from any institution that turns that key on. That seems like a terrible design, just to make it convenient for vendors. We, as customers, have no idea what the terms of the agreements are between Instructure and the vendors that hold these keys, and that makes me really uncomfortable. 

If a vendor wants/needs dev key access, they should have to come to me as a Canvas Admin, make their case, sign a stack of papers that my institution's legal council reviews and approves. Then they get their key. 

[jpoulos]

kedmison‌

I appreciate your concerns as they are valid. My perspective is that this is a trade-off between operation burden and ease of use, and not solely for the vendor, but your staff as well. If your policy is to issue your own developer keys and securely transfer them to the vendor, the system is flexible enough that your institution can choose a policy of disabling all inherited keys and issuing your own (increasing your operational burden). However, forcing every institution to manage their own developer keys and find a way to securely transfer them to each vendor in not what everyone wants. In part, it introduces security risks during the transfer of developer keys (you must train your staff to know how to securely transfer this data). Based on our user research, many institutions would prefer the ease of use of enabling the inherited key and not having to own the responsibility of finding a way to transfer the client ID and secret to the vendor.

In general, we strive to provide customers with the tools to operate Canvas at the level of control they would like to operate. This functionality allows you to decide to inherit these keys--or control your own.

[anna_lamb]

Hello Developer Keys experts,

I have some questions about using developer keys and if anyone can help me out, it would be greatly appreciated.

Should I create the developer keys using my account (which is admin account) or create a separate admin account

for generate developer keys? And should I use a separate admin account for each vendor?  If a separate admin account is needed, what are the minimum permission needed for this account, I assume it doesn't need everything like my account?

Thanks in advance.

[Adrienne_J_Gaut]

hi Anna, 

Developer Keys aren't attached to a specific user account the way Access Tokens are. Developer Keys are created by any admin that has permission to do so, which, would most likely be the highest level admin in your account. Not all admins would/should be able to create Developer Keys. For the "owner email" - that is where you'd want it to most likely be a service account or service owner.

Are you thinking of Access Tokens, which are different? Access Tokens are tied to a user and that user's permissions...so...one would want to be very careful about admins creating Access Tokens and tied to individuals, rather than a service account.

[anna_lamb]

Hi Adriene,

I'm talking about Developer Keys : https://community.canvaslms.com/docs/DOC-12648-4214445806 

If I understand it correctly, and with the example given at top of the post, the access is tied to a user's account.

I have 'admin' access at the root account and I can generate Developer keys to vendor, and doesn't it mean their application can act on my behaff?

[Adrienne_J_Gaut]

hi Anna, 

No - the developer key isn't tied to your specific account as the creator of the developer key --- it IS tied to the root account:  "As an admin, you can manage developer keys for root accounts."  Let's say you-Anna create the dev-key for a vendor app. Then, you leave your institution and your user account is deleted. The dev key will still work. It's not tied to you. It also has its own set of permissions, it does not gain the permissions of you-Anna as a high-level admin. It can only get the vendor into your Canvas instance, but then it can't actually do anything (see data, edit/view anything in a course, etc.)

(I'm writing the rest of this post, assuming there is confusion on what a dev key does/does not do, but I'd rather you have the info if you aren't clear, rather than coming off as 'splainy about it.)

A vendor app then usually asks for authorization from a user that is using the app, and gets a user Access Token to do what it needs. That Access Token can only let the vendor do what that user-permission allows. So like, one doesn't usually want admins to click through a vendor app and give authorization for an Access Token b/c then the vendor has an admin level Access Token...which is way more data/actions available than say, a teacher-level Access Token which only gives access to actions/data that that teacher can do (in those teacher's courses). Our process is to masquerade as a non-admin user to vet/test things or use a fake account. Or, if no way around that, then after testing we delete the admin-level Access Token. 

The 'Owner Email' can be anything - you put that value in. It might be a super admin email address for a specific person, or it might be a service account, etc. One of our developer keys has a vendor email as the Owner email. We like to use a service account email in the Owner email, one that has a monitored mailbox, etc. if notifications ever happen. It also tells other admins who created it, so it's documentation as well.

I can suggest talking to your CSM about developer keys before issuing any so your institution can best understand the risks/limitations/etc. and how dev keys work.

Other folks reading, if I've put mis-information above, please do correct me

[stevenwilliams]

Hi Deactivated user‌ -- thanks for this comprehensive post about the history and current state of inherited developer keys in Canvas. 

You state that "exposing the scopes for Inherited developer keys to Canvas Account Admins" is under consideration. However, without these scopes being exposed to Admins, it's unclear how institutions are expected to "determine their own vetting policies and apply them when enabling an inherited developer key" when there is no transparency or information available around the scope of Instructure-issued inherited developer keys. Exposing the scope around the Instructure-issued inherited developer keys seems like a necessity for institutions to conduct this local review.

More generally, I understand that Instructure is a large company, supporting customers around the world with a wide range of regional and institutional requirements around privacy/security, and that individual institutions may reach different conclusions about the same integration. However, the current bar for Instructure issuing an inherited developer key feels far too low. At minimum, my institution would expect Instructure to at least capture information about vendor privacy/security policies and make this available to us. A HECVAT or similar accessibility self-assessment would also be good information to capture from vendors.

I can understand Instructure's reluctance to take responsibility for third-party tools. However, the current policies and practices around inherited developer keys shift far too much burden to institutions trying to use these integrations, without providing us with the basic information we need to conduct the local review of these tools that Instructure specifically asks us to complete.

[jsavage2]

Hi  @williamsst ‌,

I'm still trying to wrap my head around the impact of some inherited developer keys, but I'm not sure what's really being shifted to us, here, since this only applies to third-party vendors. If I'm choosing to do business with a vendor, I'm going to require them to complete whatever my institutional security review process is, and I need to be satisfied that they've implemented controls that meet my audit requirements, not Instructure's. Asking Instructure to vet them first doesn't really seem to add any value: I'm not going to take Instructure's word for it, whatever "it" is in a particular case.

If I'm satisfied with the vendor's answer, the technical mechanism seems irrelevant, here, since the developer key doesn't have inherent authorization of its own. They can either be trusted to use OAuth to authenticate users, or they can't. The suggestion here is, essentially, that I should give them a key of mine because they may have compromised Instructure's. That seems backwards. If I'm worried about their internal security, the *last* thing I want to do is give them another key. And if I've committed to doing business with them, what difference whether I enable an existing key or create a new one?

The subtext of Jesse's statement's is presumably that no developer in their right mind is going to consent to Instructure publicly exposing the inner working of their intellectual property--you can learn a lot about how an app works from the endpoints it's consuming--to people who aren't under NDA with the developer. But even if that weren't the case, what real benefit would it bring, since it wouldn't make our jobs any easier, anyway?

If I want to buy Trunitin today, I'm going to make them fill out 50 pages of paperwork before I turn on their integration. And if Jesse tells tomorrow what endpoints they consume...I'm still going to ask them for it in writing from their own lawyers and make them fill out 50 pages of paperwork before I turn their integration on.

[stevenwilliams]

 @jsavage2 ‌, here's the core of my concern:

• Instructure is requiring third-party developers to explicitly provide "scope enforcement for newly issued inherited developer keys", "justifications for why those scopes are needed", and "explanations of how developer keys and tokens are securely stored"
• Unlike institutionally-issued developer keys, which allow Canvas admins to view and modify their scope, institutions currently have no way to view the scope of any Instructure-issued developer key. Deactivated user‌ acknowledges the value of this information by stating that "exposing the scopes for Inherited developer keys to Canvas Account Admins" is somewhere on the roadmap.
• Instructure explicitly "expects Canvas Account Admins to determine their own vetting policies and apply them when enabling an inherited developer key".

If my institution's vetting policies require us to understand and document the scope of new developer keys we enable, and Instructure is already capturing the scope of inherited developer keys that they themselves issue, then why is Instructure not providing any method for institutions to view this information?

[jsavage2]

 @williamsst ‌,

Thanks, that definitely puts the discussion in context.

[jpoulos]

 @stevenwilliams ‌ and  @jsavage2 ‌,

Thanks for the feedback and discussion; it's very valuable to hear these perspectives on the product. I actually agree with both of you on the points that have raised. As you've mentioned, we definitely want to address the transparency issue that's in question here while still having people understand that it's normal and desirable to have deeper levels of conversations with these vendors! Until the transparency issue is addressed, we are happy to coordinate with your teams if there are any specific questions regarding the scopes that are enabled on any inherited key. I would recommend requesting this information from your CSM. If they need help, I will surely hear from them!

I think it's helpful to remember that just 1 year ago, there was no capability to see inherited developer keys, restrict their scope, nor disabled them from being able to access the accounts (god mode for all and with no visibility :smileyshocked:) . The conversations that have arisen since those features have been deployed are not surprising and I think they highlight why we started this work in the first place. As a bonus, I feel our users are finally starting to ask some very important questions regarding who has access to their data and what data they have access to because of these new features. Part of the product lifecycle is taking feedback from the people who use the product and incorporating it into future designs. The comments here are definitely validating the need for my project, which will help us with setting priority. Since you must be wondering, I do not have a current timeline for when the work may begin. This year my team is very much focused on delivering LTI Advantage, which may eliminate the need for some vendors to need API access in the first place (cool!). Once that's done, we can hopefully have time to revisit dev keys and add improve the UX for admins.

Jesse Poulos
Technical Product Manager, Platform Team

Instructure

[anna_lamb]

Hi Adrienne,

Thank you for the detailed information! I now have better understanding of it.

I just have one question.  You said if I use my account (high-level admin access) to vet/test things, then we should delete the admin-level Access Token.  Is that in my account's Settings, where it says 'Approved Integrations'?

[lmurray2]

@jpoulos 

Revisiting this topic 3+ years since the last comment regarding Developer Keys.

I'm perceiving some conflicting information in this thread and really need to straighten this out. I'm curious to understand the relationship between Inherited Developer Keys and Access Tokens. 

Bottom Line is I need to understand best practices for methods to scope permissions on an application that uses an Inherited Developer Key. Is the best method for doing this to create a custom Service Account with "scoped" permissions to create the Access Token? 

Does the Access Token limit the ability of the application to touch API endpoints? 

Very confused about how al this works.