How to Configure the PeerTube OAuth2 Plugin

To use Amazon Cognito as a Provider

author avatar

By James

How to Configure the PeerTube OAuth2 Plugin

Most engineers that work with AWS will be familiar with Amazon Cognito, and it’s use cases. For readers that are not familiar with Amazon Cognito, Cognito provides authentication, authorization, and user management for your web and mobile apps. Here are a couple of reasons you would use this Cognito with PeerTube:

  • To enable access to a PeerTube instance to an existing Amazon Cognito user pool without sign ups.
  • Integration with social identity providers such as Facebook, Google, Amazon, and enterprise identity providers such as Microsoft Active Directory.

I will not explain how to configure Amazon Cognito. Instead, the focus of this post is how to install and configure a new PeerTube plugin. The plugin adds external authorization via any OAuth2 provider. In this configuration, Amazon Cognito is the OAuth2 provider. If you want information on how to configure an Amazon Cognito user pool, please refer to the AWS documentation.

What is PeerTube?

PeerTube is a decentralized and open-source alternative to video broadcasting services like YouTube or Vimeo. The PeerTube project aims not to replace these services, but rather to offer something else, with different values. PeerTube servers form a network of inter-connected small video hosters. Each instance hosts its users and their videos. In this way, every instance is created, moderated, and maintained independently by various administrators. If you are looking for information on PeerTube, see https://joinpeertube.org/.

PeerTube has support for plugins. These plugins allow administrators to extend the functionally of a PeerTube instance without modifying the source code. This post will show you how to install and configure the OAuth2 plugin for an Amazon Cognito user pool.

What is OAuth2? OAuth 2.0 is an authorization framework that has become the industry standard in providing secure access to web APIs. OAuth allows users to grant external applications access to their data, such as profile data, photos, and email, without compromising security. See An Illustrated Guide to OAuth and OpenID Connect for a great explanation of OAuth2.

Installing the OAuth2 Plugin

  1. Login your PeerTube instance with an account the belongs to the Administrator role.

  2. Click the Administration menu item at the bottom left of the page.

  1. Click the Plugins/Themes menu item at the top of the page.

  1. Click the Search button.

  1. Scroll down to auth-oauth2 plugin in the search results.

  1. Click the Install button for the plugin.

After a successful download and installation the Install button is removed.

Configuring the OAuth2 Plugin

  1. Click the Installed menu item at the top of the page.

  1. Click the Settings button for the plugin.

  1. Enter the “Settings” for the plugin.

To activate the plugin, configure the following settings:

Setting Required? Description
Provider display name Cognito or a name of your choosing
Client ID yes The client id string from your Cognito app client settings.
Client secret yes The client secret string from your Cognito app client settings.
Domain yes The fully qualified domain name from your Cognito app client settings. example: auth.example.com
Scope yes email openid profile
Authorize URL path yes /oauth2/authorize
Token URL path yes /oauth2/token
Identity URL path yes /oauth2/userInfo
Identity username field yes username
Identity email field yes email
Send identity token sent via HTTP header? yes check the box

Note: The plugin will not function if the required settings are missing or if the settings for the provider are incorrect.

  1. Click the Update plugin settings button.

  1. Check the Login Form

If the plugin is activate and all required settings are valid, the login form will now show a new button under Or sign in with.

Troubleshooting Tips and Help

Review the PeerTube logs for error messages related to this plugin. If you need assistance with setting up a PeerTube instance on AWS, feel free to contact me.

Additional Resources

Posted on:
September 20, 2020
Length:
4 minute read, 653 words
Categories:
Security