このページでは、OpenAM を学認 IdP として構築し、学認フェデレーションに参加させる手順を紹介しています。

学認フェデレーション参加フローについて

　NII が公開している参加フローを考慮して、実際の作業に落とし込むとこのような流れになります。

• 学認フェデレーション参加の準備
  • 組織内調整
  • フェデレーション参加申請内容の確認
  • SAML 署名および HTTPS 証明書取得 　
• 学認 IdP の構築
  • OpenAM に学認に対応した SAML IdP を構築 　
• テストフェデレーション参加
  • オンライン申請
  • テストフェデレーションでの動作確認（上の申請承認後)
    • OpenAM 管理コンソールで動作確認用 SP を追加
    • テストフェデレーションの動作確認用 SP へ SSO し送信属性を確認 　
• 運用フェデレーション参加
  • オンライン申請と書面への記入押印し送付
  • 運用フェデレーションでの動作確認（上の申請承認後)
    • OpenAM 管理コンソールで動作確認用 SP を追加
    • 運用フェデレーションの動作確認用 SP へ SSO し送信属性を確認

以降の章では具体的に解説します。

学認フェデレーションへの参加準備

　IdP 構築作業の前に、学認フェデレーション（テスト、運用）参加申請の内容を理解し、申請と構築設定に矛盾が無いようにする必要があります。 　特に IdP の EntityID や組織が所有するドメイン名（スコープ）は申請とサーバー構築において重要です。（もちろん齟齬が合った場合は、修正は可能ですので怖がる必要はありません。）

組織内調整

　運用フェデレーションの参加申請には、オンライン申請に加えて書面への記入と組織代表者（学長など）の押印を行い、送付することが必要です。

　代表者の押印や、既設の学認 IdP の有無などについては事前に組織内調整をしておくことをおすすめします。

テストフェデレーション申請内容確認

　申請はオンラインで完結します。

　手順の詳細はテストフェデレーション参加手続きの 学認申請システム利用マニュアル（テストFed） を参照ください。

　記入必須項目を以下表にまとめています。それぞれの項目の詳細は申請システムのヘルプ、および運用フェデレーション参加手続きのページにある学認技術運用基準に記載があります。

運用フェデレーション申請内容確認

　申請はオンラインで行い、既設の学認 IdP が無い場合は申請システムから書式をダウンロードし、記入押印して郵送が必要です。

　手順の詳細は運用フェデレーション参加手続きの 学認申請システム利用マニュアル を参照ください。

　必須項目を以下表にまとめています。それぞれの項目の詳細は申請システムのヘルプ、および運用フェデレーション参加手続きのページにある学認技術運用基準に記載があります。

証明書の取得

　以下の２つの用途のために証明書が必要となりますので取得します。

• 構築する学認 IdP へのアクセスに利用する HTTPS 用証明書

• Shibboleth(SAML) アサーションの署名用証明書

　同じ証明書を利用することも、別の証明書を利用することも可能です。

　オンライン申請の入力フォーム内容から公的機関発行ではない組織独自の認証局で発行した証明書も利用可能と思われます。

　すでに OpenAM を HTTPS で運用しているなら、その証明書を流用するのも方法の一つです。

学認IdP構築

　OpenAM に学認に対応した SAML IdP を作成する作業となります。

署名用証明書の用意

　事前準備の章で用意した 以下を２つのファイルを使います。

• 発行された証明書ファイル

• 証明書発行依頼時に作成した秘密鍵ファイル

証明書と秘密鍵の keystore ファイルへのインポート

　keystore ファイルは以下を利用する想定です。

/opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

　発行済みの証明書関連のファイルを以下のように準備します。

　以下のコマンドで証明書と秘密鍵ファイルをまとめて PKCS12 形式のファイルに変換します。

# openssl pkcs12 \
-export \
-in openam.example.ac.jp.crt \
-inkey openam.example.ac.jp.key \
-out openam.example.ac.jp-202608.pkcs12 \
-name gakunin-cert-202608

　 以下の keytool コマンドで変換した PKCS12 ファイルをインポートします。

# keytool -importkeystore \
-srckeystore openam.example.ac.jp.pkcs12 \
-destkeystore /opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks \
-srcstoretype pkcs12 \
-srcalias gakunin-cert-202608 \
-deststoretype jceks \
-destalias gakunin-cert-202608

　 keystore ファイルに新しい証明書/秘密鍵をインポートした場合は、 OpenAM(Tomcat) サービスを再起動します。

# systemctl restart osstech-tomcat

SAMLv2 アイデンティティプロバイダ の作成

　OpenAM の管理コンソールへログインし、対象となる「レルム」を開き、「SAMLv2 プロバイダを作成」を選びます。

　 「ホストアイデンティティープロバイダの作成」を選びます。

