# Forge Appのインストール

## 概要

Atlassian Forgeアプリでは、外部へのネットワーク通信に対して厳格なセキュリティ制御が適用されます。アプリが通信するすべての外部ドメインは、`manifest.yml` にあらかじめ許可を設定する必要があります。

{% hint style="info" %}
自社環境でのデプロイが必要な理由

Forgeアプリは、お客様ごとに使用するコマンダーAPIのドメインを許可する設定が必要です。そのため、各環境に合わせてアプリを個別にデプロイする必要があります。

この方式により、お客様の環境との接続を分離し、安全に運用できます。
{% endhint %}

## 要件

### Atlassianの要件

* Jira Cloudインスタンスにアクセス可能なAtlassianアカウント
* Jira管理者権限 (アプリのインストールに必要)
* Atlassian Developerアカウント
* Node.js 18以上のインストール
* Forge CLIのインストール: `npm install -g @forge/cli`

### Node.jsのセットアップ (nvmを使用)

Forge CLIの利用には**Node.js 18以上**が必要です。Node.jsのインストールおよびバージョン切り替えには、nvm (Node Version Manager) の使用を推奨します。

#### nvmのインストール

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
```

ターミナルを再起動後、Node.jsをインストール

```bash
nvm install 18
nvm use 18
```

インストールの確認

```bash
node -v
npm -v
```

Node.jsのインストール完了後、Forge CLIをグローバルにインストール

```bash
npm install -g @forge/cli
```

### WSL / Linux環境での要件

デスクトップ環境のないWSLまたはLinux環境では、`forge login` 実行時に認証情報を安全に保存するための追加パッケージが必要です。Forge CLIはOSのキーリングにアクセスするために `libsecret` を使用しますが、ヘッドレス環境のLinuxには標準で含まれていません。

必要なパッケージのインストール

```bash
sudo apt-get install libsecret-1-0 libsecret-1-dev gnome-keyring
```

`forge login` を実行する前に、キーリングデーモンを起動

```bash
eval $(dbus-launch --sh-syntax)
echo '' | gnome-keyring-daemon --unlock --components=secrets
```

{% hint style="info" %}
この設定が必要な理由

Forge CLIはAtlassian APIトークンをOSのシークレットサービスに保存します。macOS (Keychain) およびWindows (Credential Manager) では標準で利用できますが、Linux / WSL環境では `libsecret` (クライアントライブラリ) と `gnome-keyring` (キーリングデーモン) を手動でインストールする必要があります。
{% endhint %}

### Keeperの要件

* Keeperエンタープライズアカウント (コマンダーCLIへのアクセスが可能であること)
* コマンダーCLI バージョン17.1.7以降
* 永続ログインを設定済みのコマンダーCLI
* コマンダーAPIを公開するセキュアトンネル

### 1. ソースコードの入手

#### A. リポジトリのクローン

<https://github.com/Keeper-Security/jira-connector-hub>

#### B. アーカイブのダウンロード

<https://github.com/Keeper-Security/jira-connector-hub/archive/refs/heads/main.zip>

### 2. ドメインの設定

`manifest.yml` を開き、`permissions.external.fetch.backend` セクションに、コマンダーのサービスモード用ドメインを追加します。

```
permissions:
  scopes:
      - read:jira-work
      - write:jira-work
      - storage:app
      - read:jira-user
  external:
      fetch:
        backend:
            # ADD YOUR DOMAIN(S) BELOW
            - address: https://keeper-api.yourcompany.com
            # Or use subdomain wildcard:
            - address: https://*.yourcompany.com
```

{% hint style="warning" %}
manifest.yml末尾にある既存のapp.id行を削除してください。アプリ登録時に新しいIDが自動生成されます。
{% endhint %}

#### ドメインパターンのルール

| パターン             | 許可 | 例                              |
| ---------------- | -- | ------------------------------ |
| 完全一致のドメイン        | 可  | <https://api.company.com>      |
| サブドメインのワイルドカード   | 可  | https\://\*.company.com        |
| パスのワイルドカード       | 不可 | <https://api.company.com/\\>\* |
| すべてのドメイン         | 不可 | https\://\*                    |
| HTTP (HTTPSではない) | 不可 | <http://api.company.com>       |

### 3. アプリケーションのビルド

```
# ルートディレクトリの依存関係をインストール
npm install

