How to Set Up a Client App to Authenticate to Panoptes

You're making an app. It's supposed to authenticate with Panoptes. Panoptes manages client application authentications with the OAuth2 protocol.

Never heard of it? I highly recommend this introduction, which achieves astonishing clarity in 5 minutes: https://www.rubytapas.com/2020/03/23/understanding-oauth2-with-horses/

For your app specifically, here is what you are going to do:

1. Create a user in Panoptes with the permissions that you want the app to have.

• For example, if you want your client to update whatever projects it wants, it needs admin privileges.
• More likely, it needs to read specific projects before publication, or write to specific projects. So in those cases the user needs to be added as a collaborator to those specific projects.

2. Log in as this user. Now go to https://panoptes.zooniverse.org/oauth/applications.
3. Create a new application.
4. Put in the name, redirect URIs, and permissions.

A note on redirect URIs: this is where Panoptes is redirecting after assigning your app a temporary key prior to authenticating it for a full-fledged bearer token. You will have the one that you are supposed to use for local testing, which is likely to be something like "http://localhost:someport/oauth/complete/panoptes/." <-- See the backslash at the end of that URL? That's important. It can be the right URI and without that backslash the Doorkeeper app we use won't recognize the URL.

You do not need to "authorize" these local URLs.

5. When you create the application, you will get an application id and a client secret. Put these in environment variables so that your client app can get access to them. It uses these to do stuff on Panoptes.
6. Implement OAuth authentication using the instructions for your client framework (for example, in django-rest, that's social auth). Now users can sign into your client app. Again: this step depends on the framework.
7. When a guest (a person using your client application) makes a request to do something that requires Panoptes authentication, your client app should check that the signed in user has the access rights to do whatever they're asking to do with Panoptes.

You can do this through the Panoptes client. Here's an example line that uses the Python client to fetch all the projects for which the currently signed-in user is allowed to upload subjects: Project.where(current_user_roles='collaborator')

If your guest does not have permission from Panoptes to do the thing they want to do, spit out a 401 UNAUTHORIZED error. If they do have permission, move forward with the request. You no longer need their credentials for the remainder of the code flow. We are done with the guest's credentials.

8. When it is time to perform the action the user wanted to do with Panoptes through the Panoptes client, re-authenticate withe the APP's credentials (not the user's). This is where you use those client ID and client secret variables you saved to the environment earlier.