更新 2022/01/04

WebClass を Shibboleth でSSO連携させるための設定です。

前提

WebClass の Web サーバは１台で、自身の Apache にSSL証明書をインストールして HTTPS で公開しているものとします。もしWebサーバを複数台で構成している場合は、Web分散構成における Shibboleth SP の設定 も参考にしてください。

Shibboleth SP v3 のインストールと、Apache 2.4 に対して shibboleth sp module をロードさせるところまでは完了しているものとします。

• wiki.shibboleth.net : SP3/LinuxInstall
• meatwiki.nii.ac.jp : 貴学にてSPをインストールする場合の構築手順
• Debian でに SP3 インストール方法
• RHEL7/8 でインストール

ここでは Shibboleth SP の立場で設定確認し、IDP は管理下にないために自身ではIDP設定ファイルを設定・参照できず、場合によっては IDP 管理者に対して登録・確認をお願いしながら設定するオペレーションを想定します。

 

IDP 管理者との事前の取り交わし事項

Shibboleth IDP と WebClass の Shibboleth SP がやり取りできるようにするため、事前の設定のすり合わせが必要です。以下を確認します。

• Shibboleth IDPの情報
  • Entity ID
  • MetadataProvider
    • URLおよびフォーマット、もしくはファイルで提供されるのか
• WebClass に設定する Shibboleth SP の情報
  • Entity ID
  • sp-metadata.xml
    • WebClass用にShibboleth SP のPKI鍵ペアを生成し、公開鍵と EntityID を sp-metadata.xml にパッケージングしてIDP管理者に提出します。
  • attribute-map.xml に追加する属性項目
    • WebClassが ShibbolethIDP から受け取る利用者情報です。WebClassの認証に必要です。

Shibboleth SP の設定ファイルを用意しながら確認していくことができます。

キーペアの作成

Shibboleth SP が IDP とのPKI 暗号通信を行うための、SP 用のキーペアを用意します。

検証など簡便に済ませるケースでは、Web サーバに設定した SSL の秘密鍵と証明書を流用することもあります。

キーペアを新たに作成するには keygen.sh を使います。（使い方）

sp-metadata.xml の作成

キーペアの用意と SP の EntityID を決めたら、これらをパッケージングした sp-metadata.xml を作成します。

Shibboleth SP に metagen.sh というスクリプトが用意されています。以下のように使います。

$ ./metagen.sh -c sp-cert.pem -h your.host.name -e "https://your.host.name/shibboleth-sp" > sp-metadata.xml

注意点として、-h オプションでホスト名を指定するだけで自動的に EntityId もそれらしく埋めてくれるのですが、最後に"-sp" はつけてくれません。慣例としてshibboleth-sp と最後に着けることが多いので、EntityId は明示的に指定して利用するほうが確実です。

出来上がったら IDP 管理者に提出します。

SP では sp-metadata.xml は使用しません。

shibboleth2.xml ファイルの用意

主に以下の４点を設定します

• SP EntityID
• IDP EntityID
• IDP Metadata Provider
• SP Key Pair

SP の EntityID を埋め込みます

    <ApplicationDefaults entityID="https://your.host.name/shibboleth-sp"

IDP の EntityID を埋め込みます

    <SSO entityID="https://some.idp.host.name/idp/shibboleth"
                 discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
      SAML2
    </SSO>

IDP メタデータプロバイダの指定を修正します。idp のメタデータをファイルで直接受け取っている場合は、ファイルパス指定します。もしくは、SPが自動的にダウンロードして取得する運用形態の場合は、IDP管理者よりURLを指定されるはずです。

        <!-- Example of locally maintained metadata. -->
        <MetadataProvider type="XML" validate="true" path="idp-metadata.xml"/>

        <!--
        <MetadataProvider type="MDQ" validate="true" cacheDirectory="mdq"
                baseUrl="http://mdq.federation.org" ignoreTransport="true">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
            <MetadataFilter type="Signature" certificate="mdqsigner.pem" />
        </MetadataProvider>
        -->

