diff --git a/docs/tfcli/getting_started.md b/docs/tfcli/getting_started.md index f92a1fc..1731440 100644 --- a/docs/tfcli/getting_started.md +++ b/docs/tfcli/getting_started.md @@ -24,4 +24,68 @@ The first step in setting up your `trifid-api` account is creating it! This, lik - An email address (you don't need access to the mailbox though) - Access to the `trifid-api` server logs to get the login token -- `tfcli` installed \ No newline at end of file +- `tfcli` installed + +In order to create an account, use the 'create account' tfcli command: + +```shell +tfcli account create --email [INSERT_YOUR_EMAIL_HERE] +``` + +At this point, you'll need to check your `trifid-api` server logs. Look for a log message that looks like `sent magic link [long-text-here that starts with 'ml-']`. +You'll need to grab the long string of characters starting with `ml-` and going to the end of the line. It'll look something like `ml-NrrnaEm7N-6XqbDUweoNuwchI7SBCZwJQVPUDSS7T1g`. + +This token only remains valid for 10 minutes, so you'll need to move relatively quickly. If the token expires, don't worry - use the `login` command as described at the end of this section to get a new token. + +Once you have your magic-link token, authenticate and create your session token: + +```shell +tfcli account magic-link --magic-link-token [insert-long-string-of-characters-you-got-earlier] +``` + +This will get a special token from `trifid-api` that allows you to modify only your 2fa settings, but not any hosts, networks, or roles. `tfcli` automatically saves this token to your computer - you don't need to worry about it. + +After this, you'll need to set up 2fa before you can do any other management tasks. + +In addition, approximately once every year, your session token will expire. You might also want to use multiple computers. To do this, use the `login` feature instead of `signup`: + +```shell +tfcli account login --email [INSERT_YOUR_EMAIL_HERE] +``` + +You can then use the `magic-link` command exactly as above to renew your session token or log in on a new PC. + +## Setting up 2FA + +`trifid-api` enforces two-factor authentication on all accounts. You will be unable to perform any management tasks until you complete 2fa setup. +You'll need: + +- `tfcli` installed +- A valid account and session token as created in the previous step +- A TOTP-compatible authenticator like Authy or Google Authenticator + +After you've logged in, run the following command to get your TOTP setup code: + +```shell +tfcli account mfa-setup +``` + +This command will give you instructions on how to complete TOTP setup. Follow the directions given. Afterwards, an auth token will be issued by trifid-api +and saved to your computer that gives you full control over your `trifid-api` resources such as networks, hosts, and roles. + +This token expires after about 10 minutes. When it expires, you'll need to generate a new one by entering the code on your TOTP authenticator that you set up earlier into the following command: + +```shell +tfcli account mfa --code [CODE_IN_AUTHENTICATOR_APP] +``` + +This will issue another token that is valid for another 10 minutes. + +### Troubleshooting 'Unauthorized' messages + +If you ever see error messages about being 'unauthorized', it most likely means your authentication token has expired, and you need to run `tfcli account mfa` again. If you try that and it is successful, but you still see errors, or if `tfcli account mfa` *itself* gives you an "Unauthorized error", it means your session token has expired. Refer to the end of 'Creating your Account' above to learn how to log in again. +After getting a new session token you will always need to get a new TOTP token. + +If, even after renewing your session and authentication tokens, you are still getting 'Unauthorized', it is likely an issue with your server setup. Check the trifid-api server logs or the logs of your proxy and ensure that there are no additional setup issues. + +If you're still having issues, shoot a message to our mailing list on the [homepage](index.md) of this documentation and we would be glad to help you out. \ No newline at end of file