# グローバルページUIのビルド
cd static/keeper-ui
npm install
npm run build
cd ../..

# 課題パネルUIのビルド
cd static/keeper-issue-ui
npm install
npm run build
cd ../..
```

### 4. Atlassianへのデプロイ

#### 認証

```
forge login
```

ブラウザが起動するので、画面の案内に従って認証します。

#### アプリの登録

```
forge register
```

プロンプトが表示されたら、アプリ名を入力します (例: Keeper for Jira - YourCompany)。

#### デプロイ

```
forge deploy -e production
```

#### Jiraへのインストール

```
forge install -e production
```

画面の指示に従って以下を行なってください。

1. 製品としてJiraを選択
2. Jiraサイト (例: yourcompany.atlassian.net) を入力
3. インストールを確認

#### アプリへのアクセス許可の付与 (インストール後)

`forge install` でアプリをインストールした後、**\[Jira Settings]** → **\[Apps]** → Keeperに移動します。初回表示時に、アクセス許可を求める画面が表示されます。

<figure><img src="/files/zyRoOiGmk0nxKzazScvy" alt=""><figcaption></figcaption></figure>

**\[Allow access]** をクリックし、必要な権限を付与します。これは、Forgeアプリがご利用のJiraインスタンスと連携することを承認するための一度限りのOAuth同意手順です。

{% hint style="warning" %}
この手順を実施しない場合、Keeperアプリのパネルおよび設定画面は表示されません。また、アプリを初めて利用する各ユーザーは、それぞれ個別にアクセスを許可する必要があります。
{% endhint %}

アプリの所有者以外のユーザーが **\[Allow access]** をクリックした際に、次の画面が表示される場合があります。

<figure><img src="/files/jRTPJl26jyBXK3VnKpEg" alt=""><figcaption></figcaption></figure>

これは、Forgeアプリがまだ共有設定されていないことを示しています。Forgeアプリは、開発モードではデフォルトでアプリ所有者 (`forge register` を実行したユーザー) のみが利用可能となっています。

この問題を解決するには、アプリ所有者が共有を有効化する必要があります。

1. Atlassian Developer Consoleにアクセス
2. **Keeper for Jira**アプリを選択
3. **\[Distribution]** → **\[Sharing]** に移動
4. **\[Share app]** を有効化
5. インストールリンクをコピーし、他のJira管理者またはユーザーに共有

{% hint style="info" %}
プリ所有者以外のユーザーが利用するには、この設定が必須です。\[Share app] を有効にすると、アプリをインストール済みのJiraサイト内のすべてのユーザーがアクセスを許可し、アプリを利用できるようになります。
{% endhint %}

#### 複数サイトへのインストール (任意)

複数のJiraサイトにインストールする場合、または他の管理者によるインストールを許可する場合は、以下の手順を実施します。

1. Atlassian Developer Consoleにアクセス
2. 登録済みのKeeper for Jiraアプリを選択
3. **\[Distribution]** → **\[Sharing]** に移動
4. **\[Share app]** を有効化
5. インストールリンクをコピー
6. リンクを他のJira管理者に共有、または追加のサイトへインストール

### 5. Jiraでの構成

1. **\[Jira settings]** → **\[Apps]** → **\[Keeper]** に移動します。
2. **\[Configuration]** タブで、以下を入力します。
   1. **API URL**: コマンダーAPIのURL (例: <https://keeper-api.yourcompany.com/api/v2>)
   2. **API Key**: コマンダー起動時に表示されるAPIキー
3. **\[Test Connection]** をクリックし、接続を確認します。
4. その後、**\[Save Settings]** をクリックして保存します。

{% hint style="success" %}
任意のJira課題を開き、Keeperパネルが表示されていることを確認します。簡単な操作を実行し、正常に連携できることを確認します。
{% endhint %}

### 6. ユーザーアクセスの構成

アプリのインストールおよび設定完了後、ユーザーが課題画面のKeeperアプリパネルを表示し操作できるよう、Jira側の権限設定が必要となる場合があります。

#### 課題パネルにKeeperアプリのアクションアイコンが表示されない場合

<figure><img src="/files/2fr7EkkmkzWPVzMu4BeL" alt=""><figcaption></figcaption></figure>

この問題は、インストール後に最も多く発生します。

Keeperアプリのアイコン (アプリパネルを開くアイコン) は、**課題編集**権限を持つユーザーにのみ表示されます。これはKeeper固有の制限ではなく、Jiraプラットフォームの仕様です。すべてのアプリパネルに同じ条件が適用されます。

対処手順

1. **\[Project Settings]** → **\[Access]** → **\[Space Permissions]** に移動
2. **歯車アイコン** (編集権限) をクリック
3. **\[Issue Permissions]** セクションで **\[Edit Issue]** を探す
4. サイトの既定ユーザーグループ `jira-users-<your-site-name>` を追加
5. **\[Save]** をクリック

この設定はプロジェクトごとに一度のみ実施します。設定後、対象グループのユーザーは課題画面でKeeperアプリのアイコンを表示できるようになります。

{% hint style="info" %}
グループ名の確認方法

Jiraサイトのプロビジョニング時に、Atlassianにより既定のユーザーグループ `jira-users-<your-site-name>` が自動作成されます。

例

* サイト `acme.atlassian.net` → グループ名は `jira-users-acme`
* サイト `bigcorp.atlassian.net` → グループ名は `jira-users-bigcorp`

グループ名は、`admin.atlassian.com` → 組織を選択 → **\[Directory]** → **\[Groups]** で確認できます。
{% endhint %}

{% hint style="info" %}
この設定が必要な理由

Jiraでは、課題画面でアプリパネルを表示または操作するために、EDIT\_ISSUE権限が必要です。

KeeperアプリはForgeの `jira:issuePanel` モジュールを使用しています。課題編集権限がない場合、課題画面にアプリアクションアイコンは表示されません。
{% endhint %}

#### ユーザーがプロジェクトにアクセスできない、または課題をまったく表示できない場合

Keeperパネルだけでなく、プロジェクト自体や課題を開けない場合は、アプリ権限ではなくJira側の設定に原因があります。以下を確認してください。

#### 1. プロジェクトロールの確認

CustomerやViewerなどの制限付きロールでは、課題への完全なアクセスはできません。以下は、プロジェクト種別ごとの必要ロールです。

| プロジェクト種別           | 必要なロール                            | 制限付きロール (不可)           |
| ------------------ | --------------------------------- | ---------------------- |
| Service Management | Service Desk TeamまたはAdministrator | Service Desk Customers |
| Software           | MemberまたはAdministrator            | Viewer                 |
| Business           | MemberまたはAdministrator            | Viewer                 |

ロールの確認・変更方法

1. **\[Project Settings]** → **\[Access]** → **\[People and access]** に移動
2. 対象ユーザーまたはグループを確認
3. 制限付きロールが割り当てられている場合は、課題にアクセス可能なロールへ変更

#### 2. プロダクトライセンスの確認

プロジェクトロールだけでは不十分です。ユーザーには有効なプロダクトライセンスも必要です。

1. `admin.atlassian.com` にアクセスし、組織を選択
2. **\[Directory]** → **\[Groups]** をクリック
3. 既定のJiraユーザーグループ `jira-users-<your-site-name>` を検索
4. グループを開き、**\[Apps]** タブを選択
5. 割り当てられているプロダクトとロールを確認
   1. **Jira** → ロールは**User**であること
   2. **Jira Service Management** → ロールは**User (Agent)**&#x3067;あること (Customerでは不可)
6. 必要なプロダクトが割り当てられていない場合は、右上の **\[Grant access]** をクリックし、該当プロダクトを選択して適切なロールを付与します。

{% hint style="warning" %}
CustomerとAgentの違い

Jira Service Managementでは、Customerロールはセルフサービスポータルのみアクセス可能です。課題の詳細画面にはアクセスできません。Keeperアプリパネルは課題画面上に表示されるため、ロールは必ずUser (Agent)に設定してください。
{% endhint %}

### 設定まとめ

| 設定項目       | 必要となる状況                           | 設定場所                                                                                         | 実施回数        |
| ---------- | --------------------------------- | -------------------------------------------------------------------------------------------- | ----------- |
| 課題編集権限     | アプリアイコンが表示されない場合                  | **\[Project Settings]** → **\[Access]** → **\[Space Permissions]** → **\[Edit Permissions]** | プロジェクトごとに一度 |
| プロジェクトロール  | プロジェクトにアクセスできない場合                 | **\[Project Settings]** → **\[Access]** → **\[People and access]**                           | プロジェクトごとに一度 |
| プロダクトライセンス | Jiraにアクセスできない、またはJSMポータルのみ表示される場合 | `admin.atlassian.com` → **\[Directory]** → **\[Groups]** → **\[Apps]**                       | サイト全体で一度    |

{% hint style="success" %}
推奨構成

上記3項目は、サイト既定の `jira-users-<your-site-name>` グループ単位で設定することを推奨します。

この方法であれば、新規ユーザーはグループに追加するだけで利用可能となり、個別ユーザーやプロジェクトごとの追加設定は不要です。

アプリの同意 (Allow access) は手順4で管理者が一度実施すれば完了します。
{% endhint %}

## トラブルシューティング

### 接続テスト (Test Connection) が成功しない

{% hint style="danger" %}
**症状**

接続テストが失敗する、またはタイムアウトする。ただし、ローカル環境からのcurlは成功する。
{% endhint %}

#### 原因

manifest.yml に対象ドメインが許可されていない。

#### 対処方法

1. `permissions.external.fetch.backend` に対象ドメインを追加
2. `forge deploy -e production` を実行
3. 再度接続テストを実行 (再インストール不要)

### ネットワークエラー

| 原因                      | 対処方法                    |
| ----------------------- | ----------------------- |
| ドメインが許可されていない           | manifest.yml に追加し、再デプロイ |
| HTTPを使用している (HTTPSではない) | ForgeはHTTPSのみ対応         |
| 自己署名証明書を使用している          | 有効なSSL証明書を使用            |
| トンネルが起動していない            | コマンダーサービスを起動            |

### 課題パネルにアプリアイコンが表示されない

{% hint style="danger" %}
**症状**

ユーザーはJiraの課題を閲覧できるが、Keeperのアクションアイコンが課題パネルに表示されない。
{% endhint %}

#### 原因

ユーザーのグループに**課題編集**権限が付与されていない。これは[Jiraの仕様](https://community.developer.atlassian.com/t/users-can-only-choose-to-display-hide-addons-webpanel-if-they-have-the-edit-issue-permission/48723)であり、アプリパネルのアイコンは課題を編集権限 (EDIT\_ISSUE) を持つユーザーにのみ表示される。

#### 対処方法

1. **\[Project Settings]** → **\[Access]** → **\[Space Permissions]** に移動
2. 歯車アイコン (権限編集) をクリック
3. **\[Issue Permissions]** セクションで **\[Edit Issue]** (課題を編集) を確認
4. ユーザーのグループ (例: `jira-users <your-site-name>`) を追加
5. **\[Save]** をクリック

詳しくは手順6を参照。

### ユーザーがプロジェクトにアクセスできない、または課題を表示できない

{% hint style="danger" %}
**症状**

Keeperパネルだけでなく、プロジェクト自体や課題を開けない。
{% endhint %}

#### 想定される原因

| 原因                                | 確認方法                                                                               | 対処方法                                                                   |
| --------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 不適切なプロジェクトロール (Customer / Viewer) | **\[Project Settings]** → **\[Access]** → **\[People and access]** でロールを確認         | JSMでは **\[Service Desk Team]**、Software / Businessでは **\[Member]** に変更 |
| プロダクトライセンスが未付与                    | `admin.atlassian.com` → **\[Directory]** → **\[Groups]** → グループ選択 → **\[Apps]** タブ | **\[Grant access]** から適切なプロダクトとロールを付与                                  |
| JSMポータルのみ表示される                    | ユーザーが Customer ロールまたは Customer ライセンス                                               | **User (Agent)** ライセンスおよび**Service Desk Team**ロールに変更                   |

詳細は手順6を参照。

### アイコンをクリックしてもアプリパネルが表示されない

{% hint style="danger" %}
**症状**

アクションアイコンは表示されるが、クリックすると空白、エラー、または読み込み中のまま完了しない。
{% endhint %}

#### 想定される原因と対処方法

| 原因                   | 対処方法                                                                                               |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| アプリ同意が未実施            | Jira管理者が **\[Jira Settings]** → **\[Apps]** → **\[Keeper]** に移動し、**\[Allow access]** をクリック (手順4参照) |
| アプリが共有されていない (開発モード) | アプリ所有者が**Developer Console** → **\[Distribution]** → **\[Sharing]** で共有を有効化                        |
| 組織レベルでアプリ承認が必要       | 組織管理者が `admin.atlassian.com` → **\[Security]** → **\[App access policies]** で承認                    |
| API URLまたはAPI Key未設定 | **\[Jira Settings]** → **\[Apps]** → **\[Keeper]** で手順5を完了                                         |
| トンネル / コマンダー未起動      | コマンダーサービスを起動し、トンネルを有効化                                                                             |

### 変更が反映されない

{% hint style="danger" %}
**症状**

権限やロールを変更しても挙動が変わらない (例: 課題編集を削除してもアイコンが表示される、または付与しても表示されない)。
{% endhint %}

#### 原因

Jiraでは権限情報が一定時間キャッシュされるため、反映まで数分かかることがある。

#### 対処方法

1. ユーザーに一度**ログアウト**し、ログインし直してもらう
2. ページを**ハードリフレッシュ** (Ctrl+Shift+R / Cmd+Shift+R)
3. シークレットウィンドウ / プライベートブラウザで課題を開く

### アプリがまったく表示されない

{% hint style="danger" %}
**症状**

課題上のアイコンもなく、**\[Jira Settings]** → **\[Apps]** にも表示されない。
{% endhint %}

#### 想定される原因と対処方法

| 原因                     | 対処方法                                                                 |
| ---------------------- | -------------------------------------------------------------------- |
| このサイトにアプリがインストールされていない | `forge install -e production` を実行、または `forge installations list` で確認 |
| 誤った環境にデプロイしている         | `forge deploy -e production` を実行                                     |
| ブラウザキャッシュ              | ブラウザキャッシュを削除し、ハードリフレッシュ、またはシークレットウィンドウで確認                            |

## デプロイの更新

新しいバージョンがリリースされた場合は、以下の手順を実施します。

```
# 最新コードを取得
git pull origin main

