Forge Appのインストール

ワークフロー承認で使用するKeeper for Jira Forgeアプリの自社環境向けデプロイ

概要

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

自社環境でのデプロイが必要な理由

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

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

要件

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のインストール

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

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

nvm install 18
nvm use 18

インストールの確認

node -v
npm -v

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

npm install -g @forge/cli

WSL / Linux環境での要件

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

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

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

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

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

この設定が必要な理由

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

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

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

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

パターン	許可	例
完全一致のドメイン	可	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に移動します。初回表示時に、アクセス許可を求める画面が表示されます。

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

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

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

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

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

1. Atlassian Developer Consoleにアクセス

2. Keeper for Jiraアプリを選択

3. [Distribution] → [Sharing] に移動

4. [Share app] を有効化

5. インストールリンクをコピーし、他のJira管理者またはユーザーに共有

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

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

複数の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] をクリックして保存します。

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

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

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

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

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

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

対処手順

1. [Project Settings] → [Access] → [Space Permissions] に移動

2. 歯車アイコン (編集権限) をクリック

3. [Issue Permissions] セクションで [Edit Issue] を探す

4. サイトの既定ユーザーグループ jira-users-<your-site-name> を追加

5. [Save] をクリック

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

グループ名の確認方法

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

例

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

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

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

この設定が必要な理由

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

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

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

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)であること (Customerでは不可)

6. 必要なプロダクトが割り当てられていない場合は、右上の [Grant access] をクリックし、該当プロダクトを選択して適切なロールを付与します。

CustomerとAgentの違い

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

設定まとめ

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

推奨構成

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

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

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

トラブルシューティング

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

症状

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

原因

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

対処方法

1. permissions.external.fetch.backend に対象ドメインを追加

2. forge deploy -e production を実行

3. 再度接続テストを実行 (再インストール不要)

ネットワークエラー

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

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

症状

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

原因

ユーザーのグループに課題編集権限が付与されていない。これはJiraの仕様であり、アプリパネルのアイコンは課題を編集権限 (EDIT_ISSUE) を持つユーザーにのみ表示される。

対処方法

1. [Project Settings] → [Access] → [Space Permissions] に移動

2. 歯車アイコン (権限編集) をクリック

3. [Issue Permissions] セクションで [Edit Issue] (課題を編集) を確認

4. ユーザーのグループ (例: jira-users <your-site-name>) を追加

5. [Save] をクリック

詳しくは手順6を参照。

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

症状

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

想定される原因

原因	確認方法	対処方法
不適切なプロジェクトロール (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を参照。

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

症状

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

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

原因	対処方法
アプリ同意が未実施	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を完了
トンネル / コマンダー未起動	コマンダーサービスを起動し、トンネルを有効化

変更が反映されない

症状

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

原因

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

対処方法

1. ユーザーに一度ログアウトし、ログインし直してもらう

2. ページをハードリフレッシュ (Ctrl+Shift+R / Cmd+Shift+R)

3. シークレットウィンドウ / プライベートブラウザで課題を開く

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

症状

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

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

原因	対処方法
このサイトにアプリがインストールされていない	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

manifestの権限変更は、デプロイ後すぐに反映されます。再インストールは不要です。

環境管理

環境	デプロイコマンド	インストールコマンド
本番環境	forge deploy -e production	forge install -e production

よく使用するコマンド

# インストール一覧を表示
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