CARSI SP+OAuth认证接口

本文档为CARSI SP OAuth服务认证接入接口说明。CARSI联盟中SP资源方如需通过OAuth接入CARSI联盟，可参照此文档。

请注意：预上线环境（测试环境）的域名为：spoauth2pre.carsi.edu.cn ； 正式线上环境的域名为： sp-{$client_id}.carsi.edu.cn 。{$client_id}为SP自定义的唯一ID。

测试时请使用https://spoauth2pre.carsi.edu.cn/api/authorize?response_type=code&client_id=xxxc&state=yyy ，

正式上线时将地址 https://spoauth2pre.carsi.edu.cn/ 改为 https://sp-{$client_id}.carsi.edu.cn/ ，后面接的参数不变。

如果您有地方引用了CARSI的DS服务，则测试时（预上线环境）使用 https://dspre.carsi.edu.cn，正式上线时改为 https://ds.carsi.edu.cn。

第一步：获取授权码

接口地址：https://sp-{$client_id}.carsi.edu.cn/api/authorize

接口参数：

         response_type （必选）： 设值 "code"

         client_id（必选） ： OAuthClient唯一标示，在申请时确定。

         state（必选）:   校验使用。

                       备注：state值可设置为固定值或动态值。

1. 1. 1. 1. 固定值通常设置为和client_id一致。也可自行设置。
         2. 如为动态值，则需在CARSI管理系统（mgmt）中预留SP资源的入口地址。即用户从CARSI登陆后，访问的资源页面的入口地址，例如https://www.service1.com/。在该入口，SP资源需自行构造https://sp-{$client_id}.carsi.edu.cn/api/authorize?response_type=code&client_id={client_id}&state={动态值}，并将用户指向该地址完成后续流程。

         resource_id（可选，2024-04-12新增）：经urlencode编码的字符串。用于认证完成后，重定向新位置。可以是URL（类似：https://xxxx/?yyy），或一个自定义的字符串。

    提交方式： GET/POST

    返回值： 

             返回授权码code。

              重定向到 callback_url 地址，并附带code。

              callback_url 地址在OAuthClient申请时提交CARSI联盟。示例：https://{$callback_url}?code=XXXX&state=XXXX 。

              授权码code有效期为10分钟。

              执行下面第二步成功获得访问令牌后，授权码code会自动失效。

第二步：获取访问令牌

接口地址：https://sp-{client_id}.carsi.edu.cn/api/token

接口参数：

grant_type ： 设值为 "authorization_code"

client_id ： OAuthClient 是SP唯一标示，在SP申请时确定。

client_secret  :  OAuthClient 是访问口令，在SP申请时确定。

code ：   由上一步获得。

提交方式： POST（x-www-form-urlencode 数据格式）

返回值： JSON格式

{

      “access_token”:”XXXX”,

       "refresh_token" : "XXXX",

       “expires_in”:”XXXXX”,

}

说明：

access_token ：OAuthServer 颁发的访问令牌

refresh_token：访问令牌过期后，OAuthServer 颁发的用于重新更新访问令牌的令牌

expires_in ： 访问令牌过期时间，60分钟

第三步：获取资源

接口地址：https://sp-{client_id}.carsi.edu.cn/api/resource

接口参数：

access_token ： 上一步获得的访问令牌

client_id ： 是SP唯一标示，在SP申请时确定。

提交方式： GET/POST

返回值： JSON格式

{

       "carsi-affiliation” : ”XXXX”,  #由OauthClient申请时提供的RSA公钥进行加密的数据，BASE64编码

       "carsi-persistent-uid" : "XXXX",  #由OauthClient申请时提供的RSA公钥进行加密的数据，BASE64编码

       “resource_id” : "XXXX",     #2024-04-12新增。由SP申请时提供的RSA公钥进行加密的数据，BASE64编码

}

说明（参见IdP属性介绍）：

      （1）carsi-affiliation：标识用户的身份，取值为：faculty, student, staff, alum, member, affiliate, employee, other，后面加上@xxx.edu.cn。对应的身份分别为：教师、学生、员工、校友、成员、附属人员，聘用人员、其他。例如：faculty@pku.edu.cn。

      （2）carsi-persistent-uid：一个永久的，可读性不强的身份识别码，用于唯一标识用户身份。可理解为用户在该SP中的唯一别名。

        请注意，这一步可以获取到的属性，与3. 通过CARSI SP OAuth网关接入(Joining CARSI for OAuth SP)中第一步添加SP时勾选的“SP需要的属性”是对应的，未勾选的属性无法获取到。

      （3）resource_id：如果在第一步调用authorize接口时，带有resource_id参数，则此处返回值中会带有该值。后续程序可根据此值，将用户重定向到指定位置。

常见问题：

• 关于如何获取到登录用户的所在机构信息：

请参考上述resource接口，carsi-affiliation属性的格式即为"身份@学校域名"，通过学校域名可以映射到具体的学校。

a) 可以参考CARSI发布的学校列表: https://www.carsi.edu.cn/IdPlist.html 该列表是动态更新的。注意以下三所早期加入的学校，IdP EntityID中的IdP域名是学校域名的三级域名，其余学校IdP EntityID中的IdP域名均为学校域名的二级域名。

西南交通大学：https://idp.lib.swjtu.edu.cn/idp/shibboleth
北京师范大学：https://idp.lib.bnu.edu.cn/idp/shibboleth
郑州大学：https://idp.v.zzu.edu.cn/idp/shibboleth

b) 也可以解析CARSI联盟的metadata文件来获取域名与学校的映射，里面包含了所有已上线学校的信息（每个学校是一个EntityDescriptor，查找路径为EntityDescriptor -> IDPSSODescriptor -> Extensions -> shibmd:Scope）：线上：https://www.carsi.edu.cn/carsimetadata/carsifed-metadata.xml  预上线：https://dspre.carsi.edu.cn/carsifed-metadata-pre.xml

c) 还可以通过线下渠道做这个映射，比如其它SP会要求每个学校的管理员向他们申请开通该单位SP的服务，在申请表中需要学校提交自己的affiliation属性的scope（即学校域名）以及@ 之前的身份取值范围。也是一种思路。参考：https://www.carsi.edu.cn/SPlist.html （比如科睿唯安的“服务开通”文档）

• 关于IdP释放的属性：

请参考IdP属性介绍。

• 获取的用户数据解码示例（php代码）：

<?php
 /* 代码示例 */

 $userInforaw=''; /*通过/api/resource接口获得的原始用户数据*/
 $private_key=''; /*私钥*/
 
 /*json解析*/
 $userInfoArray = json_decode($userInforaw,true);
 /*base64解码*/
 $carsi_affiliation_crypt=base64_decode($userInfoArray['carsi-affiliation']);
 $carsi_persistent_uid_crypt=base64_decode($userInfoArray['carsi-persistent-uid']);
 /*私钥解密*/
 openssl_private_decrypt($carsi_affiliation_crypt,$carsi_affiliation_decrypt,$private_key);
 openssl_private_decrypt($carsi_persistent_uid_crypt,$carsi_persistent_uid_decrypt,$private_key);
 
 echo $carsi_affiliation_decrypt;
 echo $carsi_persistent_uid_decrypt;
 
?>

• 如何验证秘钥对（公钥 / 私钥）：

可使用此地址验证公钥 / 私钥是否正确。https://spoauth2.carsi.edu.cn/CARSI_SP_demo.php

验证示例视频