用意した SP のキーペアを指定します。SP v3 ではデフォルトではキーペアを２種類分けて２つ <CredentioalResolver> の指定が書かれています。v2 ではだいたい１つのキーペアで設定することが多いと思いますので、その設定方法を継承する場合は下記の通り書き直します。

    <!--  コメントアウト
    <CredentialResolver type="File" use="signing"
            key="sp-signing-key.pem" certificate="sp-signing-cert.pem"/>
    <CredentialResolver type="File" use="encryption"
            key="sp-encrypt-key.pem" certificate="sp-encrypt-cert.pem"/>
    -->
    <!-- 追加 -->
    <CredentialResolver type="File" key="sp.key" certificate="sp.crt"/>

attribute-map.xml に追加する属性項目

利用者がShibbolethのSSOで WebClassを開くときは、まず Shibboleth のログイン画面で認証し、成功するとShibboleth により自動的に利用者の情報が WebClass に渡されます。この情報に基づいて WebClass にログインします。この時Shibboleth からWebClass に渡される利用者情報について、Shibboleth IDP, Shibboleth SP, WebClass の三者ですり合わせておく必要があります。

WebClass が必要とするデータは、WebClassのアカウントデータベースで管理しているユーザIDやログインIDに当たるデータです。もし Shibboleth IDP が LDAP からアカウント情報を引用している場合は、attribute-map.xml に以下のような記述がコメントアウトされている中から、必要なものを有効化します。

    <!-- Older LDAP-defined attributes (SAML 2.0 names followed by SAML 1 names)... -->
    <!--
    <Attribute name="urn:oid:2.5.4.3" id="cn"/>
    <Attribute name="urn:oid:2.5.4.4" id="sn"/>
    <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
    -->
    <!-- ここでは例として、LDAP の uid 属性を送ってもらう -->
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>

実際にこの情報が IDP から得られるかどうか確認する必要があるので、attribute-map.xml の編集結果は IDP 管理者に見てもらうなどして、すり合わせておきます。

ほとんどの場合、attribute-map.xml にもともと書いてある内容から書き加えたり書き換えることなく、コメントで無効化したり有効化するだけで調整すると思います。

Shibboleth SP の設定確認

上記の設定をしたうえで shibboleth sp のプロセスと apache をリスタートします。どちらも設定をロードします。

https://localhost/Shibboleth.sso/Status を開くことで最終確認できます。問題なければ、設定された SP 証明書情報が書き出され、また出力の最後の方に <Status><OK/></Status> が書き出されています。

shibboleth のログにある shibd.log もしくは shibd_warn.log を確認すると、プロセススタート時の状況が確認でき、各種設定ロードに問題がなかった確認できます。もし<Status><OK/></Status> を得られなかった場合に確認します。

• SP公開鍵とSP秘密鍵のロード、キーペアのチェック
• IDPメタデータプロバイダのロード
• attribute-map の内容のロード
• など

以上をクリアすれば、SP単体としての設定は完了です。

IDP との連携確認

WebClass の領域をシボレスで保護する設定を加え、Apache を再起動します。

WebClassのシステムオプションで、以下を設定します。SHIBBOLETH_ENVNAME_USERID の値は、IDP から受け取る attribute のIDをご確認ください。

SHIBBOLETH_ENABLE = 1
SHIBBOLETH_ENVNAME_USERID = uid

WebClass を /webclass/login.php?auth_mode=SHIB のURLで開くと、Shibboleth でのログインができます。最初は自動的にIDPログイン画面への転送され、IDPでの認証通過後にWebClassに戻ってきて自動的にWebClassログインします。

IDP と SP との連携の様子は transaction.log で確認することができます。特に、IDP から受け取った属性IDが書き出されます。

