# 独自のシェルプラグインを構築する（ベータ版） ### **独自のシェルプラグインを構築する（ベータ版）** [1Password Shellプラグインレジストリー](https://developer.1password.com/docs/cli/shell-plugins/)にお気に入りのコマンドラインツールが表示されない場合は、独自のプラグインをCreateできます。 1Password CLIを使うと、シェルプラグインをローカルで構築およびテストできるため、1PasswordにSaveした資格情報を使って、お気に入りのCLIを認証するためのサポートを追加できます。 プラグインを他のユーザーが利用できるようにしたい場合は、[シェルプラグインの GitHubリポジトリーでプルリクエストをCreate](https://github.com/1Password/shell-plugins)できます。 ### **必要条件** * **1Passwordに**[サインアップしていること](https://1password.com/pricing)。 * [Mac](https://support.1password.com/get-the-apps/?mac)または[Linux](https://support.1password.com/get-the-apps/?linux)用の1Passwordをインストールしてサインインしていること。 * [1Password CLI](https://developer.1password.com/docs/cli/get-started/)をインストールし、[デスクトップアプリの統合を](https://developer.1password.com/docs/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration)オンにしていること。 * [Go 1.18 以降](https://go.dev/doc/install)をインストールしていること。 * [Git](https://git-scm.com/)をインストールしていること。 * [GNU Make](https://www.gnu.org/software/make/)をインストールしていること。 ### **コンセプト** 1Password Shellプラグインでは、次の内容を記述する必要があります。 * プラットフォームが提供する資格情報 * プラットフォームが提供するCLIまたは実行ファイル * それぞれのCLIが認証するために認証情報をプロビジョニングする方法 * それぞれのCLIのどのコマンドに認証が必要かという情報 * ローカルファイルシステムにSaveされた認証情報を1Passwordにインポートする方法 ShellプラグインはGoで記述されており、パッケージ内の一連のGo構造体で構成され、特定のプラットフォーム、サービス、または製品用のプラグインを構成します。Goの専門家でなくても心配しないでください。プラグインを構築するために学べる[例がたくさんあります。](https://github.com/1Password/shell-plugins/tree/main/plugins) ### **ステップ1： プラグインテンプレートを利用する** まず、 GitHub上の[1Password Shellプラグインリポジトリー](https://github.com/1Password/shell-plugins)をクローンまたはフォークします。ここには、現在のプラグインレジストリーと、開発への参加に必要なSDKが含まれています。 これらを開始するには、次のMakefileコマンドを使用します。 $ make new-plugin 次の情報を入力するよう求められます。 * プラグイン名：プラットフォームの小文字の識別子（例：aws、github、digitalocean、azure）。これはGoパッケージの名前にも使われます。 * プラットフォーム表示名：プラットフォームの表示名（例：AWS、GitHub、DigitalOcean、Azure）。 * 資格情報名：プラットフォームが提供する資格情報（例：Personal Access Token、API Key、Auth Token）。 * 実行可能ファイル名：呼び出しに使うコマンド名です（例：aws、gh、doctl、az）。 フォームに入力し終わると、pluginsプラグイン、資格情報、実行可能ファイルの個別のファイルを含むGoパッケージがディレクトリー内にCreateされます。 例：![](https://4200399111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8GVOyHz3wUSpdV3qlPwR%2Fuploads%2FrbF7zoNEJTQ8aX73pq89%2F0.png?alt=media) 時間を節約するために、生Createされたファイルには、Makefileプロンプトからベストエフォート方式で取得した情報がスタブ化されます。コードには*TODO*コメントが含まれており、変更すべき点や正確性を検証すべき点を指示しています。 ### **ステップ2：プラグインの定義を編集する** ファイルplugin.goには、プラグインを構成する資格情報の種類や実行可能ファイルなど、プラグインとそれが表すプラットフォームに関する基本情報が含まれています。 プラグインの例 * AWS * [GitHub](https://github.com/1Password/shell-plugins/blob/main/plugins/github/plugin.go) * [Herok](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/plugin.go) ### **ステップ3：資格情報の定義を編集する** 資格情報定義ファイルには、資格情報のスキーマ、資格情報を実行可能ファイルにプロビジョニングする方法、資格情報を1Passwordにインポートする方法が記述されています。 資格情報の例 * [AWS ](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/access_key.go)Access Key * [GitHub Personal Access Token](https://github.com/1Password/shell-plugins/blob/main/plugins/github/personal_access_token.go) * [Heroku API キー](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/api_key.go) #### **資格情報とスキーマ** 資格情報定義の最初のセクションでは、資格情報に関する情報を追加できます。 * プラットフォームが呼び出す資格情報の名前 * プラットフォームによって提供され、資格情報を説明するドキュメントのURL*（オプション）* * 資格情報をCreateおよび取り消すことができるプラットフォーム上の管理URL。これは通常、プラットフォームのダッシュボード、コンソール、または認証設定へのURLです*（オプション）* 次のセクションでは、認証情報のスキーマを定義します。これはフィールドに分割されます。多くの認証情報は1つのシークレットフィールドのみで構成されていますが、フィールドがシークレットでなくても、認​​証に関連する1Passwordアイテムに詳細を追加するためにフィールドを追加できます。 追加フィールドの例としては、ホスト、ユーザー名、アカウントID、認証に必要なその他の全てのものがあり、資格情報タイプの1Passwordアイテムに含めることが理にかなっています。ここで宣言する全てのフィールドは、エンド ユーザーの 1Passwordアイテムにも表示されます。 フィールドごとに指定できる内容は次のとおりです。 * （タイトルを冠した）フィールド名*（必須）* * フィールドの簡単な説明*（必須）*。markdownをサポートします。 * フィールドがオプションかどうか。デフォルトはfalseです。 * フィールドがシークレットかどうか、1Password GUIで非表示にするかどうか。デフォルトではシークレットではありません。\ 注: 資格情報スキーマは、少なくとも1つのシークレットフィールドを含む必要があります。 * 実際の資格情報の値の構成。長さ、文字セット、固定プレフィックスが含まれているかどうか。 #### **プロビジョナー** 資格情報の定義では、資格情報を認証に使えるように、資格情報が実行可能ファイルに通常どのようにプロビジョニングされるかも指定します。 プロビジョナーは、本質的には、実行ファイルが1Password CLIによって実行される前と、クリーンアップが必要な場合に、実行ファイルが終了した後に実行されるフックです。これらのフックでは、プロビジョナーは、環境変数の設定、ファイルのCreate、コマンドライン引数の追加、一時的な資格情報の生Createなど、実行ファイルの認証に必要な全てのセットアップを行うことができます。実行ファイルが終了した後、ユーザーのファイルシステムに資格情報の痕跡は残らないはずです。 SDKにはすぐに利用できる一般的なプロビジョナーがいくつか用意されているため、ほとんどの場合、プロビジョニングの内部を気にする必要はありません。 * 環境変数 現在、プロビジョニング方法として環境変数を使うことを私たちはお勧めします。 環境変数は、シークレットをプロビジョニングする最も一般的な方法です。環境変数はメモリー内にのみ存在し、ほぼ全てのCLIで環境変数を使って認証できます。 SDKによって提供される環境変数プロビジョナーを使う方法は次のとおりです。 provision.EnvVars(map\[string]sdk.FieldName{\ "AWS\_ACCESS\_KEY\_ID": fieldname.AccessKeyID,\ "AWS\_SECRET\_ACCESS\_KEY": fieldname.SecretAccessKey,\ }) 1Passwordのフィールド名と、それを配置する環境変数名を指定します。 基盤となるCLIが読み取る環境変数を把握するためのヒントをいくつか紹介します。 * プラットフォームのCLIドキュメントのウェブサイトで、スタートガイド、認証ガイド、または CLIリファレンスドキュメントを検索してください。 * CLIのヘルプテキストまたはマニュアルページを参照してください。 * CLIやそれが使う基盤となるSDKがオープンソースである場合は、ソースコードをスキャンして、認証用の環境変数を受け入れるかどうかを確認してください。 * ファイル 一部のCLIは、ディスク上のファイルからの資格情報の読み取りのみをサポートしています。その場合は、SDKが提供するファイルプロビジョナーを利用できます。ファイルプロビジョナーは、一時ディレクトリーにファイルをCreateし、その後削除します。 セキュリティー上の理由から、ファイルプロビジョナーによってCreateされたファイルは、実行可能ファイルによって1回しか読み取ることができません。この制限がユースケースによって機能しない場合は、[GitHubでイシューとして報告](https://github.com/1Password/shell-plugins/issues)できます。 ファイルプロビジョナーを使って一時的なJSONファイルをプロビジョニングし、生Createされたパスを実行可能ファイルに渡す方法の例をいくつか示します。 ファイルプロビジョナーをCreateし、出力パスを --config-file として渡す。 provision.TempFile(configFile,\ provision.Filename("config.json"),\ provision.AddArgs("--config-file", "{{ .Path }}"),\ ) ファイルプロビジョナーをCreateし、出力パスをCONFIG\_FILE\_PATHに設定する。 provision.TempFile(configFile,\ provision.Filename("config.json"),\ provision.SetPathAsEnvVar("CONFIG\_FILE\_PATH"),\ ) ファイルプロビジョナーをCreateし、出力パスをJavaプロパティーとして渡す。 provision.TempFile(configFile,\ provision.Filename("config.json"),\ provision.AddArgs(\`-Dconfig.path="{{ .Path }}"\`),\ ) JSONファイルの内容を生Createするコードの例。 func configFile(in sdk.ProvisionInput) (\[]byte, error) {\ config := Config{\ Token: in.ItemFields\[fieldname.Token]\ } contents, err := json.Marshal(config) if err != nil { return nil, err } return \[]byte(contents), nil } type Config struct { Token string \`json:"token"\` } * その他 SDKに含まれる標準のプロビジョナーが実行可能ファイルの認証に不十分な場合は、独自のプロビジョナーをCreateすることもできます。そのためには、[sdk.Provisionerインターフェイス](https://github.com/1Password/shell-plugins/blob/main/sdk/provisioner.go)を実装します。 カスタムプロビジョナーの良い例は、[AWS STSプロビジョナー](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/sts_provisioner.go)が挙げられます。これは1Passwordからロードされたワンタイムパスワードコードに基づいて一時的な認証情報を生Createします。 #### **インポーター** 資格情報の定義では、インポーターを指定することもできます。インポーターは、ユーザーの環境とファイルシステムをスキャンして、必要な資格情報が存在するかどうかを確認します。1Password CLIはインポーターを実行し、ユーザーに資格情報を1つずつ1Passwordにインポートするように求めます。 CLIが認証データをディスクに書き込むことは非常に一般的で、最も一般的にはホームディレクトリーの隠し設定ファイルに書き込まれます。これは必ずしもCLIによって文書化されているわけではないので、そのような設定ファイルが存在するかどうかを確認するためのヒントをいくつか示します。 * 設定ファイルについては、プラットフォームのドキュメントを確認してください。 * CLIが認証をカバーするlogin、auth、configure、setupなどのコマンドを提供しているかどうかを確認します。提供されている場合は、そのようなコマンドのフローの完了後に、ホーム ディレクトリーに資格情報がSaveされる可能性が高くなります。 * CLIがオープンソースの場合は、ソースコードをチェックして、そのようなファイルが存在するかどうかを確認します。 * 自分のホームディレクトリーまたは\~/.configディレクトリーを調べて、プラットフォームに関連するファイルがあるかどうかを確認します。ローカルのaws設定ファイルを検索するコマンドの例を次に示します。 $ find \~/.\* -maxdepth 3 -path "\*aws\*" SDKには、ファイルの読み込み、ファイルの解析、環境変数のスキャンを行うヘルパー関数が用意されており、資格情報の種類に応じたインポーターのCreateが容易になります。 インポーターの例 * [AWS Access Key](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/access_key.go) ( \~/.aws/credentials) * [CircleCI Personal API Token](https://github.com/1Password/shell-plugins/blob/main/plugins/circleci/personal_api_token.go) (\~/.circleci/cli.yml) * [Heroku API Key](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/api_key.go) ( \~/.netrc) ### **ステップ4：実行可能ファイルの定義を編集する** プラグインが最後に行うのは、1Passwordで認証を処理するCLIまたは実行可能ファイルを定義することです。これが全てをまとめる最後の部分です。 実行可能ファイルの定義では、次の内容が記述されます。 * 1Password CLI によって実行されるコマンド。 * プラットフォームが呼び出すCLIの表示名。 * 実行可能ファイルを説明する、プラットフォームによって提供されるドキュメントのURL（オプション*）*。 * 実行可能ファイルに認証が必要な条件。例えば多くのCLIでは、--helpまたは--versionフラグが存在する場合、認証は必要ありません。 * 実行可能ファイルが使う資格情報。 実行可能な例 * [AWS CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/aws.go) ( aws) * [GitHub CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/github/gh.go) ( gh) * [Heroku CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/heroku.go) ( heroku) ### **ステップ5：プラグインをローカルでビルド＆テストする** プラグイン、資格情報、実行可能ファイルの定義が適切に入力されているかどうかを確認するには、次の Makefileコマンドを実行して定義を検証します。 make \/validate それがCreate功したら、プラグインをローカルでビルドしてテストします。次のコマンドを使って実行できます。 make \/build ビルドのアーティファクト（Create果物）は\~/.op/plugins/localに配置されます。次のコマンドを実行すると、op内に表示されます。 $ op plugin list 実際に動作するかどうかを確認するには、次のop plugin initコマンドを使います。 $ op plugin init \ ### **PRを送信する** ローカルでプラグインを使い続けることは自由ですが、他のユーザーも使えるように、[GitHubのメインレジストリー](https://github.com/1Password/shell-plugins)にPRを送信することをお勧めします。 その前に、GitHub の[CONTRIBUTING.md](https://github.com/1Password/shell-plugins/blob/main/CONTRIBUTING.md)ファイルを必ず読んでください。 SDKがあなたのユースケースに適していないと思われる場合は、[GitHubでイシューをCreateするか、 ](https://github.com/1Password/shell-plugins/issues)[Developer Slack ワークスペース](https://developer.1password.com/joinslack)に参加してプラグインの提案をお知らせください。ユースケースに最適なアプローチについてアドバイスいたします。 ### **さらに詳しく知るには** * [シェルプラグインのトラブルシューティング](https://developer.1password.com/docs/cli/shell-plugins/troubleshooting/) * [開発者Slackワークスペースに参加する](https://developer.1password.com/joinslack)