OpenAM を学認 IdPとして利用する利点

　OpenAM はオープンソースのシングルサインオン(SSO)ソフトウェアです。

　SAML、OpenID Connect、OAuth2.0、WS-Federation などの SSO プロトコルに対応した認証基盤を構築でき、さらに OSSTech 版の OpenAM では学認 IdP として利用可能な機能が強化されています。

　パスキー、ワンタイムパスワード、アダプティブリスクなど利用して、柔軟な多要素認証フローを作成する機能や、冗長化機能を標準搭載しています。

　また動作用の Tomcat を同梱しており、O.S から上のミドルウェアはワンストップでサポートされます。

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

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

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

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

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

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

　既に Shibboleth IdP 等で学認参加している組織で OpenAM の学認 IdP に移行される場合は、OpenAM 学認設定ガイドを参照ください。

組織内調整

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

既に機関の学認 IdP があり、申請担当者の eduPersonPrincipalName(ePPN) がある場合はオンラインで手続き完結できますので、ePPN 値の確認を行ってください。

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

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

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

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

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

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

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

証明書の取得

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

構築する学認 IdP へのアクセスに利用する HTTPS 用証明書
Shibboleth(SAML) アサーションの署名用証明書

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

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

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

　今後、公的な認証局が発行する HTTPS 用の証明書は有効期間が短くなっていくことが想定され、HTTPS と SAML 署名用に同じ証明書を利用し、証明書を更新していくメンテナンスコストも鑑みる必要があります。

学認IdP構築

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

　運用上はテストフェデレーションと運用フェデレーションの IdP は、分けて構築した方がテストや検証がしやすいですが、説明が長くなるので同じ IdP を使う想定で記載します。
　IdP を分けて複数構築する場合は EntityID とエンドポイント URL をそれぞれ異なるものにする必要があります。

OpenAM 環境の初期設定、構築は完了している想定です。

完了していない場合は、OpenAM 14 初期設定ガイドを参考に OpenAM の初期設定をして下さい。

署名用証明書の用意

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

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

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

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

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

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

種類	ファイル名(例)
証明書ファイル	openam.example.ac.jp.crt
秘密鍵ファイル	openam.example.ac.jp.key

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

「-name」オプションには証明書の有効期限を含んだ文字列を指定すると管理上識別しやすいです。

# 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 の識別子 (EntityID) です。　他組織との重複を避けるために、利用者が IdP へアクセスする URL を利用するのが一般的です。　既定値ではポート番号(:443)が入っていますが削除します。
署名鍵	keystore ファイルにインポートしたSAML 署名鍵のエイリアスを選択します。
新しいトラストサークル	学認専用に作成します。名前は任意です。ここでは gakunin としています。
ベースURL	ロードバランサーを利用して冗長化し、実ホスト名(FQDN)と利用者がアクセスする URL が異なる場合、利用者がアクセスする URL を指定します。

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

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

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

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

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

学認用属性送信の設定

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

　ここで紹介する方法は、IdP が全ての SP に同じ属性を送信する利用方法の場合の設定です。

SP　毎に違う属性を送信したい場合は、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

属性	マッピング例
mail	urn:oid:0.9.2342.19200300.100.1.3=mail
o	urn:oid:2.5.4.10=o
displayName	urn:oid:2.16.840.1.113730.3.1.241=displayName
eduPersonAffiliation	1.3.6.1.4.1.5923.1.1.1.1=eduPersonAffiliation
eduPersonScopedAffiliation	1.3.6.1.4.1.5923.1.1.1.9=eduPersonScopedAffiliation
eduPersonTargetedID	1.3.6.1.4.1.5923.1.1.1.10=eduPersonTargetedID

SAML エンドポイントの変更

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

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

　学認申請時に「カスタムメタデータのアップロード」で OpenAM のメタデータをアップロードする場合は、学認メタデータに含まれるエンドポイントを OpenAM 既定のエンドポイントにできるため本作業は不要です。

　設定箇所は2箇所です。

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

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

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

エンドポイント	書き換え前※実際は一行です。	書き換え後※実際は一行です。
HTTP-REDIRECT	https://openam.exapmle.ac.jp/ openam/SSORedirect/metaAlias/idp	https://openam.exapmle.ac.jp/ idp/profile/SAML2/Redirect/SSO
POST	https://openam.exapmle.ac.jp/ openam/SSOPOST/metaAlias/idp	https://openam.exapmle.ac.jp/ idp/profile/SAML2/POST/SSO

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にアカウントを作りオンライン申請をします。

　SAML 署名用の証明書の更新や、IdP URL の変更などのメンテナンスでログインする機会がありますので、学認 IdP 運用中は作成した 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とバックアップ先のマッピングは以下の値を入力して追加します。

キー	値
https://metadata.gakunin.nii.ac.jp/gakunin-test-metadata.xml	/opt/osstech/var/lib/tomcat/data/openam/openam/gakunin-test-metadata.xml

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

項目	設定値
実行時間	04:00:00
対象とするロール	なし
エンティティの新規登録を許可する	オン
有効期限をチェックする	オン
署名を検証する	オン

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

　設定画面とは別のタブを開き、以下の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 申請します。

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

※組織の代表印が必要となりますので、組織内での調整等の時間も考慮する必要があります。

以下引用

事務局により内容のチェックが行われると通知メールが届きます。印刷用の参加・設置申請書のPDFファイルが学認申請システムからダウンロードできるようになりますので、印刷・押印して国立情報学研究所に送付してください。
なお，新規IdP/SP設置時には機関の長（学長，理事長，CEO，社長，代表取締役など，機関代表者）の記名・公印の押印が必要となります。

　申請が通ると、運用フェデレーションメタデータに構築した学認 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 とバックアップ先のマッピングは以下の値を入力して追加します。

キー	値
https://metadata.gakunin.nii.ac.jp/gakunin-metadata.xml	/opt/osstech/var/lib/tomcat/data/openam/openam/gakunin-metadata.xml

変更の保存 を押します。

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

　設定画面とは別のタブを開き、以下の 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 の学認用属性送信設定を利用するので、特に設定は不要です。

　※本運用では SP 毎のドキュメントを参照して、送信する属性の設定をして下さい。

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

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

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

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

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

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

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

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

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

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

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

　実際に学認サービス (SP) を追加して SSO の運用を開始される際は、「運用フェデレーションテスト用 SP の追加」を参考に新規 SP 追加する手順となります。
　SP に送信が必要な属性は追加する学認サービスの情報を確認してください。