OIDC擴展功能2：自定義掃碼登錄

在中央授權中心OIDC功能推廣過程，發現有如下情況：

在集團某些系統中可能會有一些單位賬號，這些賬號可能由幾個員工共同管理。
有時同一個員工在某個系統中又有多個單位賬號。
無權限的員工可能需要臨時借用別的員工單位賬號登錄系統。

為了使中央授權中心支持此業務場景，特提供此擴展功能。主要步驟為：

相信手機端掃PC端的二維碼，進行一些自定義操作，如：綁定此次登錄的單位賬號，或提交此次登錄單位賬號的申請。
PC端監控登錄是否完成，登錄完成之后進入第三方系統。

此功能實現主要包括：PC端、相信手機端兩個OIDC授權功能；中央資訊云緩存服務；以及前端的展示功能。

流程時序圖如下：

第三方系統，僅需準備中央授權心的一個OIDC客戶端賬號并注冊兩個跳轉地址以及對應的state值、scope值，一個登錄界面。

client_id、client_secret
手機端RedirectUrl、ScopeA、StateA
PC端RedirectUrl、ScopeB、StateB
PC端登錄界面

一. 登錄界面處理

//Url中的換行僅為了提高可讀性，實際代碼中應去掉。
<script src="https://sso.foxconn.com/lib/jquery/dist/jquery.min.js"></script>
<script src="https://sso.foxconn.com/Civet/CustomLogin/LoginJs?
    clientId=[您的client_id]&
    MobileRedirectUrl=[手機端RedirectUrl]&
    MobileScope=[手機端RedirectUrl對應的Scope，可為空，默認為：openid civet.ext.custom_scan；此無此兩個Scope時會自動加上]&
    MobileState=[手機端RedirectUrl對應的State，可為空]&
    PCRedirectUrl=[PC端RedirectUrl]&
    PCScope=[PC端RedirectUrl對應的Scope，可為空，默認為：openid profile foxconn]&
    PCState=[PC端RedirectUrl對應的State，可為空]
    &PCClientId=[PC端ClientId，可為空，默認為前面clientId值相同]
"></script>
<--
特別說明：若定義了PCClientId值，且與clientId值不相等，則PCScope必須包含一個clientId自定義的scope。
    舉例：clientId=channel，PCClientId=BGNo1。 
          那么 PCScope必須包含以channel開頭的scope，此scope是channel事先定義好的為 channel.login.scan并授權過的。 一般 PCScope=openid profile foxconn channel.login.scan。這樣從中央授權中心獲得的AccessToken就有權限調用channel提供的接口來解析用戶登錄的公共賬號信息。
-->
<script>
  var hsso_options =  { 
    scanPrompt: "相信掃一掃，在手機端選擇要登錄的XX系統賬號",
    imgSize: 145, 
    imgMarginTop: 10, 
    imgMarginBottom: 20 
  };
  var hsso = new HQiTSSO("#div1", hsso_options);
</script>

此功能必須引用jQuery 1.7版本或以上。

JS主要方法為： new HQiTSSO(selector, options);

selector
DOM對像選擇字符串，用來指定顯示二維碼容器。
options
配置參數，可以為空。json對像，可包含下列值，且均可以為空。
- scanPrompt 提示用戶掃碼，默認值為“請使用相信「掃一掃」功能”。
- s0Prompt 用戶已掃碼的提示，默認值為“請在相信手機端完成登錄操作”。
- s5Prompt 已管理員審核時的提示，默認值為“等待管理人員同意”。
- sn10Prompt 管理員拒絕時的提示，默認值為“管理人員不同意此次登錄”。
- s10Prompt 相信手機端操作已完成時的提示，默認值為“中央授權中心正在登錄”。
- imgSize 二維碼圖片寬度，單位px，默認值為180。
- imgMarginTop 二維碼圖片上端空白高度，單位px，默認值為30。
- imgMarginBottom 二維碼圖片下端空白高度，單位px，默認值為30。
- useDefaultCsss 是否加載默認CSS樣式，默認值為true。

二. 手機端RedirectUrl處理

基本步驟：

JS方法HQiTSSO在頁面上生成一個redirect_uri=手機端RedirectUrl的OIDC授權端點鏈接二維碼。
手機端掃碼后進入手機端RedirectUrl頁面，云緩存記錄掃碼人賬號及掃碼相關信息。
手機端RedirectUrl頁面，通過OIDC的令牌端點(Token Endpoint)獲得IDToken和AccessToken，通過獲得IDToken或AccessToken搭載的信息sub值來獲得登錄者的工號。
手機端RedirectUrl頁面根據用戶賬號，顯示自定義操作界面，調用接口回寫自定義操作數據。
若需要其它用戶審核，可通過頻道開放接口SendMsg方法向審核人發消息。
審核操作完成之后，同樣調用接口回寫自定義操作狀態。

