api對(duì)接設(shè)計(jì)說(shuō)明

XXXAPI接口設(shè)計(jì)說(shuō)明一、文檔管理信息表主題XXXapi接口設(shè)計(jì)說(shuō)明版本內(nèi)容關(guān)鍵字參考文檔創(chuàng)建時(shí)間創(chuàng)建人最新發(fā)布時(shí)間二、要完成的功能單點(diǎn)登錄服務(wù)功能三。、單點(diǎn)登錄概述說(shuō)明1、IDaaS發(fā)起用戶登錄IDaaS平臺(tái)，從IDaaS登錄到SP應(yīng)用場(chǎng)景，如下圖所示:（1） 用戶訪問(wèn)IDaaS登錄頁(yè)面輸入用戶名和密碼進(jìn)行登錄（2） 瀏覽器攜帶用戶名密碼向IDaaS請(qǐng)求登錄（3） IDaaS認(rèn)證通過(guò)后，創(chuàng)建主session，并返回應(yīng)用列表給瀏覽器（4） IDaaS登錄成功，用戶可以看到IDaaS展示的應(yīng)用列表（5） 用戶點(diǎn)擊應(yīng)用列表中的SP1應(yīng)用圖標(biāo)（6） 瀏覽器攜帶SP1應(yīng)用的應(yīng)用id，向IDaaS請(qǐng)求生成SP1應(yīng)用子token（7） IDaaS根據(jù)信息生成子token并返回給瀏覽器（8） 瀏覽器攜帶子token，向SP1請(qǐng)求登錄（9） SP1應(yīng)用系統(tǒng)解析獲取的子token，驗(yàn)證通過(guò)后，創(chuàng)建子session并返回登錄后頁(yè)面（10） SP1系統(tǒng)單點(diǎn)登錄成功，瀏覽器顯示SP1系統(tǒng)登錄后頁(yè)面（11） ~（16）表示SP2系統(tǒng)的單點(diǎn)登錄流程，與SP1系統(tǒng)步驟一致，即在主session創(chuàng)建后，任何一個(gè)可單點(diǎn)登錄應(yīng)用進(jìn)行單點(diǎn)登錄的流程只需重復(fù)（5）~（10）即可/2、SP發(fā)起SP發(fā)起主要應(yīng)用于SSO后可以跳回發(fā)起SSO的應(yīng)用頁(yè)面。下面以SAML和JWT的實(shí)現(xiàn)為例來(lái)闡述SP發(fā)起的單點(diǎn)登錄流程。訪問(wèn)應(yīng)用頁(yè)面用戶到SP應(yīng)用頁(yè)面，會(huì)在SP通過(guò)Redirect或POST提交一個(gè)某種認(rèn)證協(xié)議如SAML/CAS的挑戰(zhàn)請(qǐng)求，在IDaaS登錄后，再跳轉(zhuǎn)回SP作為應(yīng)答，實(shí)現(xiàn)統(tǒng)一認(rèn)證，如下圖所示："b謂家頁(yè)函<1：4>堀向重立阿埔崢」°珀Z詛詬噌李I(lǐng)4辨生底"b謂家頁(yè)函<1：4>堀向重立阿埔崢」°珀Z詛詬噌李I(lǐng)4辨生底MMLUifiXg：FKMZtaHi四*!550URLI <11I堵|更毒翳％kMLftfc嶂_店何M" 1（12） 證版恒正H<-謝，董定向it*.村刮4*」 （L40諸審叩由原第兩 *< fg）童國(guó)商毒蟲曲———K?（1&Jai值a宙，頁(yè)函『 <6）攜曰dimW蜀面Bi4h：i址*毒*［引角斷甄ML謝飄浙有蜀諼.井定———— （10）著響際除杖ServicePruvidertSP^以SAML協(xié)議SP發(fā)起的單點(diǎn)登錄為例:(1)用戶訪問(wèn)SP資源頁(yè)面瀏覽器向SP請(qǐng)求資源SP生成SAMLAuthnRequest請(qǐng)求，其中包含當(dāng)前URL至URelayState，并返回給瀏覽器瀏覽器攜帶SAMLAuthnRequest請(qǐng)求，訪問(wèn)定義好的IDaaS中SP發(fā)起的SSOURLIDaaS驗(yàn)證SAMLAuthnRequest,若該用戶已登錄直接跳至步驟(9)，否則繼續(xù)步驟(6)重定向到IDaaS登錄頁(yè)面用戶輸入IDaaS的賬戶和密碼瀏覽器攜帶賬號(hào)密碼請(qǐng)求登錄IDaaS登錄IDaaS后，IDaaS分析SAMLAuthnRequest中的SP應(yīng)用信息，并獲取更多用戶信息，然后組合生成響應(yīng)包含RelayState的SAMLResponseToken。返回SAMLResponseToken數(shù)據(jù)給瀏覽器瀏覽器進(jìn)行跳轉(zhuǎn)，攜帶SAMLResponseToken，訪問(wèn)SPACSURLSP利用公鑰驗(yàn)證SAMLResponseToken校驗(yàn)成功后，創(chuàng)建session會(huì)話，從RelayState中取出開始時(shí)發(fā)起的URL，返回給瀏覽器瀏覽器訪問(wèn)資源頁(yè)面(15)SP返回資源頁(yè)面(16)用戶登錄進(jìn)SP資源頁(yè)面3、接口后置SP登錄時(shí)使用IDaaS進(jìn)行接口后置認(rèn)證登錄場(chǎng)景，如下圖所示：

