TLS 証明書

エージェントとユーザーが HTTPS で OpenLM Platform に接続できるようにするには、TLS 証明書を正しく設定します。OpenLM Platform と通信する主な主体は、フィールドエージェント（Broker、Workstation Agent、Directory Synchronization Agent（DSA））と Web UI にアクセスするユーザーです。これらはすべて、単一の HTTPS エンドポイントを通じて接続します。デプロイ時に設定する TLS 証明書が、この仕組みを成立させます。証明書が正しく設定されていないと、エージェントは暗号化された HTTPS 接続を確立できず、システムと通信できません。

要件

証明書は、次の要件を満たす必要があります。

PEM 形式の証明書ファイルと鍵ファイルを使用する

証明書とその秘密鍵は、それぞれ別の PEM ファイル（-----BEGIN CERTIFICATE----- で始まるテキスト形式）で用意してください。鍵ファイルにはリーフ証明書の秘密鍵のみを格納し、CA の秘密鍵は決して含めないでください。PFX/PKCS#12 や DER などのバイナリ形式は、先に変換してください。

openssl pkcs12 -in cert.pfx -clcerts -nokeys -out tls.crt
openssl pkcs12 -in cert.pfx -nocerts -nodes -out tls.key

証明書と鍵が対になっていることを確認するには、次のコマンドを実行します。2 つの出力は同一でなければなりません。

openssl x509 -noout -modulus -in tls.crt | md5sum
openssl rsa  -noout -modulus -in tls.key | md5sum

証明書をドメインに一致させる

証明書の Common Name（CN）または Subject Alternative Name（SAN）は、デプロイ時に設定する完全修飾ドメイン名（FQDN）（例: openlm.yourcompany.com）と一致している必要があります。これは、すべてのエージェントと Web UI ユーザーが接続するドメインです。

すべてのエージェントマシンで証明書を信頼させる

Broker、Workstation Agent、DSA を実行するすべてのマシンで、この証明書が信頼されている必要があります。公開 CA（Let's Encrypt や DigiCert など）が発行した証明書であれば、通常は既定のまま動作します。

証明書が 社内 CA またはプライベート CA により発行されている場合は、その CA のルート証明書および中間証明書を各エージェントマシンの OS trust store にインストールする必要があります。これがないと、エージェントは接続を拒否します。

Kubernetes クラスタ内部で証明書を信頼させる

マイクロサービスも証明書を信頼している必要があります。これは、OpenLM Platform が認証に IdentityServer を使用し、各マイクロサービスが https://<your-fqdn>/identity にコールバックして JWT トークンを検証するため重要です。クラスタ内部で証明書が信頼されていない場合、サービスは identity issuer に到達できず、JWT 検証が失敗し、ユーザーはサインインできません。

プライベート CA が発行した証明書の場合は、すべてのマイクロサービスに完全なチェーン（ルート CA と中間 CA 証明書）がマウントされます。

• Platform as VM では、インストーラーが作成する custom-ca-cert という名前の ConfigMap（データキー custom-ca-cert.crt）からマウントされます。
• その他のパスでは、OpenLM Platform の values の global.deploymentCerts を通じて、secret からマウントされます。クラスター内でプライベート CA を信頼させる を参照してください。

証明書の設定

証明書を設定するには、使用するデプロイパスの手順に従います。

Platform as VM では自動作成されます

Platform as VM でデプロイした場合、これらのオブジェクトを手動で作成しないでください。config.yaml の tls_cert_path と tls_key_path（既定では /etc/openlm/certs/tls.crt と /etc/openlm/certs/tls.key）に PEM 形式の証明書と鍵を配置すれば、インストーラーが openlm-lb-cert Secret と custom-ca-cert ConfigMap の両方を作成します。

プライベート CA や自己署名 CA の場合は、リーフ証明書、中間証明書、ルート CA の順にチェーン全体を 1 つの証明書ファイルに連結してください。証明書をローテーションするには、ファイルを差し替えて ./entrypoint.sh を実行します。Secret や ConfigMap を手動で編集しても、インストーラー実行時に上記のファイルパスの内容で上書きされます。

以降のセクションの手動手順は、AWS、Azure、オンプレミスマシンのパスに適用されます。

Kubernetes TLS secret

証明書と秘密鍵を、openlm namespace 内の Kubernetes secret として読み込みます。