回寫自定義操作數據的接口

//此為Restful API
請求地址：https://sso.foxconn.com/Civet/CustomLogin/WriteStatusOperation
請求方法：POST
請求格式：JSON
請求頭：Authorization: Bearer <access_token>
請求數據：
{
    "session_id": "[返回手機端RedirectUrl帶上的state值的豎線前部分]",
    "status": [狀態，可選值有：10, 5, -10],
    "data": "[自定義操作數據，HQiT SSO將原樣傳至PC端]",
    "auditor": "[審核人賬號，status=5時必填]"
}

access_token獲取地址：見令牌端點(Token Endpoint)

返回值說明

//操作成功
{status : 200, message : "OK"}

//常見異常
{status : 401, message : "Token Validation Failed。"}
{status : 400, message : "請求數據不完整session_id不能為空。"}
{status : 401, message : "請求數據status值不正確，它只能是：5, 10, -10。"}
{status : 501, message : "未知異常信息"}

三. PC端RedirectUrl處理

基本步驟：

自定義操作完成之后，PC端Web前端發起一個redirect_uri=PC端RedirectUrl的OIDC授權端點請求(地址稍微有些改動)，且授權中心根據云緩存數據自動完成身份驗證。
PC端頁面重載至PC端RedirectUrl，并在URL中state值前面加上“自定義操作數據”，以英文豎線（|）隔開。
第三方系統解碼“自定義操作數據”獲得用戶自定義操作內容，如：使用XXX單位賬號。中央授權中心僅是將“自定義操作數據”原樣返回不參與加密解決處理。
第三方系統通過OIDC的令牌端點(Token Endpoint)獲得IDToken，通過獲得IDToken搭載的信息custom_scan值來獲得掃碼相關信息。
與OIDC驗證一樣可以使用AccessToken調用其它接口，如：UserInfo端點(UserInfo Endpoint)

掃碼信息獲取

從令牌（IDToken）解析出來的custom_scan值，為base64d編碼數據，解碼后可得到如下數據

{
    st: "1677636000",  /*掃碼開始時間戳*/
    aud: "X007",     /*審核人，可以為空*/
    lt: "1677636060",  /*審核發起時間戳*/
    et: "1677636600"   /*操作完成時間戳*/
}

自定義操作數據加密建議

為了防止“自定義操作數據”被篡改，強烈建此操作數據進行加密或附加簽名處理。加密或附加簽名時應考慮將當前時間截、當前用戶工號信息加入以提高其安全性。

參考代碼如下：

using System;
using System.Security.Cryptography;
using System.Text;
namespace sso.foxconn.com
{
class HQiTTools
{
static string CivetNo; //當前用戶個人賬號
const string EncryptKey = "02EA80E7BFBE49279923127C04FD2418";
static void Main(string[] args)
{
CivetNo = "X007"; //當前用戶個人賬號
string DeptAccountNo = "HQiT_PMO"; //部門賬號
//Data編碼
string data = DataEncrypt(DeptAccountNo);
string deptAccNo = DataDecrypt(data);
Console.WriteLine("編碼結果：" + data);
if (ErrorMsg == "")
{
Console.WriteLine("解碼結果：" + deptAccNo);
}
else
{
Console.WriteLine("解碼錯誤：" + ErrorMsg);
}
Console.ReadKey();
}
/// <summary>
/// Data編碼
/// </summary>
/// <param name="DeptAccountNo"></param>
/// <returns></returns>
public static string DataEncrypt(string DeptAccountNo)
{
long timestamp = (DateTime.UtcNow.Ticks - 621355968000000000) / 10000000;
string data = timestamp + "." + DeptAccountNo;
data += "." + ToMD5(data + CivetNo + EncryptKey);
byte[] bytes = Encoding.UTF8.GetBytes(data);
return Convert.ToBase64String(bytes).Replace("+", "-").Replace("/", "_").Trim('=');
}
static string ErrorMsg = "";
/// <summary>
/// Data解碼
/// </summary>
/// <returns></returns>
public static string DataDecrypt(string data) {
string[] strs = null;
if (!string.IsNullOrWhiteSpace(data))
{
string text = data.Replace("-", "+").Replace("_", "/");
int num = text.Length % 4;
if (num != 0)
{
text += new string('=', 4 - num);
}
try
{
strs = Encoding.UTF8.GetString(Convert.FromBase64String(text)).Split('.');
}
catch { }
}
if (strs == null || strs.Length != 3)
{
ErrorMsg = "輸入數據錯誤";
return null;
}
//創建時間
DateTime createTime = DateTime.MinValue;
try
{
createTime = new DateTime(long.Parse(strs[0]) * 10000000 + 621355968000000000);
}
catch { }
if (Math.Abs((DateTime.UtcNow - createTime).TotalMinutes) > 10)
{
ErrorMsg = "數據過期";
return null;
}
if (ToMD5(strs[0] + "." + strs[1] + CivetNo + EncryptKey) != strs[2])
{
ErrorMsg = "簽名不正確";
return null;
}
return strs[1];
}
/// <summary>
/// MD5加密
/// </summary>
/// <param name="input"></param>
/// <returns></returns>
static string ToMD5(string input)
{
byte[] bytes = Encoding.UTF8.GetBytes(input);
byte[] hash = null;
using (HashAlgorithm hashAlgorithm = MD5.Create())
{
hash = hashAlgorithm.ComputeHash(bytes);
}
return BitConverter.ToString(hash).Replace("-", "");
}
}
}

