2. 自建Shibboleth SP接入(Joining CARSI for Shibboleth SP)

Owned by carsi_pku_team
Last updated: Nov 10, 2023
4 min read

技术调试前需做的准备(Preparation before technical debug)：

        1.请确保已完成CARSI SP申请和接入流程 (CARSI SP joining process)的前七个步骤（第一步~第七步）。

        1.Please ensure that you have completed Steps 1 to 7 of CARSI SP申请和接入流程 (CARSI SP joining process).

        2.请仔细阅读 CARSI基本调试要求（CARSI Basic Debugging Requirements）。

        2.Please read CARSI基本调试要求（CARSI Basic Debugging Requirements） carefully.

       

技术调试 (Technical debug with CARSI)：

1. 向CARSI联盟提交SP配置信息(Add SP info into CARSI)

        审批通过后，登陆 CARSI会员自服务系统。

        Once the membership is approved, login CARSI Online Helpdesk.

     

  在“我的CARSI->SP管理”中，选择“添加SP”，按照提示完成添加 SP并上传metadata文件。

        On MyCarsi->SP Mgmt(SAML) page, click Add SP, follow the hints to add your SP and its metadata.

        添加完SP后，该SP即合并到CARSI联盟的预上线环境metadata中：https://www.carsi.edu.cn/carsimetadata/carsifed-metadata-pre.xml。

        Once added, the metadata of this SP would be merged into CARSI pre-production environment: https://www.carsi.edu.cn/carsimetadata/carsifed-metadata-pre.xml.

        请将此metadata加入到SP本地的MetadataProvider中，可参考以下步骤进行配置：

        Please configure your SP to use this metadata in MetadataProvider, for example:

        a. 将SSO配置为CARSI的SAMLDS服务：

        a. set SSO discoveryURL to be CARSI SAMLDS service (pre-production):

<SSO discoveryProtocol="SAMLDS" discoveryURL="https://dspre.carsi.edu.cn/ds/index.html">
               SAML2
</SSO>

        b. 添加CARSI的metadata到MetadataProvider中：

        b. Add CARSI pre-production metadata to MetadataProvider:

<MetadataProvider type="XML" url="https://www.carsi.edu.cn/carsimetadata/carsifed-metadata-pre.xml"            
backingFilePath="/etc/shibboleth/carsifed-metadata-pre.xml" legacyOrgNames="true" reloadInterval="600" >
</MetadataProvider>

        这是一个新安装SP的环境配置，仅供参考：

        These are the steps for installing a new SP, just for your reference:

#通过yum源的方式安装(install through yum)
[root@www ~]# wget http://download.opensuse.org/repositories/security://shibboleth/CentOS_7/security:shibboleth.repo -P /etc/yum.repos.d
[root@www ~]# yum install shibboleth
[root@www ~]# systemctl start shibd  
[root@www ~]# systemctl enable shibd
[root@www ~]# systemctl restart httpd

#配置SP受保护资源目录(config producted dir)
[root@www ~]# vi /etc/httpd/conf.d/shib.conf
#line 49
<Location /secure> /secure 指的是受保护资源的目录，按照需要自行修改  protected dir, change it based on your demand

#配置SP entityID(config SP Entity ID)
[root@www ~]# vi /etc/shibboleth/shibboleth2.xml

#将(replace)：
ApplicationDefaults entityID="https://sp.example.org/shibboleth"
#改为(with)：
ApplicationDefaults entityID="https://[sp域名]/shibboleth"

#将(replace)
<SSO entityID="https://idp.example.org/idp/shibboleth" discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
               SAML2
</SSO>
#改为(with)
<SSO discoveryProtocol="SAMLDS" discoveryURL="https://dspre.carsi.edu.cn/ds/index.html">
               SAML2
</SSO>

#在<ApplicationDefaults>代码块内增加（/etc/shibboleth/carsifed-metadata-pre.xml为待生成的metadata备份文件）    Add in <ApplicationDefaults> block(/etc/shibboleth/carsifed-metadata-pre.xml is the backup metadata file to be generated)

<MetadataProvider type="XML" url="https://www.carsi.edu.cn/carsimetadata/carsifed-metadata-pre.xml"            
backingFilePath="/etc/shibboleth/carsifed-metadata-pre.xml" legacyOrgNames="true" reloadInterval="600" >
</MetadataProvider>

[root@www ~]# systemctl start shibd  
[root@www ~]# systemctl enable shibd
[root@www ~]# systemctl restart httpd