　 「SAMLv2アイデンティティプロバイダの作成」画面で、「メタデータの項目」をそれぞれ入力します。

作成した IdP の学認向けの設定変更

　画面上部のメニューから 「連携」 を押し、「エンティティープロバイダの一覧」から先程作成した IdP の EntityID を選びます。

　「表明コンテンツ」タブの 「NameID の書式リスト」 から 「urn:oasis:names: tc:SAML:2.0:nameid-format:persistent」 を削除し、画面右上の 「保存」 を押します。

　アカウントマッパーの 「Disable NameID Persistence:」 のチェックボックスにチェックを入れ、画面右上の 「保存」 を押します。

　属性定義用スクリプトで 「SAML Attribute Resolution Script」 を選択し、画面右上の 「保存」 を押します。

学認用属性送信の設定

　学認サービス (SP) 毎に送信が必要な属性は違います。

　 「表明処理」 タブを開き、 「属性マップ」 に送信する学認用属性の定義を追加します。

　例として eduPersonPrincipalName(ePPN) を、ユーザープロファイル(LDAP)に保存された eduPersonPrincipalName 属性値で送信する場合の定義を追加しています。

以下の値を 「新しい値」 に入力し、追加します。

　[=]の左辺は ePPN の OID です。右辺は LDAP 属性名となります。

　※LDAP値を使わずにスクリプトで生成する場合は生成される値名を設定します。

urn:oid:1.3.6.1.4.1.5923.1.1.1.6=eduPersonPrincipalName

「現在の値」 に表示されることを確認し、右上から 「保存」 します。

　ePPN 以外にも学認属性を送信する場合は、以下 URL の属性リストを参考に OID と LDAP 属性(又はスクリプト値)のマッピングを設定します。

属性リスト

https://meatwiki.nii.ac.jp/confluence/pages/viewpage.action?pageId=12158166

SAML エンドポイントの変更

　OpenAM に SAML IdP を構築すると規定でエンドポイントが設定されます。 　学認フェデレーションの申請をすると、Shibboleth IdP を基準としたエンドポイントがメタデータに含まれます。

　OpenAM と Shibboleth IdP ではエンドポイントに差異がありますので、今回は OpenAM の SAML エンドポイントを、Shibboleth IdP のエンドポイントと同じになるよう変換する設定をします。

　設定箇所は2箇所です。

OpenAM の管理コンソールでの設定変更

　IDP設定の「サービス」タブにて、「MetaAlias」 を確認します。ここでは 「idp」 となっています。


「IDPサービス属性」 の 「シングルサインオンサービス」 の以下2箇所を書き換え保存します。


Apache の URL 変換設定

　ここでは、OpenAM(Tomcat) の前段に配置する Apache サーバーにて変換をします。 　「idp」 部分は構築した際に振られるMetaAlias名となりますので、上の サービスタブ にて確認して下さい。 　Apache の設定ファイル httpd.conf 又は httpd.conf から Include されるファイルに以下の URL 変換用設定をを記載します。

RewriteEngine on

RewriteRule /idp/profile/SAML2/Redirect/SSO　/openam/SSORedirect/metaAlias/idp [PT]

RewriteRule /idp/profile/SAML2/POST/SSO　/openam/SSOPOST/metaAlias/idp [PT]

　Apache 設定変更後は、Apache(httpd) サービスを再起動します。

systemctl restart httpd

　以上で学認 IdPの構築は完了です。

テストフェデレーションへの参加

オンライン IdP 申請

　テストフェデレーション参加手続きの 学認申請システム利用マニュアル（テストFed） を参考に、Orthrosにアカウントを作りオンライン申請をします。

　新規 IdP 申請が通ると、テストフェデレーションのメタデータに自組織 IdP のメタデータが追加され、テストフェデレーションに参加している SP へ 学認連携 SSO できる状態となります。

メタデータ自動更新設定とメタデータ読み込み

　学認では参加している全ての IdP、SP のメタデータを一纏めにして公開しています。常に最新のメタデータを取得して関連する SP のメタデータ内容に変更が発生した際は、 OpenAM 内の SP 登録内容を更新する必要があります。

　この処理を自動的に行うサービスを設定します。

テストフェデレーションメタデータ署名証明書の keystore へのインポート

　公開されているメタデータには検証のため署名されていますので、検証を行うテストフェデレーションメタデータの証明書をインポートします。

　keystore ファイルは以下を利用する想定です。

/opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

　証明書ファイルを以下の URL から取得し OpenAM サーバーへコピーします。

https://metadata.gakunin.nii.ac.jp/gakunin-test-signer-2020.cer

　以下の keytool コマンドを実行します。

keytool -importcert \
-alias gakunin-test-signer-2020 \
-noprompt \
-trustcacerts \
-storetype jceks \
-file gakunin-test-signer-2020.cer \
-keystore /opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