復制代碼，在線運行一下

import java.security.*;
import java.util.*;
import java.text.*;
import java.nio.charset.*;
import java.util.Base64;
public class HQiTTools {
static String CivetNo; // 當前用戶個人賬號
final static String EncryptKey = "02EA80E7BFBE49279923127C04FD2418";
public static void main(String[] args) {
CivetNo = "X007";
String DeptAccountNo = "HQiT_PMO";
String data = DataEncrypt(DeptAccountNo);
System.out.println("編碼結果：" + data);
String deptAccNo = DataDecrypt(data);
if (ErrorMsg == "") {
System.out.println("解碼結果：" + deptAccNo);
} else {
System.out.println("解碼錯誤：" + ErrorMsg);
}
}
public static String DataEncrypt(String DeptAccountNo) {
long timestamp = (System.currentTimeMillis() / 1000L);
String data = timestamp + "." + DeptAccountNo;
data += "." + ToMD5(data + CivetNo + EncryptKey);
byte[] bytes = data.getBytes(StandardCharsets.UTF_8);
return Base64.getEncoder().encodeToString(bytes).replace("+", "-").replace("/", "_").replaceAll("=+$", "");
}
static String ErrorMsg = "";
public static String DataDecrypt(String data) {
String[] strs = null;
if (data != null && !data.trim().isEmpty()) {
String text = data.replace("-", "+").replace("_", "/");
int num = text.length() % 4;
if (num != 0) {
text += "=".repeat(4 - num);
}
try {
byte[] bytes = Base64.getDecoder().decode(text);
strs = new String(bytes, StandardCharsets.UTF_8).split("\\.");
} catch (Exception e) {
e.printStackTrace();
}
}
if (strs == null || strs.length != 3) {
ErrorMsg = "輸入數據錯誤";
return null;
}
// 創建時間
Date createTime = null;
try {
createTime = new Date(Long.parseLong(strs[0]) * 1000L);
} catch (Exception e) {
e.printStackTrace();
}
if (Math.abs((new Date().getTime() - createTime.getTime()) / 60000) > 10) {
ErrorMsg = "數據過期";
return null;
}
if (!ToMD5(strs[0] + "." + strs[1] + CivetNo + EncryptKey).equals(strs[2])) {
ErrorMsg = "簽名不正確";
return null;
}
return strs[1];
}
public static String ToMD5(String input) {
byte[] bytes = input.getBytes(StandardCharsets.UTF_8);
byte[] hash = null;
try {
MessageDigest md = MessageDigest.getInstance("MD5");
hash = md.digest(bytes);
} catch (NoSuchAlgorithmException e) {
e.printStackTrace();
}
return bytesToHex(hash);
}
private static final char[] HEX_ARRAY = "0123456789ABCDEF".toCharArray();
public static String bytesToHex(byte[] bytes) {
char[] hexArray = "0123456789ABCDEF".toCharArray();
char[] hexChars = new char[bytes.length * 2];
for (int i = 0; i < bytes.length; i++) {
int v = bytes[i] & 0xFF;
hexChars[i * 2] = hexArray[v >>> 4];
hexChars[i * 2 + 1] = hexArray[v & 0x0F];
}
return new String(hexChars);
}
}

復制代碼，在線運行一下

