S153 Jira Cloud docs

[davidfq]

⚠️ rc-v0.4.29 as base to compare, but this needs an initial release of: https://github.com/Worklytics/psoxy-oauth-setup-tool

Fixes

.

Features

• Updates Jira Cloud docs and TODO file: references the OAuth helper tool

Change implications

• dependencies added/changed? no

[aperez-worklytics]

Some suggestion about order and content of the doc steps

[aperez-worklytics]

I think it could be better if we distribute the doc in following sections instead and in this order:

• App configuration: where we explain how to setup the Jira app covering following steps:

1. Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and
   click on "Create" (OAuth 2.0 integration).

2. Now navigate to "Permissions" and click on "Add" for Jira. Once added, click on "Configure".
   Add the following scopes as part of "Classic Scopes":
   - `read:jira-user`
   - `read:jira-work`

   And these from "Granular Scopes":
   - `read:group:jira`
   - `read:avatar:jira`
   - `read:user:jira`

   Then repeat the same but for "User Identity API", adding the following scope:
   - `read:account`

3. Go to the "Authorization" section and add an OAuth 2.0 (3LO) authorization type: click on "Add"
   and you will be prompted to provide a "Callback URI". At this point, you could add
   `http://localhost` as value and follow the rest of steps on this guide, 

• Worklytics Psoxy OAuth setup tool: instrutions for using the tool with jira
• Manual steps:

go to "Settings" and copy the "Client ID" and "Secret". You will use these to
   obtain an OAuth `refresh_token`.

5. Build an OAuth authorization endpoint URL by copying the value for "Client Id" obtained in the
   previous step into the URL below. Then open the result in a web browser:

   `https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=<CLIENT ID>&scope=offline_access%20read:group:jira%20read:avatar:jira%20read:user:jira%20read:account%20read:jira-user%20read:jira-work&redirect_uri=http://localhost&state=YOUR_USER_BOUND_VALUE&response_type=code&prompt=consent`

6. Choose a site in your Jira workspace to allow access for this application and click "Accept".
   As the callback does not exist, you will see an error. But in the URL of your browser you will
   see something like this as URL:

   `http://localhost/?state=YOUR_USER_BOUND_VALUE&code=eyJhbGc...`

   Copy the value of the `code` parameter from that URI. It is the "authorization code" required
   for next step.

   **NOTE** This "Authorization Code" is single-use; if it expires or is used, you will need to
   obtain a new code by  again pasting the authorization URL in the browser.

7. Now, replace the values in following URL and run it from command line in your terminal. Replace
   `YOUR_AUTHENTICATION_CODE`, `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` in the placeholders:

   `curl --request POST --url 'https://auth.atlassian.com/oauth/token' --header 'Content-Type: application/json' --data '{"grant_type": "authorization_code","client_id": "YOUR_CLIENT_ID","client_secret": "YOUR_CLIENT_SECRET", "code": "YOUR_AUTHENTICATION_CODE", "redirect_uri": "http://localhost"}'`

8. After running that command, if successful you will see a
   [JSON response](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#2--exchange-authorization-code-for-access-token) like this:

```json
{
Expand All
	@@ -72,10 +80,10 @@ And following granular scopes:

9. Set the following variables in AWS System Manager parameters store / GCP Cloud Secrets (if default implementation):

   • PSOXY_JIRA_CLOUD_ACCESS_TOKEN secret variable with value of access_token received in previous response
   • PSOXY_JIRA_CLOUD_REFRESH_TOKEN secret variable with value of refresh_token received in previous response
   • PSOXY_JIRA_CLOUD_CLIENT_ID with Client Id value.
   • PSOXY_JIRA_CLOUD_CLIENT_SECRET with Client Secret value.

10. Optional, obtain the "Cloud ID" of your Jira instance. Use the following command, with the
    access_token obtained in the previous step in place of <ACCESS_TOKEN> below:
    Expand All
    @@ -96,6 +104,21 @@ And following granular scopes:
    ]

Add the `id` value from that JSON response as the value of the `jira_cloud_id` variable in the
`terraform.tfvars` file of your Terraform configuration. This will generate all the test URLs with
a proper value

The idea would be to have as first option the tool and if not, using the manual steps