# UIを再ビルド
cd static/keeper-ui && npm run build && cd ../..
cd static/keeper-issue-ui && npm run build && cd ../..

# デプロイ
forge deploy -e production
```

{% hint style="info" %}
manifestの権限変更は、デプロイ後すぐに反映されます。再インストールは不要です。
{% endhint %}

## 環境管理

<table><thead><tr><th width="248.44921875">環境</th><th>デプロイコマンド</th><th>インストールコマンド</th></tr></thead><tbody><tr><td>本番環境</td><td><code>forge deploy -e production</code></td><td><code>forge install -e production</code></td></tr></tbody></table>

#### よく使用するコマンド

```
# インストール一覧を表示
forge installations list

# ログを表示
forge logs

# アンインストール
forge uninstall
```

## セキュリティのベストプラクティス

#### APIキーの保護

* APIキーはForgeの暗号化されたアプリストレージに保存されます
* APIキーをソース管理にコミットしない
* APIキーは定期的にローテーションする

#### ネットワークセキュリティ

* すべての通信はHTTPSで暗号化されます
* ファイアウォールでIPアドレスの許可リスト設定を検討
* 追加の認証手段としてCloudflare Accessの利用を検討

#### 最小権限の原則

コマンダーは、必要なコマンドのみを許可する設定とします。例:

```
keeper service-create \
  -p=9009 \
  -c="record-add,list,ls,get,record-type-info,record-update,share-record,share-folder,rti,record-permission,epm,service-status" \
  -rm="foreground" \
  -q=y \
  -f=json
```

## クイックリファレンス

#### 完全なデプロイ手順

```
npm install
cd static/keeper-ui && npm install && npm run build && cd ../..
cd static/keeper-issue-ui && npm install && npm run build && cd ../..
forge login
forge register
forge deploy -e production
forge install -e production
```

#### manifestのドメイン設定例

```
permissions:
  external:
    fetch:
      backend:
        - address: https://your-custom-domain.com
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/jira-workflow/forge-app-installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.