Logins and profiles
Several hubs, auth list, use, status, import, migrate, logout, revoke
One login is enough for most people. Then a second hub arrives: a client's hub next to your company's, a test account next to your real one, a CI identity on your laptop for an afternoon. This chapter shows how Gritpack keeps several logins apart, how to pick one for a single command or make one the default, and how to check, move, retire and revoke them safely.
What you will be able to do
- list your logins and choose the default;
- run one command with a different login;
- save a login from a certificate you were given some other way;
- move a credential to another store;
- log out of a hub, and revoke a credential on a lost computer.
A profile is a saved connection
Every gritpack login saves a profile: a name, the hub's package address,
and a pointer to the credential. The pointer says where the credential is kept,
never what it contains. Profiles live in one file,
~/.frogfish/gritpack/config.toml. A profile made with --store file looks
like this (paths shortened):
config_version = 2
default_profile = "team"
[profiles.team]
server = "packages.example.com:443"
ca = "~/.frogfish/gritpack/credentials/01a1e865-fa11-7663-8550-8c4d87a45daa/server-ca.pem"
[profiles.team.credential]
provider = "file"
certificate = "~/.frogfish/gritpack/credentials/01a1e865-fa11-7663-8550-8c4d87a45daa/client.pem"
private_key = "~/.frogfish/gritpack/credentials/01a1e865-fa11-7663-8550-8c4d87a45daa/client-key.pem"
You do not need to edit this file. The auth commands below change it for
you, and they never print credential paths or secrets.
Under the hood.
GRITPACK_HOMEmoves the whole Gritpack directory, profiles, credentials, cache and installed applications together.FROGFISH_HOMEmoves the parent~/.frogfishinstead. To use a different profile file for one command, pass--configor setGRITPACK_CONFIG.gritpack help profileslists every file and where it lives.
Listing and choosing
$ gritpack auth list
cal (default) server=packages.example.com:443 provider=file
team server=packages.example.com:443 provider=file
Here two people's logins sit on one computer, both for the same hub. The newest login became the default when it was made. Choose another:
$ gritpack auth use team
default login is now team
Every command that talks to a hub now uses team unless told otherwise.
One command with another login
Every hub command takes --profile:
$ gritpack auth status --profile cal
account=01a1e865-dc86-7153-9bdf-ef2283d4dcab email=cal@example.com status=Active
credential=01a1e867-377a-7c33-b918-33effaddbae4 status=Active expires_at=1797492440
writable_scope=@cal
The same works for add, sync, publish, search and the rest. For a whole
shell session, or a script, set GRITPACK_PROFILE instead:
export GRITPACK_PROFILE=cal
gritpack publish --dry-run
A flag on the command line always wins over the environment variable, and both win over the default.
For automation.
gritpack auth list --jsongives one record per login withname,hub,storeanddefault, so a script can check that the login it expects is present before it starts.
Checking a login
gritpack auth status asks the hub, with the selected login, who you are:
$ gritpack auth status
account=01a1e865-dba3-7352-9217-40bfb4ff47cb email=bea@example.com status=Active
credential=01a1e865-fa11-7663-8550-8c4d87a45daa status=Active expires_at=1797492359
writable_scope=@bea
It lists every credential of your account, not only this computer's, so you can
spot one you no longer recognise. writable_scope lines are the scopes you may
publish under (Names, scopes and owners). With
--json the same facts arrive as an account object, a credentials list and
a writable_scopes list.
If auth status fails, the error says why: an expired login, a hub that cannot
be reached, or a credential the hub no longer accepts. Troubleshooting by
symptom goes through each.
Connections without a profile
Sometimes you have a certificate and key in hand and do not want to save anything, for example inside a container. Give the connection on the command line instead of a profile:
gritpack auth status --hub packages.example.com \
--cert client.pem --key client-key.pem --ca company-ca.pem
Each flag has an environment variable (GRITPACK_SERVER, GRITPACK_CERT,
GRITPACK_KEY, GRITPACK_CA). Give all four, or give --hub alone: then
Gritpack looks in your credentials directory and uses the one login there that
has not expired, and refuses if there are none or several.
You cannot mix the two ways. A profile and an explicit connection together is an error, so a command never runs half on one identity and half on another:
$ gritpack auth status --profile team --hub packages.example.com
invalid package connection: --profile cannot be combined with explicit --hub/--cert/--key/--ca
Saving a certificate you already have
Some organisations issue client certificates themselves, and some situations
leave you with credential files but no profile. gritpack auth import saves
them as a profile without enrolling again:
$ gritpack auth import team --hub packages.example.com --cert client.pem --key client-key.pem --ca server-ca.pem --default
saved profile team in ~/.frogfish/gritpack/config.toml
--default makes it the default straight away. The profile records the paths
of the files you named; Gritpack does not copy them, so keep them where they
are. Profile names are lowercase.
Moving a credential
gritpack auth migrate moves a login's credential to another store and updates
the profile:
gritpack auth migrate --profile work --store file
The stores are the ones login offers: file, keychain (macOS only) and
run. Moving to the store a login already uses changes nothing and says so:
$ gritpack auth migrate --store file --profile cal
credential unchanged profile=cal provider=file
Asking for the Keychain anywhere but a Mac is refused before anything moves:
$ gritpack auth migrate --store keychain --profile cal
invalid package connection: the keychain credential provider is available only on macOS
The usual reason to migrate is a Mac you reach over SSH, where the Keychain is
locked: run gritpack auth migrate --store file once in the Mac's own
Terminal, and the login works from SSH sessions afterwards.
Logging out
gritpack auth logout revokes a login's credential on the hub and then removes
the profile and the private key from your computer:
$ gritpack auth logout --profile cal --yes
logged out profile=cal revoked=true local_removed=true
Without --profile it logs out of the default login. On a terminal it asks
before it does anything; --yes (or -y) answers for it. Without a terminal
and without --yes, Gritpack 1.2.63 goes ahead with a warning, and says that
from 1.4.0 it will refuse instead, so add --yes to scripts now.
If the hub cannot be reached, or the account is already gone, --local-only
forgets the login on this computer without contacting the hub. The credential
then stays valid on the hub until it expires, so revoke it from another login
if the computer was not yours.
Revoking a credential
One account can hold several credentials: your laptop, your desktop, a build machine. Each can be revoked on its own, from any of your other logins:
$ gritpack auth revoke 01a1e866-621f-7293-8d9b-2cf27c02c019
revoked credential=01a1e866-621f-7293-8d9b-2cf27c02c019 account=01a1e865-dc86-7153-9bdf-ef2283d4dcab
The ID is the one gritpack auth status prints. This is what you do when a
laptop is lost: from another computer, list your credentials with
auth status, recognise the lost machine's by its issue date, and revoke it.
The account, its scopes and its packages are untouched. Revoking a credential
that is already revoked succeeds quietly, so it is safe to repeat.
You can only revoke your own account's credentials:
$ gritpack auth revoke 01a1e865-fa11-7663-8550-8c4d87a45daa --profile cal
the hub answered HTTP 403: credential is not authorized
An administrator can suspend a whole account instead; that is in Administering a hub.
Several hubs at once
When you have a login for a private hub, Gritpack asks that hub first for the
packages your projects need, and falls back to the public hub only when the
private hub says a name does not exist. A login for the public hub only matters
if you publish there. Hubs and sources explains the
order and how --from overrides it for one command.
Administrator connections are kept apart from all of this, in their own file
and with their own gritpack admin profile commands, so an everyday command
never runs with administrator rights by accident. See
Administering a hub.
What just happened
- Each login is a profile: a name, a hub, and a pointer to a credential.
auth listandauth useshow and choose the default;--profileandGRITPACK_PROFILEchoose for one command or session.auth statuschecks a login with the hub and lists your credentials.auth import,auth migrate,auth logoutandauth revokesave, move, retire and cut off credentials, each without exposing a secret.
You can stop here
If you have your logins sorted out and know how to revoke a lost one, you have everything an everyday user needs from accounts.
Next
- Names, scopes and owners: who may publish which names, and how to claim a scope.
- Optional: Continuous integration, for giving a build job a login of its own.