卜 (4)春:舛5P】鼻或蟲■卜 (4)春:舛5P】鼻或蟲■ r U)ha.ia自古明由 *-(]L)危七野】說(shuō)HI的幡 ?■〔技)戶”時(shí)可刊奇史后勇囪熾皆用卸*一——-<2)譜中連鼠如1B SP始時(shí)Wl胃是'骨一———C14^的骨T口虹n.關(guān)注地寸(1)用戶訪問(wèn)SP1登錄頁(yè)面(2)瀏覽器請(qǐng)求SP1登錄頁(yè)面SP1返回其登錄頁(yè)面用戶看到SP1登錄頁(yè)面用戶輸入用戶名密碼進(jìn)行登錄瀏覽器攜帶用戶名、密碼向SP1發(fā)起登錄請(qǐng)求SP1使用IDaaS接口進(jìn)行認(rèn)證，將用戶名、密碼傳遞給IDaaS進(jìn)行認(rèn)證登錄IDaaS進(jìn)行認(rèn)證后，生成主token，并返回主token和應(yīng)用列表以及用戶信息給SP1登錄SP1成功，瀏覽器獲取到SP1登錄后頁(yè)面用戶可看到SP1登錄后頁(yè)面，可看到顯示的應(yīng)用列表用戶在SP1顯示的應(yīng)用列表中點(diǎn)擊SP2應(yīng)用圖標(biāo)進(jìn)行單點(diǎn)登錄瀏覽器攜帶主token和應(yīng)用id，向IDaaS請(qǐng)求生成子tokenIDaaS返回SP2的子token以及SP2重定向地址瀏覽器攜帶子token訪問(wèn)SP2重定向地址SP2解析子token，驗(yàn)證成功，并返回SP2登錄后頁(yè)面(16)用戶看到SP2登錄后頁(yè)面，SP2應(yīng)用系統(tǒng)登錄成功

四、api接口說(shuō)明api參數(shù)配置appId:客戶唯一標(biāo)識(shí)符，由考試星提供，例如：14343(手機(jī)號(hào)等)。appKey:用于加密jwt，由考試星提供，例如：xf5ha3h67h4Ger34wh35p345h4。api統(tǒng)一接口地址地址：https://www.xxxxxxxxxxxxxxxxjwtInfo：jwt_info是用戶根據(jù)jwt規(guī)范，用app_key將過(guò)期時(shí)間、action_id加密，生成的加密字符串生成加密jwtInfo(java示例)⑴.安裝依賴<dependency><groupId>io.jsonwebtoken</groupId><artifactId>jjwt</artifactId><version>0.7.0</version></dependency>.生成加密字符串生成jwtInfo加密字符串importio,jsonwebtoken,Jwts;StringappKey="xf5ha3h67h4Ger34wh35p345h4”StringjwtInfo=Jwts.builder(),claim("exp”,System.currentTimeMillis()+1000*10),claim("action_id”,"201"),signWith(SignatureAlgorithm.HS256,app_key.getBytes("UTF-8")).compact();.加密參數(shù)解釋appKey:加密的私鑰，由考試星提供。exp：過(guò)期時(shí)間。action_id:表示登錄考試星動(dòng)作(注意是下劃線)。

