Authentication and permissions in RepoForge.io

All of the functionality described in this page applies to paid subscriptions only. The free version of RepoForge.io is for public/open source projects only. If you are using the free version of RepoForge.io, all of your packages will be public, and you won't be able to make a package private, or change the permissions of a package.

Introduction

RepoForge.io implements a flexible authentication and permissions system to let you control exactly who can push data to, or pull data from, your RepoForge.io account. This article goes into detail on each of the available Authentication methods.

Access tokens vs user credentials

Whenever you login to your RepoForge.io dashboard, you do so using your user credentials. You can also use these same credentials to interact with the Python and Docker APIs (e.g to push packages to and pull packages from the Python and Docker registry APIs). While user credentials work fine when you're just starting out with RepoForge.io, we'd strongly recommend using Access Tokens for any more serious work, e.g. building a devops pipeline. Using access tokens instead of user credentials is more secure and place a marginally lighter load on the RepoForge.io servers. What's more, you can create as many access tokens as you like, whereas creating additional user accounts means ugrading your subscription.

You can create access tokens at any point from the RepoForge.io dashboard:

Just click on Create new access token, give your token a name, assign roles to it, and save it. Keep in mind that you will only be shown the token once, so you'll need to store it somewhere secure. You can also rotate the token via the dashboard at any time.

You can then use it in place of your password when interacting with your Python API:

pip install twine
twine upload --repository-url https://api.repoforge.io/my-hash-id/ my-package.whl
Enter your username: anystring
Enter your password: {my-api-key}

About roles

Users and Access Tokens in RepoForge.io can assume one or more roles. Your credentials or Access Tokens will not be able to interact with RepoForge.io's APIs unless they have assumed the correct role for the given API. For example, to push a new Python package to RepoForge.io, you must do so using credentials or an Access Token that assumes the Python - Full access role.

Here is the list of standard roles available to RepoForge.io:

• Dashboard access: This role is assumed by all RepoForge.io users and lets you log into the dashboard. You cannot remove this role. Access Tokens may not assume this role (you must be a user to login).
• API access: This role lets you interact with the RepoForge.io REST API. It can only be assumed by an Access Token, not a user account.
• Python - Full access\Python - Read only: Allows read write or read only access to interact with the Python APIs (e.g it lets you use twine/pip)
• Docker - Full access\Python - Docker only: Similar to the above, but for Docker registries
• NPM - Full access\NPM - Docker only: Similar to the above, but for NPM projects. Keep in mind that due to the way npm handles authentication, it can only be assumed by an Access Token.

Beyond the limitations described above, you can attach as many roles as you like to any Access Token or user account. By default, when you first create your RepoForge.io account, you will automatically be assigned the Dashboard access, Python - Full access and Docker - Full access roles.

Limiting access to individual packages

Whenever you push a new Python package to RepoForge.io, it will be created with default permissions. This means that any user or access token with the “Python - read only” role can install that package.

However, it is possible to change the package permissions mode to use “package -level” permissions instead. This applies to all supported package types. When in this mode, the generic Python roles are no longer sufficient to access the packages When you switch a package to package level permissions, it will create two new roles - (package name) full access and (package name) read only access. In order to continue to read/write the package, you must first edit your user credentials or access token to assume these newly created roles.

Making packages public

By default, all new packages will be marked as private, meaning that it is not possible to pull/download them with an unauthenticated request. You can make a package public by switching off the private flag in the dashboard.

When a package is public, anybody with the URL will be able to pull the package without auth.

Marking a package as public doesn’t have any impact on write permissions. You cannot push new versions or new packages without authentication.

All supported package types can be made public in this way.

Python authentication

Write access - Using twine

There are three ways to authenticate when pushing packages to RepoForge.io using twine:

1. Using --stdin

twine upload --repository-url https://api.repoforge.io/my-hash-id/ my-package.whl
Enter your username: username
Enter your password: password

2. Using the -u and -p arguments

twine upload --repository-url https://api.repoforge.io/my-hash-id/ -u username -p password my-package.whl

3. Using environmental variables

export TWINE_USERNAME=username
export TWINE_PASSWORD=password
twine upload --repository-url https://api.repoforge.io/my-hash-id/ my-package.whl

Using poetry

Refer to using poetry to see best practices on authenticating while using Poetry and RepoForge.io.

Read access - using pip

pip also provides a few auth options:

1. Using --stdin

pip install -i https://api.repoforge.io/my-hash-id/ mypackage
User for api.repoforge.io: username
Password: *******

2. Using basic auth

pip install -i https://username:passwor@api.repoforge.io/my-hash-id/ mypackage

Docker authentication

Use the below command to log in to your docker registry:

docker login https://docker.repoforge.io/my-hash-id/my-registry-name/

Once logged in, you should be able to both push and pull images with the below commands. Please note that even if you are able to login successfully, your requests to docker push/docker pull may still fail depending on your permissions - the credentials you used to login must have assumed the correct roles for your registry.

NPM authentication

Due to the way npm works, it is NOT possible to access your NPM registry using user credentials - only access tokens will work

To use an access token to authenticate requests to your private NPM repository, use the following command:

npm config set //api.repoforge.io/npm/my-hash-id/:_authToken {VALID_NPM_AUTH_TOKEN}