IDP に転送されるが、IDP のエラー画面が表示されるとき

IDP に SP メタデータが登録されていないか、SP の EntityID が間違って登録されている可能性があります。shibboleth2.xml に記入した EntityID、IDP に提出した sp-metadata.xml に記入した EntityID を確認の上、IDP管理者と相談してください。

IDP でログインすると、WebClassのログイン画面に戻る

うまくいけば、WebClass のログイン後の画面が開くはずです。WebClassのログイン画面が表示されるということは、Shibboleth の IDP と SP の連携はうまくいっていますが、WebClass 自体にログインできていないことを意味します。

この場合に疑われるのは以下の３点です。

• WebClassのログインURLをご確認してください。 login.php?auth_mode=SHIB というURLでログインします。開いたURLでは、auth_mode の指定がなかったかもしれません。
• WebClassのアカウントがないかもしれません。shibboleth から受け渡されるユーザIDが WebClass に登録されているか確認します。
• Shibboleth IDP からユーザIDの属性情報を受け取れていないかもしれません。

このうち、下の２つは IDP から送られてくる属性情報が関係します。transaction.log を確認し、uid 属性が得られたか確認してください。

TransactionLogの確認方法

IDP との細かな連携の確認では、transaction.log が有効な手掛かりになります。

transaction.log の出力フォーマットは Shibboleth SP v3  では shibboleth2.xml で次にようにして指定しています。

<OutOfProcess tranLogFormat="%u|%s|%IDP|%i|%ac|%t|%attr|%n|%b|%E|%S|%SS|%L|%UA|%a" />

フォーマットの1つ1つの意味は https://wiki.shibboleth.net/confluence/display/SP3/Logging で確認できます。%attr は受け取った属性のIDです。

もし uid の値を受け取っていれば、uid(1) のように書き出されています。受け取った値はわかりませんが、uid 属性の値を１つ受け取ったことがここから読み取れます。

設定をしていたとしても、値を受け取っていない属性については、属性IDが書き出されません。

SPのデバッグログ出力

問題の原因がなかなか特定できない時、またその状況を相談したい時などでは、設定ファイルの情報に加えて、ログが重要な手がかりになります。

もし、より詳細に SP の動作を追跡して確認したい場合は、ログを DEBUG レベルで出力する設定に変える方法があります。ログの出力レベルは shibd.logger という設定ファイルで変更できます。場所は分かれていますが、以下のような設定の行があります。INFOをDEBUGに変えて shibd をリスタートすることで、shibd.log の出力が詳細になります。書き方を間違えていると、ログが出力されなくなることがあります。

log4j.rootCategory=INFO, shibd_log, warn_log

log4j.category.Shibboleth-TRANSACTION=INFO, tran_log

なお、DEBUG レベルで出力するとSPの処理状況に加えて、IDP とやり取りしたデータも書き出されます。セキュリティの面でも一般運用には向きませんので、あくまでも一時的な設定とし、運用開始前に出力レベルを下げるべきです。

その他の点検事項

log rotation

Shibboleth SP v3 ではsyslog にログを転送するのが推奨されています。

https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335687/Rotate+Log+Files

このページにもあるv2の資料が残っていて、Shibboleth SP は Log4shib というライブラリがログを管理しています。ログローテーションについては以下の資料があります。

https://shibboleth.atlassian.net/wiki/spaces/SHIB2/pages/2577072365/NativeSPLogRotation

要するに shibd.logger でローテーション設定されており、デフォルトではログファイルサイズが １MB に達するごとに自動的にローテートしてくれます。このデフォルト設定はソースビルドしてインストールしても、rpm インストールしても、どちらでも同じです。

１MB がどのようなタイミングになるかはシステムのアクセス数などによりますので、ログの保存期間ポリシーなどに対応させて１日などの単位で区切りたい場合は別途 logrotate 等を使ったローテーション設定に切り替えます。