action_id參數(shù)解釋不同的action_id代表不同的請(qǐng)求行為，目前開放的請(qǐng)求行為如下:請(qǐng)求行為編碼請(qǐng)求行為解釋201學(xué)生登錄202修改學(xué)生信息當(dāng)前開放的請(qǐng)求接口（1）考生登錄請(qǐng)求接口：地址：https://www.xxxxxxxxxxxxxxxx請(qǐng)求方法：post請(qǐng)求參數(shù)：參數(shù)編號(hào)參數(shù)名稱參數(shù)值示例參數(shù)描述1user_id15635學(xué)生唯標(biāo)識(shí)（可以是字符數(shù)字混合，只需要保證唯）2user_name張三學(xué)生姓名3passworde120ea280aa50693d5568d0071456460學(xué)生密碼（經(jīng)MD5加密）4rolestaff固定為staff5department總部/財(cái)務(wù)部學(xué)生所屬學(xué)校，如果有分級(jí)，請(qǐng)以半角左斜杠分割（action_id=201生成jwt加密字符串）返回結(jié)果:（"msg":"success","url":"/api/company/redirect/13245/?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9?eyJ1c2VyX2lkIjo1LCJleHAiOjE0OTc5NTMxODguNjg0MTIxLCJhY3Rpb25faWQiOiIyMDEifQ?I3j56t_tVMX1GgH62dy-rIktqFRienFZTJ7VKgc6lPs"}拿到結(jié)果后重定向到這個(gè)url地址，學(xué)生即可登錄平臺(tái)。（action_id=202生成jwt加密字符串）返回結(jié)果：五、綜述統(tǒng)一的輸入輸出參數(shù)（通用參考，按照平臺(tái)數(shù)據(jù)改動(dòng)）Requst參數(shù)名類型是否必填描述LanguageStringYcn:中文，en:央文UidIntY用戶IDsidstringYSessonld（TOKEN）（不需要登錄就能調(diào)用的接口、注冊(cè)接口、登錄接口,uid和sid兩個(gè)參數(shù)不需要輸入）Response參數(shù)名類型是否必填描述succeedIntY0：失敗，1：成功error_codeIntN錯(cuò)誤碼error_descStringN錯(cuò)誤消息必須登錄才能訪問(wèn)的接口接口名稱描述user/signout用戶退出user/photoupload照片上傳user/changeprofile修改用戶資料user/changepassword修改用戶密碼user/info獲取用戶信息

錯(cuò)誤返回碼列表Error_codeError_desc1授權(quán)過(guò)期500服務(wù)器內(nèi)部錯(cuò)誤600賬號(hào)被鎖定10001手機(jī)號(hào)碼不能為空10002密碼不能為空10003驗(yàn)證碼不能為空10004平臺(tái)類型不正確10005手機(jī)驗(yàn)證碼不正確10006手機(jī)驗(yàn)證碼已失效10007用戶類型不正確10008用戶名不能為空10009原密碼不能為空10010新密碼不能為空10011原密碼不正確10012經(jīng)度不能為空10013緯度不能為空10014對(duì)象用戶ID不能為空用戶接口用戶注冊(cè)(usre/signup)接口usre/signup描述用戶注冊(cè)驗(yàn)證Session方法GET/PISTRequest參數(shù)名類型是否必填描述MobileIntY注冊(cè)手機(jī)號(hào)Verify_codeStringY手機(jī)驗(yàn)證碼PasswordStringY密碼platformStringY平臺(tái)類型

Response參數(shù)名類型是否必填描述SidStringYSessonld(TOKEN)uidIntY用戶ID用戶登錄接口usre/signup描述用戶登錄驗(yàn)證Session方法GET/PISTRequest參數(shù)名類型是否必填描述MobileIntN注冊(cè)手機(jī)號(hào).（type=1時(shí)必須）usernameStringN用戶名（type=2/3/4時(shí)必須）PasswordStringN密碼（type=1時(shí)必須）PlatformStringY平臺(tái)類型Response參數(shù)名類型是否必填描述SidStr