From c6943b5aa0af1063f00a001104be9b8b95a2c79e Mon Sep 17 00:00:00 2001 From: Dan Anglin Date: Sat, 29 Jun 2024 22:41:42 +0100 Subject: [PATCH] checkpoint: done for today --- README.asciidoc | 56 +--------------------------------- assets/images/consent_form.png | 4 +-- docs/getting-started.md | 46 +++++++++++++++++----------- 3 files changed, 31 insertions(+), 75 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 6f4ad5d..32d4631 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -46,61 +46,7 @@ the current working directory. === Log into your GoToSocial account -Enbas uses the Oauth2 authentication flow to log into your account on GoToSocial. -This process requires your input to give consent to allow Enbas access to your account. - -[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]. -==== - -The login flow is completed using the following steps: - -1. You start by using the `login` command specifying the instance that you want to log into. -+ -[source,console] ----- -enbas login --instance gotosocial-01.social.example ----- - -2. The application will register itself and the GoToSocial server will create a new client ID and secret that the app needs for authentication. - -3. The application will then generate a link to the consent form for you to access in your browser. -This link will be printed on your terminal screen along with a message explaining that you need to obtain the `out-of-band` token to continue. -If you have the `BROWSER` environment variable set or if you're using Linux, the link will open in a new browser tab for you to sign into your account. -If the browser tab doesn't open, you can manually copy and paste the link in your favourite browser. - -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. -+ -image::assets/images/consent_form.png[A screenshot of the consent form] - -5. The `out-of-band` token will be printed for you at this point. 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 the -GoToSocial server on your behalf. -Enbas will then verify the access token, save the credentials to the `credentials.json` file in your configuration directory, -and confirm that you have successfully logged into your account. -+ -[source,console] ----- -$ 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 ----- +(Moved) === Common actions diff --git a/assets/images/consent_form.png b/assets/images/consent_form.png index 1b0948c..f1e8a13 100644 --- a/assets/images/consent_form.png +++ b/assets/images/consent_form.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:77cec529dc6133cd3b4fd219a99820aba24e4ecf99e1f6db41ada2bebc1bc1c2 -size 54240 +oid sha256:02def288f4a81dfbe2afa3cd133f32328a659e668999d0f123564a3e7e432bcf +size 40151 diff --git a/docs/getting-started.md b/docs/getting-started.md index d8a41fd..392eb51 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,6 +3,7 @@ ## Summary In this guide we are going to log into an account on a private GoToSocial server. + Follow along to log into your own account. ## Your configuration directory @@ -36,7 +37,9 @@ 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. +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 @@ -58,39 +61,46 @@ Follow the below steps to log into your account: 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. +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. +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. + 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. +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. +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. + Enbas will then exchange the token for an access token which will be used to authenticate + 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. +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. + +### Example login flow ``` -$ enbas login --instance gotosocial-01.social.example +$ enbas login --instance gts.enbas-demo.private -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: +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 +https://gts.enbas-demo.private/oauth/authorize?client_id=019RD0WVA903F773T5F9D9EYHP&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 +Out-of-band token: ZDRKOTE0NMUTZGVHZC0ZNJVJLWJINTMTMWE1M2UWYWFHOTQY +✔ You have successfully logged as percy@gts.enbas-demo.private. ``` ## View your account information