Chimera: Painless OAuth for Plugin Frameworks

Plugins can help teams unlock the full potential of Mattermost, but they aren’t always ready to go out of the box. Learn how Chimera streamlines plugin configuration via an OAuth2 Proxy.

One of the best aspects of any software offered in the Cloud is the ability to start using it in just a matter of minutes. The same is true for the Mattermost Cloud offering. You sign up, create a workspace and in a couple of minutes, you can invite your friends or coworkers and start collaborating using Mattermost Channels, Playbooks, and Boards.

That is not the full power of Mattermost, though. The big thing for our software is plugins. They provide a ton of useful features such as integration with GitHub, GitLab, or Zoom, to name just a few.

While easy to install through Plugin Marketplace, some plugins require additional configuration, like in the case of GitHub or GitLab registering your own OAuth 2 application. Such applications can be safely used by many users. However, OAuth credentials (Client ID and Client Secret) are required to connect them to the Mattermost plugin, and those cannot be shared with anyone.

Reducing Friction to Using Mattermost Plugins with Chimera

Although not complicated, registering an OAuth Application for each plugin requires some general understanding of OAuth 2 and might take a few minutes to set up. It is quite a tedious process as it requires following a set of instructions that differ for each provider. Additionally, it adds some small maintenance cost, as new plugins features may require setting some new permissions or rotating credentials.

To help our Cloud customers fully appreciate what Mattermost has to offer, we wanted to reduce the friction of using those plugins by removing the step of registering and maintaining OAuth 2 Applications. Thanks to Chimera, our OAuth2 Proxy, Mattermost Cloud users can skip registration of their own OAuth2 applications on the provider side (such as GitHub or Zoom) and use applications pre-created by the Mattermost team. This allows them to connect their plugins much easier, ripping the benefits of awesome integrations even faster.

How Do Mattermost Plugins Use OAuth 2?

Before jumping ahead, let’s take a brief look at OAuth 2 itself and how it is used by some Mattermost plugins.

OAuth 2 is a very common standard nowadays and you have probably used it at least a few times. Whenever you log in somewhere with GitHub or Google you are using OAuth 2. In such a case there are two servers involved in the OAuth 2 flow:

• Authorization Server — Google or GitHub — verifies the identity of the user and issues Access Token after the authorization.
• Resource Server — the website/app you are trying to access — hosts protected resources the user is trying to access.

In short, the OAuth flow (specifically Authorization Code flow) consists of the following steps:

• When users click Login with GitHub the application redirects them to Authorization Server using ClientID to identify itself. There users can log in to their account and grant the application requested permissions. 
• Then the Authorization Server triggers a callback to the application with the attached Authorization Code. 
• After receiving the callback the application can finish the flow by requesting Access Token (using ClientID, ClientSecret and Authorization Code) which then allows it to access Resource Server on behalf of the user.

There is, of course, more to OAuth 2 than this. There are security measures, `state` identifying the session, and different authorization flows, but this big picture should be enough for the purpose of this article. If you would like to go deeper into the details of OAuth 2 you can find a lot of information on helpful websites such as this one or do your own research.

Mattermost Plugin OAuth 2 Connection

In the case of Mattermost plugins, the Authorization Server and Resource Server are usually the same thing — we authorize the plugin with GitHub to use the GitHub API.

To simplify, the flow of authorizing an OAuth 2 application in Mattermost plugins looks something like this:

Given this flow, the Mattermost plugin needs to know a Client Secret of an OAuth application created on the OAuth Provider side in order to request the Access Token. This means that each workspace requires its own OAuth Application for each plugin set up by the administrator. That is what is causing friction to our users and is far from a perfect user experience.

As mentioned earlier, there is nothing wrong with multiple workspaces using the same OAuth Application but they cannot know the same credentials (as those are configured in System Console and visible to the administrator). We needed a way to keep the Client Secret actually secret without overhauling each plugin and Mattermost server to handle it differently. That is where Chimera comes in.

Simplifying OAuth 2 with Chimera

Chimera is an OAuth 2 Proxy for pre-configured OAuth 2 Applications. Mattermost plugins can work with it to allow users to leverage OAuth 2 Applications created by the Mattermost team in order to make full use of plugins in their cloud workspace.

So how does it work?

Chimera acts as an OAuth Provider for Mattermost plugins proxying authorization and token requests to the proper provider like GitHub or GitLab. From a plugin perspective, the OAuth flow remains the same but it no longer requires it to know a Client Secret of the OAuth Provider application as all that is stored securely in our cloud infrastructure and only Chimera can access the credentials.

The simplified flow now looks something like that:

After obtaining the Access Token, the plugin communicates directly with Resource Server (GitHub) and requests do not need to go through Chimera again (unless the user disconnects and connects again).

From a plugin perspective, this approach leverages the same code path for both a user-registered OAuth Application as well as Chimera, with a slight difference in where the initial OAuth credentials come from. Other than that, Chimera acts as an Authorization Server (which in fact is just a proxy) and the Resource Server remains the same.

There is one additional step for the user that is not shown on the diagram, where Chimera asks the user to ensure that RedirectURL points to the correct workspace. This is to prevent malicious actors from trying to trick users to authorize an incorrect workspace.

There are some other security measures, as well as session mechanisms that we will not go into in this article.

Connecting the Plugin with Chimera

Now with Chimera up and running, setting up the plugin is much easier. Instead of registering each OAuth Application by themself, users need to only enable the plugin, flip a switch in Plugin configuration to use a pre-registered OAuth application, generate other required settings like Webhook Secret and At Rest Encryption Key with one button click, and connect using a slash command.

Everything can be done in a matter of seconds, without following the multi-step instructions of registering an OAuth app or even leaving the Mattermost workspace.

Limitations

Of course, there are some limitations to that approach, which we can not work around. The most significant one is using non-official GitHub or GitLab URLs (ie an enterprise offering like my-company.github.com). The OAuth application created on the official GitHub.com will not work with those sites and there is of course no way for the Mattermost company to create them. However, users of those platforms can still leverage the traditional plugin connection by creating their own applications.

For now, Chimera integrates with the GitLab plugin and GitHub integration will be available with the next GitHub plugin release. You can find the code on Github.