kubectl create secret tls openlm-lb-cert \
  --key your-domain.key \
  --cert your-domain.crt \
  -n openlm

クラスター内でプライベート CA を信頼させる

証明書がプライベート CA から発行されている場合は、OpenLM Platform の values の global.deploymentCerts で、CA チェーンをマイクロサービスにマウントします。チャートは、secret の 1 つのキーを、すべてのマイクロサービスにファイルとしてマウントします。次の例では TLS secret を指定しています。この場合、その証明書ファイルにはチェーン全体（リーフ証明書、中間証明書、ルート CA の順）が含まれている必要があります。

global:
  deploymentCerts:
    enabled: true
    name: openlm-lb-cert
    secretKeyName: tls.crt
    secretFileName: custom-ca-cert.crt
    containerMountPath: /usr/local/share/ca-certificates/custom-ca-cert.crt

チェーンに必要な証明書が不明な場合は、ブラウザで同じドメインの Web サイトにアクセスし、証明書チェーンをエクスポートします。

Red Hat OpenShift では、ルートが提供するのは openlm-lb-cert ではなくルーターの証明書です。FQDN に対してルーターが提供する証明書の CA チェーンを secret に格納し、deploymentCerts でその secret を指定してください。Red Hat OpenShift を参照してください。

証明書が公開 CA から発行されている場合は、マイクロサービスはすでにその証明書を信頼しているため、deploymentCerts は不要です。

自己署名証明書または独自 CA 証明書

自己署名証明書、または独自の社内 CA が発行した証明書を使う場合は、完全な証明書チェーン を、その証明書を使用するすべての場所で提供する必要があります。

• Kubernetes TLS secret (openlm-lb-cert) には、リーフ証明書だけでなく完全なチェーンを含める必要があります
• マイクロサービスにマウントする CA チェーン（Platform as VM では custom-ca-cert ConfigMap、その他のパスでは global.deploymentCerts）には、ルート証明書とすべての中間 CA 証明書を含める必要があります
• すべてのエージェントマシンとユーザーワークステーションの OS trust store にルート CA をインストールする必要があります

完全なチェーンなしでリーフ証明書だけを渡すことは、TLS エラーの最も一般的な原因のひとつです。これらのいずれかの場所でチェーンが欠けていると、接続は失敗します。

トラブルシューティング

次の項目で、よくある証明書の問題を扱います。

まず証明書の信頼状態を確認する

信頼されていない、または不完全な証明書チェーンは、エージェント接続失敗の最も一般的な原因です。デプロイ後にエージェントが OpenLM Platform へ到達できない場合は、まず証明書の信頼状態とチェーンの完全性を確認してください。

エージェントが接続できないのはなぜですか。

エージェントマシンの OS trust store に CA のルート証明書が入っているか確認してください。Windows では Trusted Root Certification Authorities ストア、Linux では /etc/pki/ca-trust/ または /usr/local/share/ca-certificates/ を確認します。

ブラウザに OpenLM Platform の "not secure" 警告が出るのはなぜですか。

証明書がドメインと一致していない、期限切れ、またはブラウザに信頼されていない状態です。

ユーザーがサインインできない、またはサービスで認証エラーが出るのはなぜですか。

クラスター内の CA チェーンが欠落しているか、不完全である可能性が高いです（Platform as VM では custom-ca-cert ConfigMap、その他のパスでは global.deploymentCerts が参照する secret）。各サービスは identity issuer（https://<your-fqdn>/identity）に対して JWT を検証するため、この証明書を信頼する必要があります。チェーンが完全であることを確認し、再デプロイしてください。

チェックリスト

• 証明書の CN または SAN がプラットフォーム FQDN と一致している
• 証明書と秘密鍵が Kubernetes TLS secret（`openlm-lb-cert`）として読み込まれている
• クラスタ内部で完全な CA チェーンが信頼されている（Platform as VM では `custom-ca-cert`、その他のパスでは `global.deploymentCerts`）
• Broker を実行するすべてのマシンに CA ルート証明書がインストールされている
• Workstation Agent を実行するすべてのマシンに CA ルート証明書がインストールされている
• Directory Sync Agent を実行するすべてのマシンに CA ルート証明書がインストールされている
• Web UI にブラウザの証明書警告なしでアクセスできる