How to Authenticate with a UPM Scoped Registry using CLI

Published in

OpenUPM

4 min readAug 2, 2020

Feel free to check out openupm.com to discover more open-source UPM packages, and support OpenUPM at patreon.com/openupm.

Starting from Unity 2019.3.4f1, developers can authenticate with a scoped NPM registry by following verbose instructions. Eventually, Unity will add authentication UI support in Unity Hub. Before that, you can use the openupm login command to simplify the process to make your life easier.

Table of Contents

∘ How it works
∘ Using token
∘ Using basic authentication
∘ Always auth
∘ Windows Subsystem for Linux (WSL)
∘ Authenticate for Windows system user
∘ The trailing slash issue

How it works

Authentication is important for sharing private packages with your team members to fulfill security requirements. Unity allows you to configure the .upmconfig.toml file to authenticate with a scoped registry. The file is located at:

Windows: %USERPROFILE%/.upmconfig.toml
Windows (System user) : %ALLUSERSPROFILE%Unity/config/ServiceAccounts/.upmconfig.toml
Linux and macOS: ~/.upmconfig.toml

You can verify the authentication by viewing the file content later.

There are two ways to authenticate with an npm server:

using token (recommended): a server-generated persistent string for the grant of access and publishing rights.
using basic authentication: the username:password pair (base64 encoded) is stored locally to authenticate with the server on each request.

Both are supported by openupm-cli login command since 1.11.0. Please upgrade to the latest version first.

npm install openupm-cli@latest -g

After login, all openupm-cli commands will use .upmconfig.toml configuration to authenticate with your private scoped registry.

Using token

openupm login -u <username> -e <email> -r <registry> -p <password>i.e.
openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873

If you don’t provide a username, email, or password, it will prompt you to input the value.

If your npm server doesn’t require an email field, you can provide a dummy one like yourname@example.com.

Notice that for the npm server allows user creation via CLI, providing a new username will create a new user.

The token is usually persistent so that requesting a new token is not meant to invalidate old ones depends on your npm vendor.

The token is also stored (or updated) to the .npmrc file for convenience.

//127.0.0.1:4873/:_authToken="token string here"

After the authentication your .upmconfig.toml will look like:

[npmAuth."http://127.0.0.1:4873"]
email = "user1@example.com"
alwaysAuth = false
token = "token string here"

Using basic authentication

Adding --basic-auth option to use basic authentication. You should only use this option when your npm vendor does not offer the authentication token. Make sure you understand the risk that the username:password base64 encoded string (still a plain text) is stored in your local machine.

openupm login -u <username> -e <email> -r <registry> -p <password> --basic-authi.e.
openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --basic-auth

Notice that your username and password is not verified during the login process, but simply stored to the .upmconfig.toml file. Because verify the password against your npm server will generate a token, which is not what you want here. Basically, type your password carefully.

Unlike using the token, .npmrc lacks syntax to support multiple registries for basic authentication. Hence, the .npmrc is not updated for the basic authentication.

After the authentication your .upmconfig.toml will look like:

[npmAuth."http://127.0.0.1:4873"]
email = "user1@example.com"
alwaysAuth = false
_auth = "base64 encoded username:password pair"

Always auth

Adding --always-auth option if tarball files hosted on a different domain other than the registry domain.

openupm login -u <username> -e <email> -r <registry> -p <password> --always-authi.e.
openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --always-auth

Windows Subsystem for Linux (WSL)

By default, the command treats the Windows Subsystem for Linux (WSL) as a Linux system. But if you want to authenticate for the Windows (probably where your Unity installed on), add --wsloption.

Known issue: run with --wsl option may clear the terminal screen during the process.

Authenticate for Windows system user

Make sure you have the right permission, then add --system-useroption to authenticate for the Windows system user.

The trailing slash issue

The registry address should match exactly with your manifest.json. This can be confusing because:

The manifest.json file usually uses a registry address without a trailing slash.
The .npmrc file always added the trailing slash.

To make it clear, the command always trimmed the trailing slash when storing it to the .upmconfig.toml file. Make sure the manifest.jsonfile follow the same rule: i.e. use http://127.0.0.1:4873 instead of http://127.0.0.1:4873/.

If you find any issue to authenticate with an npm registry vendor, please ask for help on this thread or create an issue.