2.在预上线环境进行认证测试(Test on pre-production environment)

        访问待测试SP应用的CARSI登录链接，参考文档IdP4：访问CARSI资源门户 （通过浏览器）的步骤，使用联盟提供的测试IdP及其账号（发送邮件到carsi@pku.edu.cn获取），在预上线环境测试SP服务。可根据SP访问控制的需要，检查IdP用户属性是否正常。

        Visit the CARSI login url of your SP, refer to IdP4：访问CARSI资源门户 （通过浏览器）, use the test IdP and test account provided by CARSI (Send a mail to carsi@pku.edu.cn to apply a test IdP and test account) to test this SP on CARSI pre-production environment. Please pay attention to the attributes released by the IdP.

3.SP服务页面标明是CARSI会员(Add a CARSI entrance on SP service page)

        CARSI联盟建议会员单位在SP服务主页面或用户登录页面，以醒目方式（如放置logo）标明我单位为CARSI 身份联盟会员或提供独立的CARSI登录入口。参见 使用CARSI logo。

        CARSI suggests SP add a CARSI entrance (eg. logo) on SP home page or login page, so the end users could easily find this entrance. You can find CARSI logo here: 使用CARSI logo。

4.CARSI产品环境试运行(Trail run your SP on CARSI production environment)

        请参照模板（用户访问指南&IdP添加指南模板（User Visit Guide & IdP Appending Guide templates））准备两份文档。

        Refer the templates 用户访问指南&IdP添加指南模板（User Visit Guide & IdP Appending Guide templates）, prepare User Visit Guide & IdP Appending Guide docs.

        准备好以后，请发送邮件给 carsi@pku.edu.cn，申请在CARSI产品环境上线试运行，并将上述2份文档作为附件提供。我们会根据您提供的文档验证登录流程，确认无误后执行上线试运行操作。请注意如CARSI登录仅在您的测试环境可以试用的话，请一并告知我们您的测试网址。

        Once all the above are ready, send a mail to carsi@pku.edu.cn to apply trail run your SP on CARSI production environment, please attach the above 2 docs. CARSI will check your login process based on the User Visit Guide before we push your SP into CARSI production envirment. Please tell us your testing url if it is different from the production one.

5.切换到生产环境，试运行测试(Switch to CARSI production environment，test on it)

        收到上线成功邮件，意味着该SP metadata已合并到CARSI联盟的线上环境metadata中：https://www.carsi.edu.cn/carsimetadata/carsifed-metadata.xml。您需将SP的MetadataProvider从同步预上线环境metadata文件 https://www.carsi.edu.cn/carsimetadata/carsifed-metadata-pre.xml 修改为同步该文件， 将所有引用预上线环境的DS（https://dspre.carsi.edu.cn/ds/index.html）的地方改为引用线上环境DS (https://ds.carsi.edu.cn/ds/index.html)。

        Once your have received online notification email, it means the SP metadata is merged to CARSI online production environment: https://www.carsi.edu.cn/carsimetadata/carsifed-metadata.xml. Now you need to change your SP MetadataProvider form synchronizing https://www.carsi.edu.cn/carsimetadata/carsifed-metadata-pre.xml (pre-production) to this one, and change any reference to CARSI DS from https://dspre.carsi.edu.cn/ds/index.html (pre-production) to https://ds.carsi.edu.cn/ds/index.html (production).

6.SP试运行期间需完成: (Duting the trail run:)

        SP试运行期间,请按照CARSI SP申请和接入流程 (CARSI SP joining process)中的第九步进行对接。

        During SP trial run, please follow Step 9 of CARSI SP申请和接入流程 (CARSI SP joining process) to finish.

备注(Notice)：

        CARSI联盟IdP可支持属性参见https://www.carsi.edu.cn/docs/attribute_profile_zh.pdf。其中eduPersonScopedAffiliation属性取值，相较于默认安装SP增加了一个other@scope取值，SP可使用该取值支持与IdP的特殊约定，根据需要调整/etc/shibboleth/attribute-policy.xml配置文件，接受该取值，比如：

        Please refer to this page https://www.carsi.edu.cn/docs/attribute_profile_zh.pdf to understand CARSI IdP released attributes, be noticed we have added a value other@scope for eduPersonScopedAffiliation, you may need to modify your /etc/shibboleth/attribute-policy.xml config file to support this value:

    <afp:PermitValueRule id="eduPersonAffiliationValues" xsi:type="OR">
        <Rule xsi:type="AttributeValueString" value="faculty"/>
        <Rule xsi:type="AttributeValueString" value="student"/>
        <Rule xsi:type="AttributeValueString" value="staff"/>
        <Rule xsi:type="AttributeValueString" value="alum"/>
        <Rule xsi:type="AttributeValueString" value="member"/>
        <Rule xsi:type="AttributeValueString" value="affiliate"/>
        <Rule xsi:type="AttributeValueString" value="employee"/>
        <Rule xsi:type="AttributeValueString" value="other"/>
    </afp:PermitValueRule>


版权所有©北京大学计算中心