Auth for new RESTful API (2019-09-16)
Caitlin McCabe
Administrator
Original Post: Deborah Fitchett, September 19, 2019 at 10:12 PM
I'm trying to get started with the new RESTful API. I'm a self-taught programmer on the side of my real job so struggling a little with the documentation at points that might be obvious to people who code for a living. 😃
I'm using PHP and cURL. (I can't gain any insight from the Python examples on GitHub, it may as well be in Sanskrit; I can't even tell which of the sample files is relevant to me.) I've worked with RESTful APIs before but in my experience the way auth is handled varies wildly from API to API (user/pass, cookies, tokens, checksums; sending data in the url vs header vs post data....) and I'm not clear what's wanted here.
1) With the SOAP API (which I never got working, I'm even less comfortable with that than with RESTful!) we had a username/password. With RESTful I take it we create a client with ID and secret, so have done that.
2) I also take it the next step is to use that ID and secret to create a token. I see the machine-readable documentation at , but... not having learned APIs formally I can't translate any of this into Human so can't figure out what any of these options means or how they fit together. Which endpoint(s?) do I need to contact? How do I pass the data to them? What other parameters (scope etc?) are required?
3) And then I presume I use the token to make my actual API call (GETting folders and sessions using the documentation at ) - but again do I pass the token through in a header, or what? (Or even better can I just use the client id and secret directly, in which case again how?)
Thanks for any help anyone can provide!
Deborah
Responses
Deborah Fitchett, September 22, 2019 at 11:59 PM
(For additional information: I want to write some code that can get basic information about videos in our Panopto site, including title, creator, date created, any description, and privacy level. The goal is to create, on a daily basis, a list of public videos that we can index in our library discovery layer. It would be read-only; it'd be scheduled by cronjob; no users would interact with it.)
Mark Brewsala, Moderator, September 25, 2019 at 4:57 PM
Hi Deborah,
I think our forum swallowed your links. Was the article you were referencing this one about getting OAuth2 tokens?
https://support.panopto.com/s/article/How-to-Get-OAuth2-Access-Tokens-for-Users
We don't currently have any PHP code examples for getting or using OAuth tokens. But here are some resources for demystifying OAuth in PHP and cURL:
https://stackoverflow.com/questions/25423924/oauth-2-0-in-php-using-curl
Let us know if you're still blocked after checking those out.
Thanks,
Mark
Deborah Fitchett, September 25, 2019 at 6:09 PM
Hi Mark,
Thank you, that's a completely new link to me - I'd only found:
https://support.panopto.com/s/article/support-panopto-com-s-article-oauth2-client-setup ("How to Use OAuth2 Clients" which doesn't go that far)
and
https://lincoln.ap.panopto.com/Panopto/oauth2/.well-known/openid-configuration (the JSON 'documentation' for the OAuth API which I can't make head or tail of)
It looks like exactly what I wanted - and makes clear that I've been heading off on a tangent. So, backing right back up to the start:
My use case is a scheduled (cron) job that will access a list of video titles etc to make them available for indexing in an external system. So there's no human/browser interaction at all.
The link you provide covers instructions for the varieties of web application clients, but that's clearly not what I need. "How to Use OAuth2 Clients" (https://support.panopto.com/s/article/support-panopto-com-s-article-oauth2-client-setup) mentions that two other options are:
- Server Application (Client Credentials Grant)
- User Based Server Application (Resource Owner Grant)
Which of these two do I want for my use case, assuming I want to get title/link/etc details for all videos in particular (non-user) folders?
And are there instructions somewhere else for authenticating using those methods?
Deborah
Hiroshi Ohno, Moderator October 2, 2019 at 5:46 PM
Deborah,
Thank you for the reply.
I understand that your end goal is to run a service program without the user interaction.
This article discusses such scenario in details:
https://support.panopto.com/s/article/oauth2-for-services
To summary,
- Server Application is for only specific type of API and not appropriate for general usage.
- User Based Server Application is an option for the scenario, but please note that it's your responsibility to save the accessing user's actual password in safe manner. We support this primarily for migrating the legacy applications, but it is not recommended as a best practice of OAuth2's usage.
- The best practice of OAuth2 is that your service provides UI for initial authentication (and re-authentication when the sync is lost with some reason) somehow and works the rest of time without user interaction.
I hope this helps.
Deborah Fitchett, October 8, 2019 at 7:38 PM
Thanks very much for this information! It looks like exactly what I need. Can you explain more about why Server Application is not appropriate for general use? It seems perfect for what I need to do (where it’s just not possible to have a user authenticate) so I want to make sure I’m not missing any major disadvantages/potential problems. Otherwise the only other option for me would be User Based Server Application and as you note this isn’t best practice. Deborah
Hiroshi Ohno, Moderator, October 8, 2019 at 7:55 PM
Hi Deborah,
Server Application flow exists for some special API that are not associated with any user context. Most of our API need to identify who is the caller, and I believe all API you will use require a user. Thus, it is useless for you to get the token through Server Application.
Deborah Fitchett, October 9, 2019 at 8:11 PM
Thank you! Two steps forward, one step back: I’ve successfully got a token, using parameters: $url = $base_url . 'Panopto/oauth2/connect/token'; $header = array( 'Content-Type: application/x-www-form-urlencoded', 'Authorization: Basic ' . base64_encode($api_key . ":" . $api_secret), ); $data = 'grant_type=password&username='.urlencode($username).'&password='.urlencode($password).'&scope=api'; (Note unlike for other app types, the documentation doesn’t say to include the authorization basic header for the User Based Server Application, but I don’t get a token without it. It would be good to have this clarified in the docs.) I then use this token to access the Folder API: $url = $base_url . 'api/v1/folders/' . $folder_id; $header = array( 'Authorization: Bearer ' . $token, 'Accept: application/json', ); (No $data as it’s a GET request.) But now I get a 403 error. (I actually get exactly the same error if I try to use the access token from a Service Application.) I’ve tried giving the user not only view, create, and publish permissions for the specific folder, but also the admin system role – all no luck. Having reread all the available documentation a dozen times I’m now stumped – what am I missing? Deborah
Hiroshi Ohno, Moderator, October 9, 2019 at 9:08 PM
Deborah,
Thank you for trying it. It sounds like you are doing the right thing as far as I see write here. It think the best thing here is to open a support ticket through your organization's Panopto administrator, so that our support team may see more closer look, for example why error is returned from the server log.
Deborah Fitchett, October 9, 2019 at 9:21 PM
Will do! Thanks again very much for all your patience and help. You’ve definitely answered my original question and it’s reassuring to know I haven’t made any really obvious mistake here. :-)