キーストアのパスワードを聞かれますので入力します。

キーストアのパスワードを入力してください:

成功すれば以下のように表示されます。

証明書がキーストアに追加されました

正常にインポートできたかどうか、以下のコマンドを実行し、キーストアパスワードを入力し 「gakunin-test-signer-2020」 が追加されていることを確認します。

keytool -list \
-alias gakunin-test-signer-2020 \
-storetype jceks \
-keystore /opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

キーストアのパスワードを入力してください:

**gakunin-test-signer-2020**,2025/06/16, trustedCertEntry,

Certificate fingerprint (SHA-256):
FA:11:11:5B:EC:13:4D:55:85:AF:60:32:E1:6C:01:01:EF:9C:A0:6B:17:8C:8B:9C:7F:2B:69:41:EB:68:30:1E

~~後略~~

　keystore ファイルに新しい鍵、証明書をインポートした場合は、OpenAM(Tomcat) サービスを再起動します。

# systemctl restart osstech-tomcat

テストフェデレーションメタデータ自動更新設定

　OpenAM 管理コンソールへログインし、対象レルムの左からサービスを開き、 サービスの追加 からサービスタイプ SAMLv2メタデータの自動更新 を選び、この画面では特に変更はせずに 作成 押します。

　一旦作成後の画面にて詳細の値を追加します。

　メタデータのURLとバックアップ先のマッピングは以下の値を入力して追加します。

以下の値を設定して 変更の保存 を押します。

　問題なく動作するか確認するため、手動でメタデータ読み込みを実行します。

　設定画面とは別のタブを開き、以下のURLへアクセスします。realmは実際に利用するレルムを指定します。

https://openam.example.ac.jp/openam/saml2/jsp/reload.jsp?realm=/

　画面に 「Complete」 と表示されればメタデータ読み込み成功です。

テストフェデレーションテスト用SPの登録

　SAMLv2メタデータの自動更新 サービス設定を開き、テスト用に用意されているSPを登録します。

　「対象とするエンティティ」にテスト用SPのエンティティIDを追加し、変更を保存します。

　ここでは、 「https://test-sp2.gakunin.nii.ac.jp/shibboleth-sp」 を追加しています。

　設定画面とは別のタブを開き、以下のURLへアクセスします。realmは実際に利用するレルムを指定します。

https://openam.example.ac.jp/openam/saml2/jsp/reload.jsp?realm=/

　 　画面に 「Complete」 と表示された後、 「連携」 メニューより、「エンティティプロバイダ」 の一覧に追加したSPがあることを確認します。

　 　「連携」タブの「トラストサークル」から 「gakunin 」を開き該当の SP を追加します。

　 　以下のように表示されればトラストサークルへの追加完了です。

送信属性の設定

　テスト用 SP に送信する学認用属性の設定をします。

　このドキュメントでは、IdP の送信設定を利用するので設定はしません。

　実運用で IdP の設定ではなく、SP 毎に送信する属性を指定する場合や、スクリプト等で生成する場合は、OpenAM 学認設定ガイドの 2.8学認で利用する属性の生成 、 2.9学認で利用する属性の送信設定 を参照して下さい。

テストフェデレーションのテスト

　テストフェデレーションの新規 IdP 申請が通ったことを確認した後に、テスト用の SP で IdP から送信された属性を確認します。

　シーケンスとしては、以下のような動作となります。　学認フェデレーションは SAML をベースとした Shibboleth プロトコルを利用しています。

　追加したテスト用 SP の URL https://test-sp2.gakunin.nii.ac.jp/ へアクセスします。

　「接続テスト（スコープ制限なし・affiliation 制限なし）」 を押します。

　学認 IdP を選択する学認のディスカバリーサービス画面にて、プルダウンより、自組織を選び 「選択」 を押します。

　OpenAM のログイン画面へリダイレクトされますので、ログインします。

　OpenAM へログインが完了すると、テスト用 SP へ SAML アサーションが送信され、SP が受信した属性確認画面が表示されます。

　ここでは、IdPによるSSO連携の確認と、IdPの学認用属性送信が正しく送信されているか確認できます。

　以上で、テストフェデレーションの参加とテストは完了です。

　運用フェデレーションへの参加に進みます。

運用フェデレーションへの参加

　前提条件としてテストフェデレーションに参加済みである必要があります。

運用フェデレーションの新規IdP申請

　運用フェデレーション参加手続きの 学認申請システム利用マニュアル に記載されている案内に従ってオンラインで申請を行います

　テストフェデレーションの場合と同じく、Orthros アカウントを使い、オンラインで新規 IdP 申請します。

　オンラインで申請し、 参加・設置申請書 に必要事項を記入、押印し書類を郵送します。

