Using GitHub's fine-grained access tokens with Composer

When using Composer (the dependency manager for PHP) to download packages from GitHub you might run into situations where you need to authenticate to the GitHub API, for example because you are exceeding GitHub rate limits for unauthenticated requests or because you are trying to download a package that is private. The secure way to do so is by using a personal access token (PAT), a randomly generated secret token that is tied to your GitHub account but only grants limited access to your account.

Traditionally, you would generate a personal access token with a set of scopes to define the access granted to an application using the token. If you only needed to circumvent the rate limit for public repositories, it would be enough to generate a token without any scopes. Such a token would allow you to circumvent the public rate limit, without granting any additional access to (private) repositories. However, if you wanted to use the token to also download private Composer packages, you'd have to select the repo scope to allow the token access to private repositories you have access to. That meant that the token didn't just allow you to download the private repository, but would grant full control of all private repositories you can access - including read and write access to the code, commit statuses, collaborators, and webhooks. Much more permissions than we needed to simply download a private package, and a clear violation of the principle of least privilege.

Introducing fine-grained personal access tokens

Luckily, GitHub recently introduced a new type of personal access tokens which allow much more fine-grained control over the granted permissions than the classic personal access tokens. Instead of selecting broad scopes that apply to your whole GitHub account and all repositories you have access to, you can now choose whether the token should allow access to your personal repositories or to a specific organization, and you can limit the repositories the token has access to (only public repositories, all repositories, or selected repositories), the level of access (read-only or read & write access), and the specific permissions to permit access to (such as repository contents, metadata, issues, etc.).

Fine-grained personal access tokens are currently in public beta, so you can already start using them. In order to generate a fine-grained personal access token, go to your user settings in GitHub and navigate to Developer settings → Personal access tokens → Fine-grained tokens, then click on Generate new token. You will have to give the new token a name, an expiration, optionally a description, and connect it to either your personal account or an organization you're member of. Next, select which repositories the token can access, and the specific permissions that are granted to the token.

Selecting the right token permissions for Composer

Which permissions to select for a Composer token depends on what you are trying to achieve. If you just want to avoid hitting GitHub's public rate limits, you can select Public Repositories (read only) under Repository access without giving the token any permissions:

On the other hand, if you want Composer to download private repositories, you will have to select either All repositories or select the specific repositories you want to grant access to, and grant Read-only access to the Contents repository permission. This will automatically also grant access to the mandatory Metadata permission.

Finally, click on the green Generate token button to generate the token. You will see the token, which starts with github_pat_, on the screen. Copy it now, because this is the only time GitHub will show it to you and you'll have to regenerate it if you lose it.

Now you can store the generated token in Composer as described in the Composer documentation:

composer config --global github-oauth.github.com github_pat_XXXXXXXX

Using fine-grained tokens with organization repositories

If you want to use the new tokens to download private repositories owned by your GitHub organization, there are a few extra things to consider.

First of all, when creating a new token you have to choose a resource owner: either your personal GitHub account, or an organization you're a member of. The token will only be able to access resources owned by the selected resource owner. This means that you cannot create a token that Composer can use to download private repositories from both yourself and from an organization, or from multiple organizations. If you are working on multiple projects which require private dependencies owned by different GitHub organizations, you will need to create separate tokens for each of them and store them locally in your Composer projects by running the composer config command without the --global flag.

Before you can select an organization as a resource owner, an organization owner has to allow the use of fine-grained personal access tokens. In the organization settings, under Thirt-party access, there is a new section Personal access tokens which allow the organization to allow or restrict access via both fine-grained and classic personal access tokens, and optionally require administrator approval before a fine-grained personal access token can be used to access resources within the organization.

From a security perspective, it makes sense to allow the use of fine-grained personal access tokens within your organization, and start phasing out the use of classic personal access tokens. That way, your developers can apply the principle of least privilege to their personal access tokens, reducing the risk of data loss in case of a compromised token.