Authentication#

Credentials matter in two distinct situations when using sysand:

  • Publishing to the official Sysand Index. The index at sysand.com is public — browsing and installing projects requires no credentials — but sysand publish requires a bearer token and fails up-front if no bearer-token credential matches the index URL. See Create an API token, which also shows the per-shell commands for configuring the token.

  • Reading from an access-restricted location. Any Sysand index or project download location may require authentication — for example a self-hosted index on an internal network. Then sysand needs credentials just to fetch projects.

The rest of this page explains which authentication methods sysand supports and how to configure credentials.

Sysand currently supports:

  • HTTP(S) using the basic access authentication scheme

  • HTTP(S) using (fixed) bearer tokens (used by, for example, the Sysand Index and private GitLab pages)

  • Git, for projects fetched from git repositories. When git is installed, Sysand runs it with your existing setup, so anything that already works for git clone — SSH keys, credential helpers — also works for Sysand. There is no Sysand-side way to configure git credentials; the SYSAND_CRED_* variables described below do not apply to git.

Configuring credentials#

Currently, authentication is configured only through environment variables.

Credentials for the basic authentication scheme are provided by setting environment variables following the pattern:

SYSAND_CRED_<X> = <PATTERN>
SYSAND_CRED_<X>_BASIC_USER = <USER>
SYSAND_CRED_<X>_BASIC_PASS = <PASSWORD>

Where <X> is arbitrary, <PATTERN> is a wildcard (glob) pattern matching URLs, and <USER>:<PASSWORD> are credentials that may be used with URLs matching the pattern.

For example, the following settings tell Sysand that it may use the credentials foo:bar with URLs matching https://*.example.com/**:

$ export SYSAND_CRED_TEST='https://*.example.com/**'
$ export SYSAND_CRED_TEST_BASIC_USER='foo'
$ export SYSAND_CRED_TEST_BASIC_PASS='bar'

URLs matching that pattern include:

https://www.example.com/projects/project.kpar
https://projects.example.com/index.json
https://projects.example.com/projects/myproject/versions.json

In the wildcard pattern, ? matches any single character other than /, * matches any sequence of characters not containing /, and ** matches any sequence of characters possibly including /.

Credentials will only be sent to URLs matching the pattern, and even then only if an unauthenticated response produces a status in the 4xx range. Note that redirects are an exception:

  • if credentials are sent to a URL that redirects to a different URL, credentials will also be sent to the redirected URL if the host remains the same

  • credentials to the redirected URL are sent without making an unauthenticated attempt first

If multiple patterns match, they are tried in an unspecified order after the initial unauthenticated attempt, until one results in a response not in the 4xx range (Sysand logs a warning when a URL matches multiple patterns).

Authentication by a (fixed) bearer token works similarly, using the pattern:

SYSAND_CRED_<X> = <PATTERN>
SYSAND_CRED_<X>_BEARER_TOKEN = <TOKEN>

With these set, the Sysand client sends Authorization: Bearer <TOKEN> in response to 4xx statuses when accessing URLs matching <PATTERN>.