API Authentication Practices

[nardell]

When I have experimented with Canvas APIs I have used access tokens that I create from my account. Seemed like a reasonable way to get going with tests. However when I consider moving the API code to production (for things like monitoring and reporting) I will need to set up automated processes that can authenticate for API access. I am asking the community what is considered the best-practice for API access authN/authZ when building automated processes. 

I am considering setting up a functional user (with permissions and account scope set according to need) and creating an access token from that user. Alternatively,  I am planning on creating a developer key from the scoped functional user account. Wanted to know if there are any recommendations on specifics. I like the look of the new scoped developer keys, however it is not clear if I can scope a developer key to only have access a particular sub-account (without using a a sub-account scoped function user.) 

Again thanks for any advice.

Mike 

[nardell]

I think much of my question may be touched on in this article/ discussion:

https://community.canvaslms.com/docs/DOC-14390-canvas-apis-getting-started-the-practical-ins-and-out... 

Will read that carefully; looks good. But I think much of my question may really be focused around more pedestrian issues about the procedural aspects of creating the tokens/ keys. One think I have noticed is that is a bit harder to create access tokens or keys from a functional user now. Seems like there is a new security feature that disallows key/token creation by masquerading. 

[prj_site_commun]

All API work is done as some user, so for an automated process that isn't driven by human interaction, it makes sense to create a user with just the permissions needed for your API access.  You'd need a developer key if you were planning to jump through the OAuth hoops, but even then you'd still need some particular user to authenticate as.  Creating an authentication token lets you skip the developer key, if you aren't doing anything with human interaction.  As you noted, you do have to really log in as the API user to create the authentication token, but that's easier than coding the OAuth process.

[nardell]

Paul :: Yeah, I have just arrived at a conclusion that echoes your advice. I am a little disappointed that Dev Keys do not  fit into the machine to machine communication story. I finally worked through the OAuth flow documented here: OAuth2 - Canvas LMS REST API Documentation, to convince myself that it is not a good fit for the automated processes I am trying to facilitate (needing to click through a browser/user orientated authorization step is pretty much a deal killer). It is worth noting that there is an OAuth2 Grant Type and Flow that does seem to be applicable to automated process communication [Note reference below]. However this grant/flow does not seem to be implemented on Canvas; I tried but was rejected when I tried to pass grant_type with the value client_credentials. 

I should emphasize that from an application admin perspective, Dev Keys with the new scoping feature really does seem like the best way to manage access controls for the kinds of automated processes many folks at our institution want to implement. I have set-up functional accounts, created special Account Admins with selected permissions, etc, and it really is a pain when compared to creating Dev Keys with scoping control. Oh well - glad to have an answer even if it is not the answer I wanted. 

Mike

=========Notes===========================

A Guide To OAuth 2.0 Grants - Alex Bilbie - look for the the section which describes the Client Credentials Grant. 

also check out the OAuth 2.0 RFC

RFC 6749 - The OAuth 2.0 Authorization Framework 

[nardell]

Paul :: By the way, I may have missed a  key point in my first read of your response: "All API work is done as some user, so for an automated process that isn't driven by human interaction, it makes sense to create a user with just the permissions needed for your API access" -- I understand that now. My main misunderstanding was a belief that Dev Keys were a short-cut around the functional user creation, auth token creation, and management (at the cost of the OAuth2 overhead). As an aside (and as someone really quite new to OAuth2), I can see that there are some nice security aspects that machine to machine processes could benefit from even at the cost of the implementation overhead. One of the main reasons I was trying to make an automated process work with OAuth2.

Mike

[dtod]

I'm trying to wrap my head around Developer Keys. Right now my understanding is that the developer key is simply to uniquely identify an application which is authorized to act on behalf of users.  After a user authorizes the application, then the application is acting as that user with the same permissions of that user, unless we restrict the scopes of the application in which case it will have a subset of the permissions of that user.

Is that right?

I'm working with a vendor which wants to do some quite extensive admin-type things that an authorizing user would not be able to do (e.g. a faculty member could not search all courses in an account), but my reading implies that I have to create a user for that vendor, grant it enough permissions, and then create a developer key for their application. They then have their user authorize the application and go from there (or shortcut it by creating a token just for their special user).

What I want to do is be able to restrict the permissions for their admin-type user with the kind of fine-granted control that scopes give me, but if I'm right, then the only way I could do that is if that user was the only user of the developer key (which may be the case).

[themidiman]

The developer key is what Canvas uses to 'trust' an LTI application for Oauth process in order to create user access tokens on behalf of the user that eventually uses their Canvas login for plausible API usage within Canvas once the Oauth process has finished. It is completely separate from the access token itself. I haven't developed an LTI in the past, but it became more apparent and understandable to me once our institution adopted UDOIT. 

https://community.canvaslms.com/docs/DOC-12657-4214441833

[pklove]

Just be careful not to mix LTI up with the API and API OAuth process.

While an LTI might use the API and OAuth to get a token, the need for this depends on the LTI.

And you can have applications that use the OAuth process to get an API token that are not LTI tools.

[pklove]

Yes, I think you have understood it all correctly.

You cannot apply scopes to a manually generated token, it gets all the permissions of the user.

So you need to create a scoped developer key and give the vendor the key and a user they can log in with so they can go through the OAuth process to get their token.

Or, I guess you could go through the OAuth process yourself and give the vendor the access and refresh tokens.

[kimhuang]

Hi Folks,

I found this thread is very informative and helpful.

Hope you can shed some light on the Canvas API Authentication issues that I am facing. The university wants to develop a LTI tool to help a course instructor add a TA/student to the course site without violating the FERPA rule. (For Example, an undergraduate can't be the TA of the course.) The university doesn't want the instructor to add a course participant by using the "+People" button because of the FERPA rule.

When an instructor launches the LTI tool, the tool inherits the instructor's API permissions. An access token is generated by following the Oauth2 Flow for this instructor.

 However the instructor permission doesn't allow him/her to get the new participant's user information in Canvas(canvas internal id, etc. the canvas internal id is needed to enroll the new participant to the course).  That's because the permission of getting any Canvas user's information is at the account level. An instructor's role is at the course level.

I am considering setting up a functional user (with permissions and account scope set according to need) and let the function user to go through the Oauth2 Flow to get the access token in order to call the Canvas API to get the new participant's information. 

However this functional user still needs to go through the human interaction to authorize the app to access his account. Is there a way to bypass the human interaction menu to authorize the access? I have attached a screen shot.

Alternatively, I can generate an access token for this functional user to avoid jumping through the Oauth2 hoops. This LTI tool is hosted in the private cloud. According to your experience, how big is the security risk?

Thanks so much for reading my email,

Best,

-Kim

[matthew_buckett]

@kimhuang We use Access Tokens as outlined in the https://community.canvaslms.com/t5/Student-Guide/How-do-I-manage-API-access-tokens-as-a-student/ta-p... to provide our LTIs with the ability to perform operations the user using them doesn't normally have and I think it's perfectly acceptable from a security point of view.  We have also created a user/role especially for a "functional user" so that should the token become compromised it has limited access to data in Canvas.

I think you can also delete the role after you have assigned it to your "functional user" in your account so that it doesn't confuse admins in sub-accounts.