Don't sweat adding a new authentication method. Here are some tips for adding a new authentication method. 

In my role as a Project Consultant, I frequently assist clients with configuring their authentication for Canvas. Because I have had several requests recently for assistance with Okta, I decided to put this resource together.

Prerequisites

• Any user that needs to authenticate via Okta must already have a user account provisioned in Canvas.
• The login ID field in Canvas must match the username field returned from Okta.
• Access to the Okta Admin Console.
• Admin access in your Canvas instance.
  
  

Configuring Okta with Canvas

To set up Okta as the identify provider for Canvas, use the following steps:

1. From the Okta Dashboard, click Add Applications.
   
   
   
   
2. Click the Create New App button.
   
   
   
   
3. Select SAML 2.0 and then click the Create button.
   
   
   
   
4. Under General Settings, name the App and then click the Next button.
   
   
   
   
5. Under SAML Settings, input https://YOURDOMAIN.instructure.com/login/saml as the Single sign on URL (ACS URL).
   
   Then check the option to Allow this app to request other SSO URLs. Copy and paste the Single sign on URL and then add 0 as the Index number.
   
   Click the + Add Another button and input https://YOURDOMAIN.beta.instructure.com/login/saml as the next Requestable SSO URL and add 2 as the Index number.
   
   Repeat the process to add https://YOURDOMAIN.test.instructure.com/login/saml and add 3 as the index number.
   
   Next, input http://YOURDOMAIN.instructure.com/saml2 as the Audience URI (SP Entity ID).
   
   Click the Show Advanced Settings link.
   
   
   
   NOTE: For vanity URLs, be sure to add https://YOURVANITYURL/login/saml as a Requestable SSO URL with an Index number of 4.
   
   
6. For the Authentication context class, select X.509 Certificate.
   
   
   
   
7. Under Preview the SAML assertion generated from the information above, click the Next Button.
   
   
   
   
8. Under Help Okta Support understand how you configured this application, select I'm an Okta customer adding an internal app and check the option for This is an internal app that we have created.
   
   Then click the Finish button.
   
   
   
   
9. Copy the Link Address for the Identity Provider metadata.
   
   
   
   
10. In your Canvas instance, go to the account settings and click on Authentication. Then select SAML on the authentication service dropdown menu.
    
    
    
    
11. Paste the Identity Provider metadata link address in the IdP Metadata URI box.
    
    
    
    
12. Scroll to the bottom of the page and click the Save button. This will populate all the required fields for the configuration. Click the Save button again to finalize the process.
    
    

Additional Resources

For more information about configuring authentication for Canvas, please check out the following guides:

• How do I configure third-party authentication providers for a Canvas account?
• How do I configure SSO settings for my authentication provider?

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.

Official Canvas Document

Canvas, as a SAML ServiceProvider, supports special values for RelayState to allow deep linking into Canvas for IdP initiated logins. An IdP can also modify the RelayState for an SP initiated login if it has outside knowledge of where it wants to send the user upon login, rather than the default (either the user's original destination that triggered the login sequence, or the user's dashboard).

In general, this functionality should be used sparingly, as deep links into Canvas can remain as bare Canvas links and rely on Canvas built-in behavior to maintain the original destination in order to not obfuscate links.

Examples

School maintained portal does an IdP initiated login, sending directly to a specific course:

POST https://school.instructure.com/login/saml?SAMLResponse=...&RelayState=/courses/1

Redirect; Location: https://school.instructure.com/courses/1‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Consortium WAYF Service redirecting through the appropriate home account for a user:

GET https://school1.instructure.com/courses/1

Redirect; Location: https://wayf.consortium.edu/login/saml?SAMLRequest=.

<User logs in at WAYF; WAYF injects RelayState based on original referrer, but does an IdP initiated login to the consortium account in Canvas, instead of the original destination of school1>

POST https://consortium.instructure.com/login/saml?SAMLResponse=...&RelayState=https://school1.instructur...

Redirect; Location: https://school1.instructure.com/courses/1?session_token=.‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍...‍‍‍‍‍‍‍‍‍

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.

     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?