Domino 管理者 - Domino REST API について知っておくべきこと (パート 2)

2023/12/28 - 読み終える時間: 9 分

Domino Administrators - What You Need to Know About the Domino Rest API Part Two の翻訳版です。

Domino 管理者 - Domino REST API について知っておくべきこと (後編)

2023年12月15日

著者: Heather J Hottenstein / Technical Advisor

「Domino 管理者が Domino REST API について知っておくべきこと」の前回の記事では、Domino管理者が Domino REST API に関心を持つ理由について説明し、ダウンロードとインストールの方法を紹介し、コンポーネントを紹介しました。インストール後、DRAPI は Domino サーバー上で自動的に実行を開始します。しかし、Domino 上で動作する HTTP のように、"load HTTP"を発行したからといって、本番に耐えうる Web サーバーができたわけではありません。この記事では、Dominoアプリケーションの完全な機能と安全なインタフェースを確保するために必要な設定手順について説明します。

ポートの保護

Domino REST API には HTTP を使用してアクセスする 4 つのポートがあります。ポートと提供する機能は次のとおりです。

他のHTTPトラフィックと同様に、これらのポートも証明書で保護する必要があります。デフォルトの Web ポート 80 とは異なり、TLS を使用してアクセスしてもポートは変更されません。以下の図では、HTTP を介した外部 Web トラフィック要求は nginx プロキシで受信され、Domino REST API または Domino Web サーバーにルーティングされます。さらに、DRAPI 管理コンソールへのアクセスは 8889 経由のローカルアクセスで発生することがわかります。

これらのポートは Domino の HTTP エンジンとは別物であることに注意することが重要です。実際、Domino REST API は Domino サーバーに HTTP をロードせずに動作します。現在、これらのポートは Domino の証明書マネージャとそれぞれの TLS キャッシュによって保護されていません。ただし、証明書マネージャを使用して Let's Encrypt 証明書を取得できます。その後、証明書ストアの certstore.nsf から証明書をエクスポートし、セキュアポート構成に使用します。高レベルでは、証明書取得プロセスで証明書マネージャを活用し、Domino サーバー上で直接 DRAPI のポートをセキュアにするためにその証明書を使用するために、以下のステップを踏みます。

1. 証明書ストアの certstore.nsf で、エクスポート可能な TLS クレデンシャルを作成します。

2. クレデンシャル要求が処理され、有効な証明書が作成されたら、TLS クレデンシャル文書の [Export TLS Credentials]アクションボタンを使用して証明書をエクスポートします。この例では、PKCS12 形式が選択され、ファイルは PFX タイプとしてエクスポートされます。

3. rock.pfx を DRAPI がインストールされている Domino サーバーの Domino\Data フォルダにコピーします。 注：証明書の場所は Data フォルダである必要はありません。証明書の場所は Data フォルダである必要はなく、Domino サーバにローカルで、ステップ 4 で説明する JSON 設定ファイルで正しく参照される必要があります。

4. DRAPI がインストールされた Domino サーバで、テキストエディタを使用して以下のような情報を含む JSON 設定ファイル（tls-config.json）を作成し、keepconfig.d フォルダに保存します。

注意事項：証明書のパスは、フォワード・スラッシュ（/）を使用して指定されたTLSFile.です。

{

"TLSFile": "c:/domino/data/go.pfx",

"TLSPassword": "P@$$w0rd1352",

"TLSType": "pfx"

}

5. テキストエディタを使って、サーバーのnotes.iniを開きます。

6. KeepManagementURLを更新し、httpsとサーバーのホスト名を含めます。

KeepManagementURL=https://rock.adventure.com:8889

7. Domino コンソールで tell restapi reload を実行します。

重要：restapiをリロードする前に、サーバーのnotes.iniのLeepManagementURLを更新してください。

注意事項: Let's Encrypt証明書が更新されたら、エクスポート、コピー、リロードの手順を繰り返す必要があります。 または、これらの手順を自動化するプロセスを作成してください。

もう 1 つのオプションは、外向きのプロキシ、つまり nginx を使用することです。上記と同様に、Certificate Manager を使用して証明書を取得し、それをエクスポートしてプロキシで使用することができます。証明書の更新には証明書のエクスポートを繰り返す必要があることに注意してください。HTTP が終了する外向きのプロキシを使用する場合、つまり Domino サーバーとプロキシ間のトラフィックが HTTP を使用する場合、KeepManagementURL を更新する必要はなく、keepconfig.d フォルダに TLS JSON 設定ファイルも必要ありません。

• nginx を HTTPS プロキシとして構成する - 単一ドメイン - HCL Domino REST API ドキュメント (hcltechsw.com)

• nginxをサブドメインでHTTPSプロキシとして構成する - HCL Domino REST API Documentation (hcltechsw.com)

機能アカウント

Healthcheck、Management、Prometheusポートにアクセスできるように、機能アカウントを設定することも、インストール後に必要なステップです。機能アカウントは、さまざまなタスクを実行するために必要な個人アカウントではありません。機能アカウントを作成するには、json 構成ファイルを作成し、DominoDatakeepconfig.d フォルダに配置します。この構成ファイルにはユーザー名とシークレットが含まれる。DRAPI ドキュメントには、管理機能アカウントのデフォルトテキストとして、ユーザー名が Doctor Notes、シークレットがパスワードの塩漬け値である以下の16進数テキストが含まれています。

