Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

S153 Jira Cloud docs #416

Merged
merged 5 commits into from
Nov 6, 2024
Merged

S153 Jira Cloud docs #416

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2f7bd0c
Update Jira Cloud docs and TODO
davidfq Jul 10, 2023
82daef1
Reorganize docs @aperez-worklytics CR
davidfq Jul 12, 2023
41d6492
Merge branch 'rc-v0.4.46' into S153-jira-cloud-docs-tool-ref
davidfq Jan 31, 2024
8098c0c
Update docs
davidfq Jan 31, 2024
427c2ec
Merge branch 'rc-v0.5.0' into S153-jira-cloud-docs-tool-ref
eschultink Nov 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 58 additions & 35 deletions docs/sources/atlassian/jira-cloud.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,47 +19,55 @@ And following granular scopes:

## Setup Instructions

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

2. Then click "Authorize" and "Add", adding `http://localhost` as callback URI. It can be any URL
that matches the settings.
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`

3. Now navigate to "Permissions" and click on "Add" for Jira. Once added, click on "Configure".
Add 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`
And these from "Granular Scopes":
- `read:group:jira`
- `read:avatar:jira`
- `read:user:jira`

4. Once Configured, go to "Settings" and copy the "Client Id" and "Secret". You will use these to
obtain an OAuth `refresh_token`.
Then repeat the same but for "User Identity API", adding the following scope:
- `read:account`

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:
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, or you could use our
[Psoxy OAuth setup tool](#worklytics-psoxy-oauth-setup-tool).

4. Once Configured, 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:
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...`
`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.
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.
**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:
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"}'`
`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:
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.
- `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.
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.

### Worklytics Psoxy OAuth setup tool

Assuming you've created a Jira Cloud OAuth 2.0 (3LO) integration as described above, from the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. 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.

  2. 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

third step of the "manual configuration", you can use our
[Psoxy OAuth setup tool](https://github.com/Worklytics/psoxy-oauth-setup-tool) to obtain the tokens.

Once you've installed and run the tool, you will get a Callback URI like this:
`http://localhost:9000/psoxy-setup-callback` (instead of just `http://localhost`) that you can
use in the "Authorization" section of the Developer Console. The tool is interactive, and you
will be prompted to confirm that you've registered the Callback URI before continuing.

Then, you will be prompted to enter the "Client ID" and "Secret" from the Developer Console, and
the tool will open a web browser to complete the authentication and authorization flows. After that,
it will print the necessary values to complete the configuration (as in step 9 above).
94 changes: 59 additions & 35 deletions infra/modules/worklytics-connector-specs/main.tf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -598,47 +598,56 @@ And following granular scopes:
- read:avatar:jira: for retrieving group members

## Setup Instructions
1. Go to https://developer.atlassian.com/console/myapps/ and click on "Create"

2. Then click "Authorize" and "Add", adding `http://localhost` as callback URI. It can be any URL
that matches the settings.
### Manual configuration
1. Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and
click on "Create" (OAuth 2.0 integration).

3. Now navigate to "Permissions" and click on "Add" for Jira. Once added, click on "Configure".
Add 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`
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`

4. Once Configured, go to "Settings" and copy the "Client Id" and "Secret". You will use these to
obtain an OAuth `refresh_token`.
And these from "Granular Scopes":
- `read:group:jira`
- `read:avatar:jira`
- `read:user:jira`

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:
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, or you could use our
[Psoxy OAuth setup tool](#worklytics-psoxy-oauth-setup-tool).

4. Once Configured, 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:
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...`
`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.
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.
**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:
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"}'`
`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:
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 @@ -651,10 +660,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.
- `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 @@ -675,9 +684,24 @@ 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.
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.

### Worklytics Psoxy OAuth setup tool

Assuming you've created a Jira Cloud OAuth 2.0 (3LO) integration as described above, from the
third step of the "manual configuration", you can use our
[Psoxy OAuth setup tool](https://github.com/Worklytics/psoxy-oauth-setup-tool) to obtain the tokens.

Once you've installed and run the tool, you will get a Callback URI like this:
`http://localhost:9000/psoxy-setup-callback` (instead of just `http://localhost`) that you can
use in the "Authorization" section of the Developer Console. The tool is interactive, and you
will be prompted to confirm that you've registered the Callback URI before continuing.

Then, you will be prompted to enter the "Client ID" and "Secret" from the Developer Console, and
the tool will open a web browser to complete the authentication and authorization flows. After that,
it will print the necessary values to complete the configuration (as in step 9 above).
EOT
}
}
Expand Down