SAML連携の証明書更新 ── 更新エラーの解決方法

概要

AWSとSAML 2.0対応のアイデンティティプロバイダー（IdP）を連携してシングルサインオン（SSO）を実現している環境では、IdP側の署名証明書の有効期限切れがログイン障害の原因になることがあります。

証明書の更新はIdP側の定期的な運用作業ですが、AWS側のIAMアイデンティティプロバイダーに登録されているメタデータを更新しないと、SAMLレスポンスの署名検証が失敗し、フェデレーションログインができなくなります。この記事では、証明書更新時のエラーを即時に解決する方法と、次回以降の更新で同じ問題を発生させないための再発防止策について解説します。SAML連携の基本構成やSSO環境の構築手順についてはKeycloakとAWSのSAML SSO環境構築を参照してください。

あわせて読みたい

KeycloakとAWSのSAML SSO環境構築 ── IdPの設定からSSOログイン確認まで 概要 シングルサインオン（SSO）は、1つのIDとパスワードで複数のサービスにログインできる仕組みです。IdP（アイデンティティプロバイダー）にユーザー情報を集約し、...

 この記事のメリット

• SAML連携における証明書の役割と、証明書更新がログイン障害を引き起こすメカニズムを理解できる
• 証明書更新エラーの即時解決手順（メタデータの再アップロード）を習得できる
• 再発防止策（IdP側での証明書ローテーション）の考え方を把握できる
• 「新しいIdPエンティティの作成」や「アクセスキーの生成」が不適切な理由を理解できる
• SCS試験のSAMLフェデレーションに関する問いに正確に答えられるようになる

 技術解説

SAML連携の基本構成、認証フロー、署名証明書の役割についてはKeycloakとAWSのSAML SSO環境構築の技術解説セクションを参照してください。ここでは、証明書更新に関連するトピックに絞って解説します。

 証明書更新時に障害が発生するメカニズム

IdPの署名証明書には有効期限があり、期限が近づくと新しい証明書への更新（ローテーション）が必要になります。ここで問題となるのが、IdP側で証明書を更新した後にAWS側のメタデータを更新しなかった場合です。

IdPが新しい証明書Bで署名したSAMLアサーションを、AWSが古い証明書Aで検証しようとするため、署名の不一致が発生します。

 即時解決策: メタデータの再アップロード

障害が発生した場合の即時解決策は、IdPから新しいメタデータファイルをダウンロードし、AWS側のIAMアイデンティティプロバイダーにアップロードすることです。

この操作のポイントは以下の通りです。

• 既存のIAMアイデンティティプロバイダーを更新する: 新しいエンティティを作成する必要はありません。既存のエンティティに対してメタデータを上書きアップロードするだけです
• IAMロールの信頼ポリシーの変更は不要: メタデータの更新はIdPエンティティのARNを変更しないため、IAMロールの信頼ポリシーに設定されているプロバイダーARNはそのまま使用できます。なお、IAMロールの信頼ポリシーで参照するSAMLプロバイダーは、そのロールと同じAWSアカウントに存在する必要があります
• 即座に反映される: メタデータのアップロード後、すぐにフェデレーションログインが復旧します

 再発防止策: IdP側での証明書ローテーション

同じ問題を繰り返さないためには、次回の証明書更新時に以下の手順で対応します。

1. 現在の証明書の有効期限が切れる前に、IdP側で新しい証明書を追加する（AD FSではセカンダリ証明書、Keycloakでは新しい鍵プロバイダーの追加に相当する操作）
2. IdPのメタデータファイルを再生成する（この時点でメタデータには旧証明書と新証明書の両方が含まれる）
3. 再生成したメタデータをAWSのIAMアイデンティティプロバイダーにアップロードする
4. 旧証明書の有効期限が切れた後、IdP側でプライマリ証明書を新しい証明書に切り替える

この手順により、証明書の切り替え前後でAWS側のメタデータに新旧両方の証明書が登録されている状態を作れるため、切り替え時にログイン障害が発生しません。

 対応策の比較

 実践

ここでは、KeycloakとAWSのSAML SSO環境構築で構築したSSO環境を使って、Keycloakの署名鍵を更新した後にAWS側のメタデータを更新する手順を実践します。

 前提条件

• KeycloakとAWSのSAML SSO環境構築の手順が完了しており、KeycloakからAWSへのSSOログインが正常に動作する状態
• Keycloakがローカルで起動中（http://localhost:8080、masterレルムを使用）
• IAMアイデンティティプロバイダー Keycloak が作成済み
• IAMロール KeycloakSSORole が作成済み

 手順1: Keycloakで新しい署名鍵を生成する

Keycloak側で新しい署名鍵を生成し、証明書が更新された状態を作ります。