{

"identity": {

"managementAPI": {

"Doctor Notes": {

"active": true,

"secret":

"E4B321EBA91B7F92D9BF5EAFA5322824FEC2287B8A6C133D7C31EFB706A2BA30:1A57478185E7AF3A98F01ECA08F0BA881DBC88BEC60AE8C6F1B1CC5CC55C11A20F676E082BF2D28BB96DB5A8CFB091C767C035B380DB4CBC7D1001EA8BE01663"

}

}

}

}

この例を使用して構成ファイルを作成します。必要に応じて別のユーザー名を指定します。Domino コンソールで tell restapi reload を発行した後、https://localhost:8889 を使用して管理コンソールにアクセスします。

注：ログインするには、構成ファイルに記載されているユーザー名（大文字と小文字が区別され ます）を入力し、パスワードは password とします。

もちろん、デフォルトのパスワードは変更する必要があります。新しいシークレットを取得するには、Salt thisフィールドにパスワードを入力します。Saltボタンを押すと、新しいシークレットが設定ファイルに入力されます。そして、新しいパスワードを有効にするために "tell restapi reload" を発行することを忘れないでください。

JWTの設定

管理コンソールには、「Create IdP Certificate」ボタンがあります。これは DRAPI を実行している複数の Domino サーバーで共有できる恒久的な JWT トークンを作成するために使用します。Create IdP Certificate ボタンを押すと、keepconfig.d フォルダに証明書、公開/秘密鍵ペア、json 設定ファイルが生成されます。これらの4つのファイルは、環境全体で共有したい場合は、DRAPIを実行している他のDominoサーバーにコピーペーストすることができます。

JWT コンフィギュレーションに関する注意事項： Domino REST API は複数の外部プロバイダから JWT トークンを受け入れることができます。Domino REST API は複数の外部プロバイダから JWT トークンを受け入れることができます。そのための手順はここにあります。

• Auth* - HCL Domino REST API Documentation (hcltechsw.com)

OAuth

Domino REST API はアクセストークンを消費するように設計されています。このトークンは OAuth ダンスの結果であることも、単に Domino 認証情報の交換の結果であることもあります。Domino REST API は OAuth ダンスを行う IdP を提供します。

OAuth を動作させるには、 oauth.nsf データベースと、keepconfig.d フォルダ内の oauth 設定ファイルが必要です。

oauth.nsfデータベースはDRAPIインストールの一部として作成されます。データベースの ACL を編集し、DRAPI を実行している Domino サーバーを OAuthAdmin ロールに追加する必要があります。

次に oauth 設定ファイルを作成します。以下のテキストをコピーしてください。

{

"oauth": {

"active": true,

"database": "oauth.nsf",

"url": "http://rock.adventure.com:8880",

"authCodeExpiresIn": 120,

"accessTokenExpiresIn": 3600,

"refreshTokenExpiresIn": 525600

}

}

次に、テキストベースのエディタ（メモ帳など）を開き、テキストを貼り付けます。ドキュメントを拡張子.json、つまりoauth.jsonで保存し、keepconfig.dフォルダに置きます。最後に、tell restapi reloadを実行して、構成の更新を有効にします。

LocalKeepAdmins グループ

DRAPI インストールの一部として作成された Domino データベースでは、それぞれの ACL に LocalKeepAdmins グループが自動的に追加されます。この ACL エントリを利用するには、Domino ディレクトリにグループを作成し、DRAPI 管理者、つまりスコープとアプリケーションの作成と更新を行う者を追加する必要があります。

DRAPI データベース

DRAPI の一部としてインストールされた 3 つのデータベースは、管理グループとサーバーグループを追加して、組織のセキュリティ要件を満たすように ACL を更新する必要があります。さらに、DRAPI がインストールされている Domino サーバを管理サーバとして追加することを推奨します。

Domino Keep Agent Scheduler（keepagents.nsf）データベースのデフォルトは Reader ですが、No Access に変更することもできます。ランタイムエージェントを管理する人、つまり LocalKeepAdmins には Editor アクセス権が必要です。

Domino Keep OAuth（oauth.nsf）データベースには、DeleteフラグのないAuthorへのDefaultアクセスが必要です。これにより、ユーザーは管理 UI を使用して同意を取り消すことができます。

Domino Keep 設定（keepconfig.nsf）データベースのデフォルトアクセスは Reader にする必要があります。

最後に、Domino サーバーに追加するデータベースと同様に、サーバーの ID または組織の署名 ID でこれら 3 つのデータベースに署名することをお勧めします。そこで、Domino Administrator クライアントを使用して、keepagents.nsf、keepconfig.nsf、および oauth.nsf を選択し、それぞれの ID ファイルで署名します。

まとめると、Domino REST API の構成手順には以下のものが含まれます。

• TLS 証明書で HTTP トラフィックを保護し、notes.ini で KeepManagementURL を更新します。

• DominoDatakeepconfig.d フォルダに json 設定ファイルを作成して機能アカウントを作成し、管理コンソールを使用してパスワードをカスタム値に変更します。

• DRAPI を実行している複数の Domino サーバーで共有できる恒久的な JWT トークンを作成します。DRAPI を実行する複数の Domino サーバ間で共有できる恒久的な JWT トークンを作成します。

• oauth.nsf データベースの ACL を更新し、oauth 設定ファイルを作成することで、アプリケーションアクセス用の OAuth を設定します。

• LocakKeepAdminsグループを作成し、設定します。

• DRAPIデータベースのACLを更新します。

• DRAPI データベースに署名します。

さて、Domino REST API が完全に機能し、セキュアになったところで、次回のブログ記事では DRAPI Admin UI を使ってスキーマ、スコープ、OAuth アプリケーションを作成し、REST API アクセス用のデータベースを準備する方法を紹介します。

• Domino 管理者 - Domino REST API について知っておくべきこと (パート 3)