3. 通过CARSI SP OAuth网关接入(Joining CARSI for OAuth SP)

技术调试前需做的准备(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管理(OAuth)”中，选择“添加SP”，按照提示完成添加。

On MyCarsi->SP Mgmt(OAuth) page, click Add SP, follow the hints to add your SP.

选填项：“SP 登出通知地址”：为CARSI联盟SLO登出时，将以 “post” 方式向已登陆的SP（OAuth）的登出通知地址发送用户登出通知，SP在接收到通知后可对用户进行SP应用层登出，SP（OAuth）需根据 “https://carsi.atlassian.net/wiki/spaces/CAW/pages/114753551 ” 设计登出通知地址接口。

Optional item: "SP Logout Notification Url" : When the CARSI Alliance SLO logs out, it will send the user logout notification to the login notification url of SP (OAuth) in the form of "POST". SP (OAuth) can log out the user at the SP application layer after receiving the notification. SP (OAuth) needs to design the interface of logout notification url according to "https://carsi.atlassian.net/wiki/spaces/CAW/pages/114753551 ".

请注意，务必根据实际需要勾选“SP需要的属性”中需要获取的属性，通常至少需要carsi-affiliation。

Notice: Please ensure to select "SP Required Attributes" based on your requirements, please select at lease one attribute (eg, carsi-affiliation).

2.线上提交OAuth对接参数(Add OAuth info into CARSI)

SP添加好以后，点击进入该SP详情页，在页面最下方有入口绑定OAuth Client信息。

Once SP is added, click this SP to visit its detail page, at the bottom of this page click "Edit OAuth Client" to bind OAuth client info.

需要的信息具体包括(Info needed)：

（1）Client_ID ：资源的英文缩写或拼音简称，长度不能超过20个字符

（1）Client_ID ： Client ID in English characters, less than 20 characters

（2）Client_Secret ：自己设置一个OAuthClient访问口令，长度不超过30位。CARSI SP+OAuth2认证接口介绍的接口token中用到的

（2）Client_Secret ： Set a new secret and remember it, will be used to access CARSI OAuth API, lesse than 30 characters. Refer to CARSI SP+OAuth2认证接口 Interface '/token' for details.

（3）回调地址：遵照OAuth协议，应用系统提供的服务地址。建议为 https。

（3）Redirect URI ：The redirect URI mentioned in OAuth 2 protocol. Suggested to be https.

（4）非对称密钥对中的公钥：签名算法为RSA2，密钥长度至少2048位，建议使用4096位

（4）Public key content of pub-private pair：Use RSA2, aleast 2048 bits suggested to be 4096 bits

关于非对称密钥对中的公钥(About the public key)：

公钥是在 CARSI SP+OAuth2认证接口中介绍的resource接口中使用的，其作用是将IdP返回的用户身份信息做加密后再返回给OAuth客户端，OAuth客户端再使用自己的私钥解密出该信息。可以参考以下命令生成一个4096位的非对称密钥对，将其中的rsa_pcks8_pem.public文件的全部内容（包括头尾2行）或将整个文件提供给CARSI。

The publich key is used in CARSI SP+OAuth2认证接口 resource interface, it is uesed to encrypt the user attributes returned by IdP, the OAuth clien uses its private key to decrypt the info. You could refer to below commands to generate a 4096 bits key pair. Please copy all the contents in rsa_pcks8_pem.public (including the header and tail lines) to CARSI.

openssl genrsa -out rsa_pem.key 4096    #生成PKCS #1 PEM格式的私钥，4096位
openssl pkcs8 -topk8 -inform PEM -in rsa_pem.key -outform PEM -out rsa_pcks8_pem.private -nocrypt    #转换成PKCS #8 PEM格式的私钥（因为Java等程序是需要使用该格式的）
openssl rsa -in rsa_pcks8_pem.private -pubout -out rsa_pcks8_pem.public    #生成对应的公钥

这是一个样例公钥文件(This is an example public key file)：rsa_pcks8_pem.public

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

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

Visit the CARSI login url of your SP (CARSI SP+OAuth2认证接口 ‘/authorize‘ interface), 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.

4.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。

5.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.

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

收到上线试运行的邮件后，根据CARSI SP+OAuth2认证接口头部的说明，切换SP OAuth 网关服务器的域名，从预上线域名改为线上域名。

After receiving trail run email，Refer to the instruction at the top of CARSI SP+OAuth2认证接口 to switch the SP OAuth Gateway DNS from prerelease to release(online).

SP试运行期间,请按照 https://carsi.atlassian.net/wiki/spaces/CAW/pages/27103679 中的第九步进行对接。

During SP trial run, please follow Step 9 of to finish.