apollo/enbas
1
0
Fork 0
Code Issues 4 Pull requests Projects Activity Actions

checkpoint: continuiung writing the getting started guide

Browse source
This commit is contained in:
Dan Anglin 2024-06-29 20:33:50 +01:00
parent 0509290e15
commit a00e34f7c3
Signed by: dananglin
GPG key ID: 0C1D44CFBEE68638
2 changed files with 69 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
docs/getting-started.md
View file

@ -21,10 +21,76 @@ Alternatively you can use the `--config-dir` global flag to specify your configu
## Generate your configuration file
Run `enbas init` to generate your configuration file.
Run the `init` command to generate your configuration file.
View configuration file. JSON file, mostly blank slate for you to configure to your preferences. Configuration documentation coming soon. For this getting started guide you may want to specify your preferred browser to open the link to your instance's login page. Can leave blank if you prefer to open the link manually.
```bash
enbas init
```
Use the `--config-dir` flag if you want to generate it in a specific directory
```bash
enbas --config-dir config init
```
You should now see a file called `config.json` in your configuration directory.
Feel free to edit the file to your preferences (configuration documentation coming soon).
For this 'Getting Started' guide you may want to specify your preferred browser in the configuration to allow Enbas to open the link to your instance's authorisation page. If you prefer to open the link manually then you can leave it blank.
## Log into your GoToSocial account
Enbas uses the Oauth2 authentication flow to log into your account on GoToSocial.
```
[WARNING]
As of writing GoToSocial does not currently support scoped authorization tokens so even if we request read-only
tokens, the application will be able to perform any actions within the limitations of your account
(including admin actions if you are an admin).
You can read more about this https://docs.gotosocial.org/en/latest/api/authentication/[here].
```
Follow the below steps to log into your account:
1. Run the `login` command specifying the instance that you want to log into.
```
enbas login --instance gts.enbas-demo.private
```
2. Enbas will send a registration request to your instance and receive a new client ID and secret that it needs for authentication.
3. Enbas will then generate a link to the consent form for you to access in your browser and print it to your terminal screen along with a message explaining that you need to obtain the `out-of-band` token to continue.
The link will open in a tab in your preferred browser if you've specified it in your configuration, otherwise you can manually open it yourself.
If the browser tab doesn't open for you as expected you can still manually open it yourself.
4. Once you've signed into GoToSocial on your browser, you will be informed that Enbas would like to perform actions on your behalf.
If you're happy with this then click on the `Allow` button.
![A screenshot of the consent form](/assets/images/consent_form.png "Consent Form")
5. The `out-of-band` token from your instance will be displayed to you in your browser. Copy it and return to your terminal.
6. Paste the token into the prompt and press `ENTER`.
Enbas will then exchange the token for an access token which will be used to authentication to your instance on your behalf.
7. Enbas will then verify the access token, save the credentials to the `credentials.json` file in your configuration directory,
and inform you that you have successfully logged into your account.
```
$ enbas login --instance gotosocial-01.social.example
You'll need to sign into your GoToSocial's consent page in order to generate the out-of-band token to continue with
the application's login process. Your browser may have opened the link to the consent page already. If not, please
copy and paste the link below to your browser:
https://gotosocial-01.social.example/oauth/authorize?client_id=01RHK48N1KH9SFNH2VVZR414BJ&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code
Once you have the code please copy and paste it below.
Out-of-band token: ZGJKNDA2YWMTNGEYMS0ZZJLJLWJHNDITM2IZYJJLNJM3YJBK
Successfully logged into bobby@gotosocial-01.social.example
```
## View your account information

2
internal/executor/login.go
View file

@ -100,7 +100,7 @@ func (l *LoginExecutor) Execute() error {
return fmt.Errorf("unable to save the authentication details: %w", err)
}
l.printer.PrintSuccess("Successfully logged into " + loginName + ".")
l.printer.PrintSuccess("You have successfully logged as " + loginName + ".")
return nil
}