How to Authenticate with a UPM Scoped Registry using CLI
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 --wsl
option.
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-user
option 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.json
file 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.
Feel free to check out openupm.com to discover more open-source UPM packages, and support OpenUPM at patreon.com/openupm.