<?php
class HQiTTools {
private static $CivetNo; //當前用戶個人賬號
const EncryptKey = "02EA80E7BFBE49279923127C04FD2418";
private static $ErrorMsg;
public static function main() {
self::$CivetNo = "X007"; //當前用戶個人賬號
$DeptAccountNo = "HQiT_PMO"; //部門賬號
$data = self::dataEncrypt($DeptAccountNo);
$deptAccNo = self::dataDecrypt($data);
echo "編碼結果：" . $data . "\n";
if (self::$ErrorMsg == "") {
echo "解碼結果：" . $deptAccNo . "\n";
} else {
echo "解碼錯誤：" . self::$ErrorMsg . "\n";
}
}
public static function dataEncrypt($DeptAccountNo) {
$timestamp = (time() - strtotime("1970-01-01 00:00:00 UTC"));
$data = $timestamp . "." . $DeptAccountNo;
$data .= "." . self::toMD5($data . self::$CivetNo . self::EncryptKey);
$bytes = utf8_encode($data);
$encoded = base64_encode($bytes);
return str_replace(["+", "/"], ["-", "_"], rtrim($encoded, '='));
}
public static function dataDecrypt($data) {
$strs = null;
if (!empty($data)) {
$text = str_replace(["-", "_"], ["+", "/"], $data);
$num = strlen($text) % 4;
if ($num != 0) {
$text .= str_repeat('=', 4 - $num);
}
try {
$bytes = base64_decode($text);
$strs = explode(".", utf8_decode($bytes));
} catch(Exception $e) {}
}
if ($strs == null || count($strs) != 3) {
self::$ErrorMsg = "輸入數據錯誤";
return null;
}
$createTime = intval($strs[0]);
$timestamp = (time() - strtotime("1970-01-01 00:00:00 UTC"));
if (abs($createTime - $timestamp) / 60000 > 10) {
self::$ErrorMsg = "數據過期";
return null;
}
if (self::toMD5($strs[0] . "." . $strs[1] . self::$CivetNo . self::EncryptKey) != $strs[2]) {
self::$ErrorMsg = "簽名不正確";
return null;
}
return $strs[1];
}
private static function toMD5($input) {
return md5($input, true);
}
}
HQiTTools::main();
?>

復制代碼，在線運行一下

方法擴展

若第三方系統由多個微服務組成，且所有微服務都集成了中央身份授權中心單點登錄驗證。在使用此“自定義掃碼登錄”功能時，考慮減少手機端掃碼操作，可重新生成一個“自定義操作數據”值放至在PC端授權鏈接中。

授權端點地址：

//Url中的換行僅為了提高可讀性，實際代碼中應去掉。
https://sso.foxconn.com/connect/authorize?
    client_id=[您的client_id]&
    scope=[PC端的Scope]&
    response_type=code&
    redirect_uri=[PC端RedirectUrl]&
    state="[自定義操作數據]|[其它狀態信息]"

四. 在頻道賬號的應用

這里只是說明此功能在頻道賬號上的一個應用案例。

這里涉及到四類參與者：

相信個人用戶
中央授權中心
第三方系統：頻道/頻道賬號系統，它的client_id=channel。
第四方系統：需使用頻道賬號的某個功能系統，假設它的client_id=functionSystem001。

第四方系統登錄界面處理

如前文所說，配合頻道/頻道賬號系統設定，登錄界面內容如下。

//Url中的換行僅為了提高可讀性，實際代碼中應去掉。
<script src="https://sso.foxconn.com/lib/jquery/dist/jquery.min.js"></script>
<script src="https://sso.foxconn.com/Civet/CustomLogin/LoginJs?
    clientId=channel&
    MobileRedirectUrl=https://believe.foxconn.com/mp_login/ChannelSelector.html&
    MobileState=[可選項/可為空，值有：roleIdGt0、roleIdGt1，分別表示不许無權用戶臨時登錄、只许擁有者登錄]&
    PCClientId=[functionSystem001， 您的client_id]&
    PCRedirectUrl=[PC端RedirectUrl]&
    PCScope=openid profile foxconn channel.login.scan&
    PCState=[PC端RedirectUrl對應的State，可為空]
"></script>
<script>
  var hsso_options =  { 
    scanPrompt: "相信掃一掃，在手機端選擇要登錄的相信頻道賬號",
    imgSize: 145, 
    imgMarginTop: 10, 
    imgMarginBottom: 20 
  };
  var hsso = new HQiTSSO("#div1", hsso_options);
</script>

注：涉及的scope開通可與相信團隊聯系開通。

第四方系統獲得頻道的賬號信息

使用前文所述的“PC端RedirectUrl處理”：
1）獲得state值英文豎線（|）前的“自定義操作數據”；
2）獲得AccessToken。

使用上面得到內容，請求頻道賬號系統獲得頻道賬號信息。

POST https://believe.foxconn.com/mp_login/channelinfo
  Authorization: Bearer <access_token>
  Content-Type: application/x-www-form-urlencoded
    
    login_data=<自定義操作數據>&
    lang=tw     //支持cn/tw/en/jp

返回結果


{
    "data": {
        "uid": "CivetDeve",
        "name": "生活頻道開發指南",
        "icon": "https://icivetmedia.foxconn.com/group1/M00/48/69/CoaWx1p7x8uAKsf3AABo84SjADM518.jpg",
        "roleId": 2
    },
    "code": 200,
    "msg": "OK"
}

// roleId，值有： 0/1/2，分別表示臨時同意登錄、運營人員登錄、頻道擁有者登錄。
//    其中，roleId=0時強列建議授權登錄時檢查掃碼信息確認登錄同意人的賬號，或不予登錄。