Authentication

We rarely want just about anyone with an internet connection to be able to access and modify our projects, especially if they are private. On the other hand, we also don’t want to have too many accounts with too many different passwords (for security!). For this reason, you don’t need an account to use Mattrbld, but to ensure that only you and your collaborators are able to modify a project, you will still need to prove that you may in fact do so by authenticating. In this article you’ll learn how authentication is handled within Mattrbld and what you can do to make it even more secure and to ensure that it will work with your Git provider of choice.

Authentication in Git

If you’re a developer and have worked with Git before, you know that in order to clone a private repository or to push changes to a remote repository, you either have to authenticate yourself with a username and password, or via an SSH key.

Since Mattrbld essentially does pretty much the same as you would do on your machine if you were to edit content using a text editor, naturally the same is true for it. Unfortunately, SSH doesn’t work in a browser, so for Mattrbld you’ll need to use your username and password, or even better, an access token, as you’ll learn below.

This means that while you and your collaborators don’t need an account to use Mattrbld, you will need an account for the Git provider hosting your project. For example, if your project’s repository is hosted on GitLab, you and every user you would like to collaborate with on that project will have to have a GitLab account. The same is true for GitHub, Bitbucket, and all the other Git providers.

Why not use OAuth?

Mattrbld is a static web application. That means that everything runs on your own device and all the webserver does is distribute the files (HTML, CSS and JavaScript) needed to make that work. As such, it would be impossible to keep the cryptographic keys necessary for OAuth safe and secret.

In addition to that, Mattrbld aims to be as decentralised and agnostic as possible, so you can use it with any Git provider, even your own. Authentication via OAuth would require Mattrbld to be registered as an app with all the Git providers out there, which would be impossible and require an unreasonable amount of extra time.

When Do I Need to Authenticate?

Authentication with your Git provider will always be necessary whenever you are trying to:

• Import a project from a private repository

• Sync local changes to a central repository, be it private or public

This is a necessary step to prove that you are in fact allowed to read t he project (while importing) and make changes to it (while syncing).

If you perform one of the above actions, Mattrbld will open a dialog asking you to authenticate before proceeding. Oftentimes you will only see this when opening a project and then when syncing the changes.

This dialog will offer you the option to remember the credentials until the end of the session, which will no longer ask you to authenticate when needed, unless something goes wrong. For security reasons the password will be cleared if you hit your browser’s refresh button, navigate to a different site or otherwise close Mattrbld, or switch between different local profiles (it’s stored only in memory and never on disk).

Use an Access Token!

Instead of using your GitLab/GitHub/Bitbucket/etc. password, you should instead generate an Access Token. This is a special string of characters that can be used like a password, but will only have certain permissions on your account (to work with Mattrbld it only needs read and write permissions to your repositories, nothing else). Access Tokens have a defined lifespan and can be revoked at any point, which makes them more secure and ensures that you won’t have to enter your personal password into a website.

If you are using 2-Factor-Authentication (2FA), you will have to use such a token, and some Git providers such as GitHub have started requiring them whether you have 2FA enabled or not.

You can learn how to generate an Access Token in the documentation of your Git provider. Here are the links for GitLab and GitHub. Since it’s quick and easy to create Access Tokens, you should also revoke the one you’re using for Mattrbld once you no longer need it, for example because you have decided to no longer use Mattrbld.

Fine-Grained Personal Access Tokens on GitHub

GitHub is introducing personal access tokens with fine-grained permissions, which allow you to scope them to individual repositories and severely limiting their permissions, making them even more secure. For such a token to work in Mattrbld, you only need to allow “Read and write” permissions for “Contents” in the “Repository permissions” section.

On Security Concerns

Your password or token will never be stored by Mattrbld. However, since most Git providers require the use of a proxy server, it will be sent through the CORS-proxy you defined for your projects along with the rest of the data you are syncing with the central repository. You should always make sure that you are only using Mattrbld via an secure connection, i.e. by ensuring that you are using a HTTPs connection.

If you don’t trust the proxy that comes bundled with Mattrbld, please use your own and be aware that proxies or instances of Mattrbld hosted by third parties may not have your best interests at heart.

Access to your repositories is valuable, so please take good care of your credentials.

Now you know what a project is and how to import it, despite the content being in a private repository by authenticating with your Git provider. The next series of articles will introduce you to the options you have to configure the project in Mattrbld, as well as explain where those configuration options are stored.