　申請が通ると、運用フェデレーションメタデータに構築した学認 IdP のメタデータが追加され、運用フェデレーションに参加している SP へ学認連携 SSO できる状態となります。

メタデータ自動更新設定とメタデータ読み込み

　運用フェデレーションのメタデータを読み込む設定を行います。

　テストフェデレーションの時に行った作業と同じですが、対象 URL と証明書が違います。

運用フェデレーションメタデータ署名証明書の keystore ファイルへのインポート

　取得したメタデータファイルの検証を行う証明書をインポートします。

　 　keystore ファイルは以下を利用する想定です。

/opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

　 　証明書ファイルを以下の URL から取得し OpenAM サーバーへコピーします。

https://metadata.gakunin.nii.ac.jp/gakunin-signer-2017.cer

　 以下の keytool コマンドを実行し、キーストアパスワードを入力してインポートします。

keytool -importcert \
-alias gakunin-signer-2017 \
-noprompt \
-trustcacerts \
-storetype jceks \
-file gakunin-signer-2017.cer \
-keystore /opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

　 　キーストアのパスワードを聞かれますので入力します。

キーストアのパスワードを入力してください:

　 　成功すれば以下のように表示されます。

証明書がキーストアに追加されました

　 　正常にインポートできたかどうか、以下のコマンドを実行し、キーストアパスワードを入力し gakunin-signer-2017 が追加されていることを確認します。

keytool -list \
-alias gakunin-signer-2017 \
-storetype jceks \
-keystore /opt/osstech/var/lib/tomcat/data/openam/openam/keystore.jceks

キーストアのパスワードを入力してください:

**gakunin-signer-2017**,2025/06/24, trustedCertEntry,

Certificate fingerprint (SHA-256):
5E:D6:A8:C5:E9:30:49:3F:B4:BA:77:54:6A:FB:66:

~~後略~~

　 　keystore ファイルに新しい鍵をインポートした場合は OpenAM(Tomcat) を再起動します。

# systemctl restart osstech-tomcat

運用フェデレーションメタデータ自動更新設定

　OpenAM 管理コンソールへログインし、対象レルムの左から「サービス」を開き、サービスタイプ 「SAMLv2メタデータの自動更新」 を開きます。

　既にテストフェデレーション用メタデータの情報があるので、運用フェデレーションメタデータの URL とバックアップ先のマッピングは以下の値を入力して追加します。

変更の保存 を押します。

　問題なく動作するか確認するため、手動でメタデータ読み込みを実行します。

　設定画面とは別のタブを開き、以下の URL へアクセスします。realm は実際に利用するレルムを指定します。

https://openam.example.ac.jp/openam/saml2/jsp/reload.jsp?realm=/

　画面に 「Complete」 と表示されればメタデータ読み込み成功です。

運用フェデレーションテスト用 SP の登録

　「SAMLv2メタデータの自動更新」 サービス設定を開き、テスト用に用意されている SP を登録します。

　「対象とするエンティティ」にテスト用 SP のエンティティIDを追加し、変更を保存します。

　ここでは、 「https://attrviewer20.gakunin.nii.ac.jp/shibboleth-sp」 を追加しています。

　設定画面とは別のタブを開き、以下の URL へアクセスし手動で最新メタデータ読み込みを実行し、テスト用 SP の追加登録します。realm は実際に利用するレルムを指定します。

https://openam.example.ac.jp/openam/saml2/jsp/reload.jsp?realm=/

　画面に 「Complete」 と表示された後、 「連携」 メニューより、 「エンティティプロバイダ」 の一覧に追加した SP があることを確認します。

　「連携」タブのトラストサークルから 「gakunin」 を開きトラストサークルへ追加します。

　以下のように表示されればトラストサークルへの追加完了です。

送信属性の設定

　テスト用 SP に送信する学認用属性の設定をします。

　ここではテストとして、IdP の学認用属性送信設定を利用するので、特に設定は不要です。

フェデレーションのテスト

　運用フェデレーションの新規 IdP 申請が通ったことを確認した後に、テスト用の GakuNin SP で IdP から送信した属性を確認します。

　SPとして追加したテスト用 SP の 以下 URL へアクセスします。

https://attrviewer20.gakunin.nii.ac.jp/

「接続テスト（スコープ制限あり・affiliation 制限あり）」 を押します。

　学認 IdP を選択する学認のディスカバリーサービス画面にて、プルダウンより、自組織を選び 「選択」 を押します。

　OpenAM のログイン画面へリダイレクトされますので、ログインします。

　OpenAM へログインが完了すると、テスト用 SP へ SAMLアサーションが送信され、テスト用 SP が受信した属性確認画面が表示されます。

　ここでは、IdP による学認連携の確認と、属性が正しく送信されているか確認できます。

　以上で、運用フェデレーションの参加とテストは完了です。