Sign in and contexts

Sign in in the browser. The command prints a link and a code; open the link, sign in (with a password or single sign-on), check the code and approve:

relic auth login https://relic.example.com

Sign in with a user name and type the password at the prompt:

relic auth login https://relic.example.com --user alice

In a script, read the password from standard input and save the context as ci:

echo "$PASSWORD" | relic auth login https://relic.example.com -u ci --password-stdin --context ci

In a CI job, exchange the platform's OIDC token through a workload identity:

relic auth login https://relic.example.com --identity github --oidc-token "$ID_TOKEN"

The exchanged token lives an hour at most. The other sign-ins create an access token that lasts 90 days, or --expires-days within the limits.

The token and server URL are saved as a context, named after the server's host unless you pass --context, in relic/config.yaml (mode 0600) under your user configuration directory (~/.config on Linux). The password is never stored.

Signing in again to a context revokes its previous token. Neither that nor logout touches tokens given to package managers (Package managers) or made with relic auth token create. When relic auth login cannot save the context, it fails and revokes the token it just created.

Every command takes --context, --url and --token, and reads RELIC_URL, RELIC_TOKEN and RELIC_CONFIG. Flags win over environment variables, which win over the saved context; --context therefore wins over RELIC_URL and RELIC_TOKEN. A context's token and certificate authority go only to its own server: when --url or RELIC_URL names another server, give its token with --token or RELIC_TOKEN. The URL must be an http:// or https:// URL, and spaces and line breaks around a token are dropped.

Change your password

Change your password, giving the current one; the new one needs at least 8 characters:

relic auth password

--password-stdin reads the current password from the first line of standard input and the new one from the second. Tokens and sessions stay valid. In the UI, the key button next to Sign out does the same. Users of LDAP or single sign-on change their password there.

Servers with a private certificate authority

A server that generates its own certificate authority (TLS) needs one of these at sign-in:

• --ca-file with the authority's certificate, ca.crt, from the server's administrator.
• On a terminal, answer y to Trust this authority for <host>? [y/N] after comparing the SHA-256 fingerprint shown with the one the server logs at start.

Otherwise the command fails and prints the fingerprint. The context keeps the authority, so signing in again to the same context and URL needs neither.

On the server's own machine

Where relic server setup installed the service, a command needs no sign-in while no flag, environment variable, saved context or chosen config file names a server or token. It reaches the service at the address in its settings file, signs in with RELIC_ADMIN_USERNAME and RELIC_ADMIN_PASSWORD from that file, and trusts the ca.crt in its RELIC_TLS_DIRECTORY.

• The file is the service's server.env, or /etc/relic/relic.env for a system service. Only those who can read it get this access: the user who ran the setup, or root and the relic group.
• It stops working once that password is changed; sign in with relic auth login then.
• relic package setup still needs a context, because it hands out a token.