• Keycloak管理コンソール（http://localhost:8080/admin）にログインします。
• レルムが master であることを確認します。
• 左側ナビゲーションの「Realm settings」を選択し、「Keys」タブを開きます。
• 「Providers」タブを選択します。
• 「Add provider」→「rsa-generated」を選択します。
• 以下を設定します。
  • Name: rsa-generated-new（任意の名前）
  • Priority: 現在のプロバイダーより高い値（例: 200）
• 「Save」をクリックします。

Priorityが高い鍵が優先的に使用されます。新しい鍵プロバイダーを追加すると、SAMLアサーションの署名に使用される証明書が自動的に切り替わります。

 手順2: SSOログインの失敗を確認する（任意）

証明書の不一致によるログイン障害を体験します。

• ブラウザで以下のURLにアクセスします。

http://localhost:8080/realms/master/protocol/saml/clients/aws-saml

• Keycloakのログイン画面が表示された場合は、シークレットウィンドウで testuser でログインします。
• AWSへのSSOログインが失敗することを確認します。これは、Keycloakが新しい鍵でSAMLアサーションに署名しているのに対し、AWS側のメタデータには旧証明書が登録されているため、署名検証が失敗するためです。

 手順3: Keycloakから新しいメタデータを取得する

新しい鍵が有効になると、メタデータエンドポイントの内容も自動的に更新されます。以下のコマンドで新しいメタデータを取得します。

curl -o keycloak-metadata-new.xml http://localhost:8080/realms/master/protocol/saml/descriptor

curl -o keycloak-metadata-new.xml http://localhost:8080/realms/master/protocol/saml/descriptor

 手順4: AWS側のメタデータを更新する

• AWSマネジメントコンソールにログインし、上部の検索バーに IAM と入力し、表示された「IAM」を選択します。
• 左側ナビゲーションの「アクセス管理」→「IDプロバイダー」を選択します。
• プロバイダ名「Keycloak」をクリックして詳細画面を開きます。
• 「メタデータ」セクションで現在の「有効期限」の値を確認しておきます。(メタデータドキュメント自体の有効期限であり、X.509証明書の有効期限とは異なる値です。)

• 「メタデータを置換」をクリックします。
• 置き換えの確認で「確認」と入力しますして、「置換」をクリックします。
• 「メタデータドキュメント」の「ファイルを選択」をクリックし、手順3で保存した新しいメタデータファイルを選択します。

• 「変更の保存」をクリックします。
• 詳細画面に戻り、「メタデータ」セクションの「有効期限」が更新されていることを確認します。
  • 画像では同日に設定、再生成した関係で同じ日付になっています。

メタデータの更新後、IAMロールの信頼ポリシーやSAMLプロバイダーのARNは変更されません。関連する設定の修正は不要です。

 手順5: SSOログインの復旧を確認する

• ブラウザで以下のURLにアクセスします。

http://localhost:8080/realms/master/protocol/saml/clients/aws-saml

• AWSマネジメントコンソールにリダイレクトされ、正常にログインできることを確認します。

 証明書ローテーションの再発防止手順（運用参考）

今回の実践では新しい鍵を即座に有効化してログイン障害を体験しましたが、以下の手順でダウンタイムなしの証明書ローテーションが可能です。

1. Keycloakで新しい鍵プロバイダーを追加する（この時点ではPriorityを低く設定し、まだ優先されないようにする）
2. メタデータを再取得してAWSにアップロードする（メタデータに新旧両方の証明書が含まれる）
3. 新しい鍵プロバイダーのPriorityを最高値に変更する（AWS側には既に新証明書が登録されているため、ログイン障害は発生しない）
4. 旧鍵プロバイダーを削除し、メタデータを再度更新する（任意のクリーンアップ）

 まとめ

SAML連携の証明書更新時のエラーは、IdP側の署名証明書とAWS側のメタデータに登録された証明書の不一致が原因です。

この問題の解決にあたって、新しいIAMアイデンティティプロバイダーエンティティを作成する必要はありません。新規作成するとARNが変わるため、IAMロールの信頼ポリシーやアプリケーション設定など関連するすべての設定を修正する必要があり、ダウンタイムが長くなります。

また、アクセスキーとシークレットキーの生成はSAML連携のトラブルシューティングとは無関係です。SAMLフェデレーションは一時的な認証情報を使用する仕組みであり、長期的なアクセスキーを配布することはフェデレーション導入の目的に反します。

SCS試験では、SAML連携のトラブルシューティングにおいて「既存のIdPエンティティを更新する」のか「新しいエンティティを作成する」のかを正確に判断することが求められます。メタデータの上書き更新ではARNが変わらないため追加の設定変更が不要であるという点を押さえておくことが重要です。

 参照先

• SAML 2.0 フェデレーション – AWS IAM
• IAM で SAML ID プロバイダーを作成する – AWS IAM
• SAML 2.0 フェデレーティッドプリンシパルを有効にして AWS マネジメントコンソール にアクセス – AWS IAM
• サードパーティーの SAML ソリューションプロバイダーを AWS に統合する – AWS IAM