免登录配置指引
⚠️ 注意！
- 确保你的授权服务能够在能正常访问，否则有可能请求失败
- 确保你的相关相求地址以及url信息填写正确，否则无法正常请求
- 考虑到不同公司授权服务器请求及返回数据存在差异在配置的时候需要填写请求模板，模板支持五种占位符分别为： {ClientId} 、 {ClientSecret} 、 {Code} 、 {AccessToken} 、 {AccessTokenType} 需要在模板中填写正确的占位符,只支持一层嵌套不支持多层次嵌套
- HTTP请求的Content-Type为application/json，获取用户信息时HTTP Header会自动带上Authorization：{AccessToken}或Authorization：Bearer {AccessToken}键值对 键值对
一、业务请求流程
二、占位符说明
| 占位符 | 含义 |
| {ClientId} |
你公司的授权服务器生成ClientId 在【免登录配置】你的请求参数、返回参数及URL中使用占位符格式必须为:{ClientId} |
| {ClientSecret} |
你公司的授权服务器生成ClientSecret 在【免登录配置】你的请求参数、返回参数及URL中使用占位符格式必须为:{ClientSecret} |
| {Code} |
你公司的授权服务器在用户授权以后回调的code 在【免登录配置】你的请求参数、返回参数及URL中使用占位符格式必须为:{Code} |
| {AccessToken} |
通过授权服务器回调的[code]调用配置的[获取Token URL]获取到的令牌，通过该令牌能够获取到用户信息 在【免登录配置】你的请求参数、返回参数及URL中使用占位符格式必须为:{AccessToken} |
| {AccessTokenType} |
通过授权服务器回调的[code]调用配置的[获取Token URL]获取到的令牌类型，目前仅支持bearer类型 在【免登录配置】你的请求参数、返回参数及URL中使用占位符格式必须为:{AccessTokenType} |
| {MatchPuDuAccount} |
通过您授权服务颁发的令牌获取的到用户信息，您返回的用户信息跟普渡账号匹配的字段，占位符必须为： {MatchPuDuAccount} |
| {RedirectUri} |
若您的授权服务器对RedirectUri有校验，请在您的获取令牌或者获取用户的接口请求参数中使用它，占位符必须为： {RedirectUri} |
三、“免登录配置“参数说明
| 参数 | 请求方式 | URL参数模板说明 | 请求参数模板说明 | 返回参数模板说明 | 参数说明 |
| Client ID | 不涉及 | 不涉及 | 不涉及 | 不涉及 | 由企业生成提供 |
| Client Secret | 不涉及 | 不涉及 | 不涉及 | 不涉及 | 由企业生成提供 |
| 授权服务器URL | 不涉及 | 不涉及 | 不涉及 | 不涉及 | 该地址可以了解企业自有OAuth2 服务的相关文档 |
| 获取Token URL | GET |
在发送HTTP请求的时候通过GET方式调用该接口 假设原本请求接https://xxxxx.com/oauth/token?client_id=bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc&client_secret=d34cce4ca0b9116340451c2000a9af216d5b209579c7567b63347b38d6100b81&code=a0b9116340 则通过占位符为： https://xxxxx.com/oauth/token?client_id={ClientId}&client_secret={ClientSecret} &code={Code} |
不涉及 |
若你的接口返回参数为： { "access_token": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc", "refresh_token": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc", "token_type": "bearer" } 则填写的模板为： { "access_token": "{AccessToken}", "refresh_token": "{refreshTokenType}", "token_type": "{AccessTokenType}" } |
1.改接口仅支持GET、POST两种HTTP请求方式 2.对于有其他固定直接写在里面在请求的时候会请求过期 3.POST 参数支持BODY RAW请求方式 4.请求的头部自动带上：Content-Type：application/json 5.返回的参数请确保能通过令牌获取到用户信息，否则无法正常登陆
|
| POST |
在发送HTTP请求的时候通过POST方式调用该接口 假设原本请求接口为：https://xxxxx.com/oauth/token?client_id=bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc&client_secret=d34cce4ca0b9116340451c2000a9af216d5b209579c7567b63347b38d6100b81&code=a0b9116340 则通过占位符为： https://xxxxx.com/oauth/token?client_id={ClientId}&client_secret={ClientSecret}&code={Code} |
若你的接口请求参数为： { "client_id": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc", "client_secret": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc" } 则填写的模板为： { "client_id": "{ClientId}", "client_secret": "{ClientSecret}" } |
若你的接口返回参数为： { "access_token": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc", "refresh_token": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc", "token_type": "bearer" } 则填写的模板为： { "access_token": "{AccessToken}", "refresh_token": "{refreshTokenType}", "token_type": "{AccessTokenType}" } |
||
| 获取用户信息 URL | GET |
在发送HTTP请求的时候通过GET方式调用该接口 假设原本请求接口为：https://xxxxx.com/api/v5/user?access_token=bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc 则通过占位符为： https://xxxxx.com/api/v5/user?access_token={AccessToken} |
不涉及
|
若你的接口返回参数为： { "user_id":"xxxxxxxxx", "email":"xxxx@xx.com", "name": "xxxxxxxxx" } 则填写的模板为： { "user_id":"xxxxxxxxx", "email":"{MatchPuDuAccount}", "name": "xxxxxxxxx" } |
1.改接口仅支持GET、POST两种HTTP请求方式 2.对于有其他固定直接写在里面在请求的时候会请求过期 3.POST 参数支持BODY RAW请求方式 4.请求的头部自动带上：Content-Type：application/json 5.返回的参数请其中的匹配字段确保能够与普渡的登陆账号匹配上否则登陆会失败 6.在调用用户信息接口的时候会在HTTP Header自动带Authorization：{AccessToken}或Authorization：Bearer{AccessToken}键值对 |
| POST |
在发送HTTP请求的时候通过GET方式调用该接口 假设原本请求接口为：https://xxxxx.com/api/v5/user?access_token=bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc 则通过占位符为： https://xxxxx.com/api/v5/user?access_token={AccessToken} |
若你的接口请求参数为： { "access_token": "bfe175c3180480253a228827c1c8a9393906d3808ccaea778e3dc70ebd2057fc" } 则填写的模板为： { "access_token": "{AccessToken}" } |
若你的接口返回参数为： { "user_id":"xxxxxxxxx", "email":"xxxx@xx.com", "name": "xxxxxxxxx" } 则填写的模板为： { "user_id":"xxxxxxxxx", "email":"{MatchPuDuAccount}", "name": "xxxxxxxxx" } |
||
| 账号匹配字段 | 不涉及 | 不涉及 | 不涉及 | 通过调用【获取用户信息 URL】接口获取到的用户信息与普渡的登陆账号匹配字段 | |
| 重定向地址 | 不涉及 | 不涉及 | 不涉及 | 通过重定向地址跳转到企业的授权服务器从而实现免登陆功能，在填写完成上述配置信息以后自动生成 |
四、配置流程说明(以GITHUB为例)
- 第一步，注册一个github第三方应用。
Homepage URL：随意填写
Callback URL：【普渡认证服务地址】/v1/redirect - 第二步，在创建好的github应用中生成Client secrets
注意，务必保存好你的Client secrets，不要泄露。
获取到Client ID和Client secret之后，进入下一步 - 第三步、找到对应的普渡业务平台进行配置
此处以普渡代理商平台为例
Client ID&Client Secret已经通过github的应用获取到了，接下来按照使用 OAuth 应用对 REST API 进行身份验证 - GitHub 文档来进行相关配置。
- 授权服务器URL：即Github授权服务器授权地址。 https://github.com/login/oauth/authorize
如果你的应用需要带更多的参数可以在此处配置
- 获取Token：
既通过授权服务器回调过来的code(授权码), 来获取access_token的接口。
通过配置请求参数和返回数据，通过占位符(具体意义参考以上【占位符说明】)
- 获取用户信息：
即通过上面接口获取到的access_token和token_type，来获取用户的具体信息。获取到用户信息之后，会通过你配置的返回数据，通过{MatchPuDuAccount}占位符来和普渡账号中的账号字段做匹配。
-
- 注意，目前仅支持bearer的token_type。如果不传则会默认通过在header中通过Authorization传值。
配置完成并成功保存后。下方会产生一个跳转地址。
形如：【普渡认证服务地址】/v1/jump/【Client ID】
如果你需要跳转到指定地址，你可以通过在跳转地址上添加redirect_uri参数来进行指定跳转(注意此参数需要进行encode编码)。
五、常见错误
如果您在使用过程中出现了错误提示，其中提示的前缀为错误码，可能的错误原因如下：
| 错误码 | 错误可能原因 |
| 3133 | 填写的用户匹配字段，在您的授权服务器获取用户信息的接口没有返回改字段或者返回字段为null |
| 3134 | 请检查您的授权服务器是否有正常返回授权code |
| 3135 | 获取您的授权配置信息错误，请检查您的免登录配置是否正确 |
| 3137 | 获取您授权服务的令牌url或者获取用户信息的url错误，请检查您的免登录配置是否正确 |
| 3138 | 解析您的获取令牌url错误，请检查您的获取令牌url占位符是否使用正确 |
| 3139 | 调用您的获取令牌的url发生错误，请检查您的url是否填写正确，您的url请求参数是否正确，您的url请求参数占位符是否使用正确；若您的授权服务器对【redirect_uri】有强制校验请检查您在您的授权服务器中的回调地址是否填写正确 |
| 3140 | 调用您的获取令牌的url发生获取令牌，在解析返回参数的时候发生错误，请检查您的返回参数占位符是否填写正确 |
| 3141 | 调用您的获取用户信息url发生错误，请检查您的url是否填写正确，您的url请求参数是否正确 |
| 3142 | 您授权服务器返回的用户信息，获取到匹配字段后，普渡系统的账号状态异常，请登陆普渡系统修改当前账号的状态 |
| 3144 | 您返回的用户信息，获取到匹配字段后，跟普渡系统账号未匹配上 |