Artisan commands¶
Handover adds these commands to Laravel's php artisan.
Executing commands in containers
If you're using a container you need to execute the command inside of the container.
For example, if you're using Docker you must prefix the command with docker exec and specify the container name. Here's an example where we assume that the container is handover:
docker exec -it --user www-data handover COMMAND [ARGUMENTS...]
| Command | Purpose |
|---|---|
groups:add-admin CID |
Add a member to the System Administrators group |
key:get |
Print the current application key |
member:data |
Fetch fresh member data from VATSIM Connect |
passport:client:delete |
Revoke an OAuth client and all its tokens |
reset:acceptedprivacy |
Make every member accept the Data Protection Policy again |
signing-keys:activate KID |
Make a staged signing key the active key |
signing-keys:generate |
Create a staged signing key |
signing-keys:import |
Import the Passport signing key, or create the first key |
signing-keys:list |
List the signing keys and their states |
signing-keys:remove KID |
Remove a retired signing key |
signing-keys:revoke KID |
Remove a signing key immediately |
groups:add-admin¶
php artisan groups:add-admin 1234567
Adds the member with the given CID to the group with the slug system-administrators.
If the group does not exist, the command creates it as an admin group.
The member must have logged in to Handover once.
The command fails if a group with that slug exists but is not an admin group. Fix that group by hand first.
key:get¶
Prints the application key, so you can set it as APP_KEY. See installation.
member:data¶
Updates every member who has VATSIM Connect tokens stored. The scheduler runs it daily, see background jobs.
passport:client:delete¶
Asks for a client ID and a confirmation. It then revokes the client, its access tokens and its refresh tokens. You can also delete clients in the admin pages.
reset:acceptedprivacy¶
Marks every member as not having accepted the Data Protection Policy. See updating the policy.
Signing key commands¶
These commands manage the keys that sign access tokens. For when to run them, see signing keys.
The keys live in /app/storage/oauth-keys:
<kid>.keyholds one private key. Only the user that runs Handover can read it.keys.jsonrecords the state of each key, when it entered that state, and whether it was imported.
The kid is the RFC 7638 thumbprint of the public key.
Keys use RS256.
signing-keys:generate¶
php artisan signing-keys:generate
Creates a 2048-bit RSA key in the staged state and prints its kid.
Handover publishes the key but does not sign with it.
signing-keys:activate¶
php artisan signing-keys:activate KID
Makes a staged key the active key and retires the old active key.
The command refuses until the key has been staged for one hour. --force skips the wait.
signing-keys:remove¶
php artisan signing-keys:remove KID
Deletes a retired key and stops publishing it.
The command refuses until the key has been retired for two hours. --force skips the wait.
signing-keys:revoke¶
php artisan signing-keys:revoke KID
Deletes a key in any state, immediately. Tokens it signed stop working. If the key was active, the command creates and activates a new key, with no staging.
signing-keys:import¶
php artisan signing-keys:import
Creates or imports the first key. The container runs it on every start, and a migration runs it once. If the key store already holds keys, the command does nothing. Otherwise it does one of the following:
- If
PASSPORT_PRIVATE_KEYis set, it imports that key as the active key. - If
/app/storage/oauth-private.keyexists, it imports that key as the active key, then deletesoauth-private.keyandoauth-public.key. - Otherwise, it creates a new key and activates it.
An imported key keeps its size.
Handover ignores PASSPORT_PRIVATE_KEY and PASSPORT_PUBLIC_KEY after the import.
The command prints a warning while PASSPORT_PRIVATE_KEY is still set.
signing-keys:list¶
php artisan signing-keys:list
Lists each key with its kid, its state, the time it entered that state, and whether it was imported.
Passport commands¶
Laravel Passport provides these commands. Handover uses them as follows.
| Command | Purpose |
|---|---|
passport:client |
Create an OAuth client, see OAuth clients |
passport:keys |
Not used. Handover ignores the keys it creates. Use the signing key commands instead |
passport:hash |
Hash stored client secrets, needed once when upgrading to 4.0.0 |
passport:purge |
Remove revoked and expired tokens. The scheduler runs it daily |