# Setting up Jira for connecting to Amazon Q Business
Before you connect Jira to Amazon Q Business, you need to create and retrieve the Jira credentials you will use to connect Jira to Amazon Q. You will also need to add any permissions needed by Jira to connect to Amazon Q.
The following sections give you an overview of how to configure Jira to connect to Amazon Q using either basic authentication or OAuth 2.0 authentication.
**Topics**
+ [Basic authentication](jira-credentials-basic.md)
+ [OAuth 2.0 authentication](jira-credentials-oauth.md)
+ [How Amazon Q works with Jira access and refresh tokens](jira-credentials-notes.md)
+ [Checking Jira connectivity](jira-connection-check.md)
# Basic authentication
You can connect Amazon Q to Jira using basic authentication credentials. The following procedure gives you an overview of how to configure Jira to connect to Amazon Q using basic authentication.
**Configuring Jira basic authentication for Amazon Q**
1. Log in to your account from [Jira](https://jira.atlassian.com/). Note the username you logged in with. You will need this later to connect to Amazon Q.
1. From your Jira home page, copy the Jira URL from your Jira browser URL. For example: *https://example.atlassian.net*. You will need this later to connect to Amazon Q.
1. Then, go to [Security]( https://id.atlassian.com/manage-profile/security/api-tokens.) page in Jira.
1. From the **API tokens** page, select **Create API token**.
1. In the **Create an API token** dialog box that opens, for **Label**, add a name for your API token. Then, select **Create**.
1. From the **Your new API token** dialog box, copy the API token and save it in a text editor of your choice. You can't retrieve the API token once you close the dialog box.
1. Select **Close**.
You now have the username, Jira URL, and Jira API token you need to connect to Amazon Q with basic authentication.
For more information, see [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) in Atlassian Support.
# OAuth 2.0 authentication
You can connect Amazon Q to Jira using OAuth 2.0 authentication credentials. The following procedures give you an overview of how to configure Jira to connect to Amazon Q using OAuth 2.0 authentication.
**Topics**
+ [Step 1: Retrieving username and Jira URL](#jira-credentials-url)
+ [Step 2: Configuring an OAuth 2.0 app integration](#jira-credentials-oauth-app)
+ [Step 3: Retrieving Jira client ID and client Secret](#jira-credentials-id-secret)
+ [Step 4: Generating a Jira access token](#jira-credentials-access)
+ [Step 5: Generating a Jira refresh token](#jira-credentials-refresh)
+ [Step 6: Generating a new Jira access token using a refresh token](#jira-credentials-refresh-access)
## Step 1: Retrieving username and Jira URL
To connect Jira to Amazon Q, you need your Jira username and your Jira URL. The following procedure shows you how to retrieve these.
**Retrieving username and Jira URL**
1. Log in to your account from the [Jira](https://jira.atlassian.com/). Note the username you logged in with. You will need this later to connect to Amazon Q.
1. From your Jira home page, note your Jira URL from your Jira browser URL. For example: *https://example.atlassian.net*. You will need this later to both configure your OAuth 2.0 token and connect to Amazon Q.
## Step 2: Configuring an OAuth 2.0 app integration
To connect Jira to Amazon Q using OAuth 2.0 authentication, you need to create a Jira OAuth 2.0 app with the necessary permissions. The following procedure shows you how to create this.
**Configuring an OAuth 2.0 app integration**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Select the profile icon from the top-right corner. Then, from the dropdown menu that opens, select **Developer Console**.
1. From the **Welcome** page, select **Create** and then select **OAuth 2.0 integration**.
1. On the **Create a new OAuth 2.0 (3LO) integration** page, for **Name**, enter a name for the OAuth 2.0 application you are creating. Then, select the **I agree to be bound by Atlassian's developer terms** checkbox, and select **Create**.
The console will display a summary page outlining the details of the OAuth 2.0 app created.
1. From the left navigation menu, choose **Authorization**.
1. From the **Authorization** page, choose **Add** to add **OAuth 2.0 (3LO)** to your app.
1. On the **OAuth 2.0 authorization code grants (3LO) for apps**, enter the Jira URL you copied as the **Callback URL** and then choose **Save changes**.
1. From the **Authorization URL generator** section that appears, choose **Add APIs** to add APIs to your app. This will redirect you to the **Permissions** page.
1. On the **Permissions** page, for **Scopes**, navigate to **User Identity API**. Select **Add**, and then select **Configure**.
1. On the **User Identity API** page, choose **Edit Scopes**, and the add the following `read` scopes:
+ **`read:me`** – View active user profile
+ **`read:account`** – View user profiles
Then, select **Save**.
1. Return to the **Permissions** page. From **Scopes**, navigate to **Jira API**. Select **Add**, and then select **Configure**.
1. On the **Jira API** page, you need to add scopes from both the Classic scopes and Granular scopes sections.
Choose **Edit Scopes**, and add the following scopes:
**In the Classic scopes section, add:**
+ **`read:jira-user`** – View active user profiles
+ **`read:jira-work`** – View Jira issue data
+ **`manage:jira-configuration`** – Manage Jira global settings
**In the Granular scopes section, add:**
+ **`read:application-role:jira`** – View application roles
Select **Save**.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) and [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/) in Atlassian Developer.
## Step 3: Retrieving Jira client ID and client Secret
To connect Jira to Amazon Q using OAuth 2.0 authentication, you need to provide a Jira client ID and client secret. The following procedure shows you how to retrieve these.
**Note**
You must create an OAuth 2.0 app before you can retrieve the client ID and client secret. See [Configuring an OAuth 2.0 app integration](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-credentials.html#jira-credentials-oauth-app) for more details.
**Retrieving Jira client ID and client secret**
+ From the left navigation menu, choose **Settings**. Then, scroll down to **Authentication details** section and copy and save the following in a text editor of your choice:
+ Client ID – You will enter this as **App key** in the Amazon Q console.
+ Client Secret – You will enter this as **App secret** in the Amazon Q console.
You will need these to generate your Jira OAuth 2.0 token and also to connect Amazon Q to Jira.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) and [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/) in Atlassian Developer.
## Step 4: Generating a Jira access token
To connect Jira to Amazon Q, you need to generate an access token. The following procedure outlines how to generate an access token in Jira.
**Generating your Jira access token**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Open the OAuth 2.0 app you want to generate a refresh token for.
1. From the left navigation menu, choose **Authorization** again. Then, for **OAuth 2.0 (3LO)**, choose **Configure**.
1. From the **Authorization** page, from **Authorization URL generator**, from **Granular Jira API authorization URL**, copy the URL and save it in a text editor of your choice.
The URL is of the following format:
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. In the saved authorization URL, update the `state=${YOUR_USER_BOUND_VALUE}` parameter value to any text of your choice. For example, `state=`*sample\$1text*.
For more information, see [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-) in Atlassian Support.
1. Open a web browser of your choice. Then, paste the authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select **Accept**.
You will be returned to your Jira home page.
1. Copy the URL of the Jira home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Jira access token. The whole section after `code=` is the authorization code.
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a Jira access token. Use the following cURL command to do so:
```
curl --location '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": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_CALLBACK_URL"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return an `access-token`. Copy the access token and save it using a text editor of your choice. You will need it to connect Jira to Amazon Q.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) in Atlassian Developer.
## Step 5: Generating a Jira refresh token
The access token you use to connect Jira to Amazon Q using OAuth 2.0 authentication expires after 1 hour. When it does, you can either repeat the whole authorization process and generate a new access token. Or, you can choose to generate a refresh token. You can use the refresh token to regenerate a new access token when an existing access token expires.
To do this, you add a `%20offline_access` parameter to the end of the `scope` value in the authorization URL you used to generate your access token. The following procedure shows you how to generate a refresh token.
**Generating an Jira refresh token**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Open the OAuth 2.0 app you want to generate a refresh token for.
1. From the left navigation menu, choose **Authorization** again. Then, for **OAuth 2.0 (3LO)**, choose **Configure**.
1. From the **Authorization** page, from **Authorization URL generator**, from **Granular Jira API authorization URL**, copy the URL and save it in a text editor of your choice.
1. In the saved authorization URL, update the `state=${YOUR_USER_BOUND_VALUE}` parameter value to any text of your choice. For example, `state=`*sample\$1text*.
For more information, see [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-) in Atlassian Support.
1. Then, add the following text at the end of the `scope` value in your authorization URL: `%20offline_access` and copy it. For example:
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO%20offline_access
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. Open a web browser of your choice and paste the modified authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select **Accept**.
You will be returned to the Jira console.
1. Copy the URL of the Jira home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Jira refresh token. The whole section after `code=` is the authorization code.
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a Jira access token. Use the following cURL command to do so:
```
curl --location '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": "AUTHORIZATION CODE",
"redirect_uri": "YOUR CALLBACK URL"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return an `refresh-token`.
Copy the refresh token and save it using a text editor of your choice. You will need it to connect Jira to Amazon Q.
For more information, see [Implementing a Refresh Token Flow](https://developer.atlassian.com/cloud/oauth/getting-started/refresh-tokens/) in Atlassian Developer.
## Step 6: Generating a new Jira access token using a refresh token
You can use the refresh token you generated to create a new access token-refresh token pair when an existing access token expires. The following procedure shows you how to generate a refresh token.
**Generating an Jira access token-refresh token pair**
1. Copy the refresh token you generated following the steps in [Step 5: Generating a Jira refresh token](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-credentials.html#jira-credentials-refresh).
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a new Jira access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR REFRESH TOKEN"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return a new access token-refresh token pair in the following format:
```
{
"access_token": "string,
"expires_in": "expiry time of access_token in second",
"scope": "string",
"refresh_token": "string"
}
```
For more information, see [Implementing a Refresh Token Flow](https://developer.atlassian.com/cloud/oauth/getting-started/refresh-tokens/) and [How do I get a new access token, if my access token expires or is revoked? ](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#how-do-i-get-a-new-access-token--if-my-access-token-expires-or-is-revoked-)in Atlassian Developer.
# How Amazon Q works with Jira access and refresh tokens
The following are important points to note about using Jira access and refresh tokens with Amazon Q:
+ If a Jira access token-refresh token pair you use to connect to Amazon Q are expired or invalid, the Amazon Q sync process fails. If this happens, you need to generate and provide a new pair of tokens.
+ If your access token is valid but you have an invalid refresh token, Amazon Q will sync data until the access token expires (up to 1 hour). After the access token expires, you won't be able to re-generate an access token-refresh token pair using the expired refresh token. When both access token and refresh token expire, the Amazon Q Jira data source connector stops syncing.
+ If an access token expires during the Jira connector sync process, the connector internally regenerates a new pair of tokens using the existing refresh token (if the provided refresh token is valid). After regenerating the new pair of tokens, the old pair is invalidated by Jira and can't be re-used. To sync documents again after the connector auto-regenerates tokens, you must provide a new access token-refresh token pair.
+ If you use OAuth, select **Rotate secret** if you want Amazon Q to rotate the secret automatically so that you don’t have to manually update the secret every time before you sync.
+ As a best practice, use Jira OAuth and the **Rotate secret** feature for the Amazon Q connector.
# Checking Jira connectivity
Before you sync your Jira data source connector after [configuring it](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-console.html), we recommend you check the connection between Amazon Q Business and Jira. The following are the cURL commands you need to check Jira connectivity.
**Topics**
+ [Checking basic authentication connectivity](#jira-connection-check-basic)
## Checking basic authentication connectivity
To check connectivity for a Jira data source connector using basic authentication, use the following cURL command:
```
curl --location 'https:///wiki/rest/api/user/current'
--header 'Authorization: Basic '
```
If your data source is connected as expected, the JSON response should resemble the following:
```
{
"type": "known",
"accountId": "accountId",
"accountType": "atlassian",
"email": "email",
"publicName": "Administrator",
"profilePicture": {
"path": "/wiki/aa-avatar/",
"width": 48,
"height": 48,
"isDefault": false
},
"displayName": "Administrator",
"isExternalCollaborator": false,
"_expandable": {
"operations": "",
"personalSpace": ""
},
"_links": {
"self": "https:///wiki/rest/api/user?accountId=",
"base": "https:///wiki",
"context": "/wiki"
}
}
```
If your Jira connector is not connected correctly, you will see the following error:
+ CNF-5123: The profile value is invalid. Try again after sometime.
To troubleshoot the issue, check your Jira URL and make sure it's correct.