前端FIDO U2F集成

2023-03-14 13:09 星期二

本页面主要介绍前端FIDO U2F如何进行集成集成。

绑定硬件令牌

1.1 获取令牌信息

HTTP Method：POST
请求地址：https://serverurl/api/v1/safe/u2fRegisterStart
Header Content-Type：application/json

接口功能： 获取用户和硬件令牌相关数据。

请求参数：

参数名必选类型参数说明
tokenName是String自定义的令牌名称

响应结果：

参数名参数说明
code响应码，具体参见附录：响应码
message结果描述
data业务数据，此数据为json格式数据，以下为此接口返回数据说明属性名称说明code返回码，0表示成功，其它返回码参见返回码列表。msg返回描述信息reqid是新创建的凭据的ID，在用户尝试进行身份验证时用于标识它。fido2_data业务数据，此数据为json格式数据，以下为此接口返回数据说明属性名称说明rp代表依赖方，这是负责注册和验证用户的实体，即我们要向其注册的网站。 id必须是网站域的子集。challenge服务器收到的随机字符串，必须用公共密钥签名以证明用户拥有相应的私有密钥。user包含有关当前注册用户的信息。 它必须至少包含用于将用户与凭证关联的属性id 。 它在服务器上生成。pubKeyCredParams是一个对象数组，描述了将要创建的凭证的功能。 当前， type的唯一可能值为“公钥”，而alg的值-7表示使用SHA-256的椭圆曲线算法ECDSA。timeout包含以毫秒为单位的时间，脚本将等待注册过程完成authenticatorSelection设置用于创建凭据的authenticatorSelectionCriteria器的条件attestation包含新生成的公钥，可选的证明证书以及用于服务器上验证的其他元数据。

成功示例：

{
    "code":200,
    "message":"ok",
    "data":{
        "msg":"成功",
        "code":0,
        "fido2_data":{
            "attestation":"direct",
            "challenge":"gi-7_E_hAR6I8P58x0O9NYQcrUcm7kSuF54wlaNLiIY",
            "authenticatorSelection":{
                "authenticatorAttachment":"cross-platform",
                "userVerification":"preferred",
                "requireResidentKey":false
            },
            "user":{
                "displayName":"zyq",
                "id":"enlx"
            },
            "rp":{
                "name":"company_default_api",
                "id":"cloudentify.com"
            },
            "pubKeyCredParams":[
                {
                    "type":"public-key",
                    "alg":-7
                }
                ]
        },
        "reqid":"fido20d040o0c0",
        "username":"zyq"
    }
}

1.2 调取绑定令牌

请求方法：navigator.credentials.create()

接口功能： 将用户和硬件令牌进行绑定。

请求参数：

参数名必选类型参数说明
publicKey是字符串对象需要JSON序列化，用户和硬件令牌的数据，以下为参数说明属性名称说明rp代表依赖方，这是负责注册和验证用户的实体，即我们要向其注册的网站。 id必须是网站域的子集。challenge服务器收到的随机字符串，必须用公共密钥签名以证明用户拥有相应的私有密钥，需要base64解码处理。user包含有关当前注册用户的信息。 它必须至少包含用于将用户与凭证关联的属性id 。 它在服务器上生成。id需要base64解码处理pubKeyCredParams是一个对象数组，描述了将要创建的凭证的功能。 当前， type的唯一可能值为“公钥”，而alg的值-7表示使用SHA-256的椭圆曲线算法ECDSA。timeout包含以毫秒为单位的时间，脚本将等待注册过程完成authenticatorSelection设置用于创建凭据的authenticatorSelectionCriteria器的条件attestation包含新生成的公钥，可选的证明证书以及用于服务器上验证的其他元数据。

参数示例：

{
    "publicKey": {
        "reqid": "fido20d040o0c0",
        "rp": {
            "id": "cloudentify.com",
            "name": "company_default_api"
        },
        "challenge": "Z2ktN19FX2hBUjZJOFA1OVjbTdrU3VGNTR3bGFOTGlJWQ==",
        "user": {
            "displayName": "zyq",
            "id": "ZW5seA=="
        },
        "pubKeyCredParams": [
            {
                "type":"public-key",
               "alg":-7
            }
        ],
        "authenticatorSelection": {
            "authenticatorAttachment":"cross-platform",
            "userVerification":"preferred",
            "requireResidentKey":false
        },
        "attestation":"direct",
    }
}

1.3 校验硬件令牌

HTTP Method：POST
请求地址：https://serverurl/api/v1/safe/u2fRegisterConfirm
Header Content-Type：application/json

接口功能： 校验硬件令牌

请求参数：

参数名必选类型参数说明
reqId是String是新创建的凭据的ID，在用户尝试进行身份验证时用于标识它。获取令牌时返回的数据
u2fData是字符串对象需要JSON序列化，绑定令牌返回的数据集合，令牌校验成功后的数据参数业务数据，以下为参数数据说明属性名称说明id是新创建的凭据的ID，在用户尝试进行身份验证时用于标识它。type硬件认证返回的硬件类型，当前可能仅保留值“ public-key”。rawId是二进制格式的idresponse此数据全部需要base64编码处理，为json格式数据，以下为参数数据说明属性名称说明clientDataJSON作为response是从浏览器传递到身份验证器的数据，用于将凭据与服务器和浏览器关联。attestationObject包含新生成的公钥，可选的证明证书以及用于服务器上验证的其他元数据。username用户名

参数示例：

{
        "reqId":"fido20d040o0c0",
        "u2fData":"{\"id\":\"8hV8x0dZFKEhmxx3d4szCLYDGORoJcERuHx4vGDbpaedc1B_Vos4BblGCA6CybIlURGxIgCvteR3
        -g4Ssmgh8l74HxsdX-sjzb5PHSSLMiFtokMtGudw6drlUjNB2BIh\",\"type\":\"public-key\",\"rawId\":{},\"res
        ponse\":{\"clientDataJSON\":\"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiZ2ktN19FX2hBUjZ
        JOFA1OHgwTzlOWVFjclVjbTdrU3VGNTR3bGFOTGlJWSIsIm9yaWdpbiI6Imh0dHBzOi8vd2FuZ3poZS5jbG91ZGVudGlmeS5j
        b20iLCJjcm9zc09yaWdpbiI6ZmFsc2V9\",\"attestationObject\":\"o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2FsZyZjc2
        lnWEcwRQIhAKBT5-lp1F6Ql1GcRaPR1OzfTyM3PsMWUhob1JAkxXcLAiAwZJ45jXkol56WBSYVRrKYoy3seKNpK21E0NmIEOJ
        l9mN4NWOCWQI_MIICOzCCAeGgAwIBAgIQHfK1WlHcS2iFo9meaX_tEjAKBggqhkjOPQQDAjBJMQswCQYDVQQGEwJVUzEdMBsG
        A1UECgwURmVpdGlhbiBUZWNobm9sb2dpZXMxGzAZBgNVBAMMEkZlaXRpYW4gRklETyBDQSAwNDAgFw0xODA1MjEwMDAwMDBaG
        A8yMDMzMDUyMDIzNTk1OVowaDELMAkGA1UEBhMCVVMxHTAbBgNVBAoMFEZlaXRpYW4gVGVjaG5vbG9naWVzMSIwIAYDVQQLDB
        lBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRYwFAYDVQQDDA1GVCBGSURPMiAwNDMwMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQc
        DQgAEsn4OjjkAH1Tsm29P6IQZA3ZFIKh262mNPMANfVtNw8zZVjKjGhOsvWfzjz1isqWg3AylKJZADcmtOXiL6iiARaOBiTCB
        hjAdBgNVHQ4EFgQU3TJEFxpnq79SIAdz0TzPN5aud7EwHwYDVR0jBBgwFoAUkyNwZsUdzsSrHCuthMHz5x3OYGcwDAYDVR0TA
        QH_BAIwADATBgsrBgEEAYLlHAIBAQQEAwIEMDAhBgsrBgEEAYLlHAEBBAQSBBDuBBvOJeVM24-GiX_WQYRkMAoGCCqGSM49BA
        MCA0gAMEUCID8W6RCyob1_rDPUPaaBuWY4Z91votfLnSdHB_f88bGxAiEAozu4gVI5H8ZSu5t94xgy5QJrmtPjeslPJab0Tqv
        zRNZZAf4wggH6MIIBoKADAgECAhAYFStBt0OubbQVmcOxfYIJMAoGCCqGSM49BAMCMEsxCzAJBgNVBAYTAlVTMR0wGwYDVQQK
        DBRGZWl0aWFuIFRlY2hub2xvZ2llczEdMBsGA1UEAwwURmVpdGlhbiBGSURPIFJvb3QgQ0EwIBcNMTgwNTIwMDAwMDAwWhgPM
        jAzODA1MTkyMzU5NTlaMEkxCzAJBgNVBAYTAlVTMR0wGwYDVQQKDBRGZWl0aWFuIFRlY2hub2xvZ2llczEbMBkGA1UEAwwSRm
        VpdGlhbiBGSURPIENBIDA0MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExaEWVjmKkhb8crsoukpphTm_j0crBmzIQCqdpJ_
        QJDPrtUdnRw9dh3qcTi6bcEfSWvhbziA9xkVR6tnbceu4M6NmMGQwHQYDVR0OBBYEFJMjcGbFHc7EqxwrrYTB8-cdzmBnMB8G
        A1UdIwQYMBaAFEu9hyYRrRyJzwRYvnDSCIxrFiO3MBIGA1UdEwEB_wQIMAYBAf8CAQAwDgYDVR0PAQH_BAQDAgEGMAoGCCqGS
        M49BAMCA0gAMEUCIH-1QMQ_RpYWJL0TJUi0St8EtmFxj-QsMrpfmtQMcGq1AiEA-sWmfdzVx_eRWKQZBWiZW67HU-J6lUpOMi
        H3nkpgwvFoYXV0aERhdGFY5JUOnH781oolR6eNlLBhcfd9QVU5psnVCXC5Kul-WF96RQAAHMPuBBvOJeVM24-GiX_WQYRkAGD
        yFXzHR1kUoSGbHHd3izMItgMY5GglwRG4fHi8YNulp51zUH9WizgFuUYIDoLJsiVREbEiAK-15Hf6DhKyaCHyXvgfGx1f6yPN
        vk8dJIsyIW2iQy0a53Dp2uVSM0HYEiGlAQIDJiABIVggITIsh6qbrpQvMAZGtooofBjEGlluUothDPpBgJCU9NkiWCCjoOBq6
        fhot865lFLRFW0x2fsH1T3sebtfsYb0fnBqug\"},\"username\":\"zyq\"}"
}

响应结果：

参数名参数说明
code响应码，具体参见附录：响应码
message结果描述

解绑硬件令牌

HTTP Method：POST
请求地址：https://serverurl/api/v1/safe/u2fUnbind
Header Content-Type：application/json

接口功能： 校验硬件令牌

请求参数：

参数名必选类型参数说明
code是String手机号验证码
tokenName是String令牌名称

响应结果：

参数名参数说明
code响应码，具体参见附录：响应码
message结果描述

硬件令牌登录

1.1 获取用户匹配的硬件令牌参数

HTTP Method：POST
请求地址：https://serverurl/api/v1/login/fido2AuthStart
Header Content-Type：application/json

接口功能： 获取用户和硬件令牌相关数据。

请求参数：

参数名必选类型参数说明
username是String当前登录账号名

响应结果：

参数名参数说明
code响应码，具体参见附录：响应码
message结果描述
data业务数据，此数据为json格式数据，以下为此接口返回数据说明属性名称说明reqid是新创建的凭据的ID，在用户尝试进行身份验证时用于标识它。fido2_data业务数据，此数据为json格式数据，以下为此接口返回数据说明属性名称说明rpId代表依赖方，这是负责注册和验证用户的实体，即我们要向其注册的网站。 id必须是网站域的子集。challenge服务器收到的随机字符串，必须用公共密钥签名以证明用户拥有相应的私有密钥。timeout包含以毫秒为单位的时间，脚本将等待注册过程完成allowCredentials是一个包含凭证描述符的数组，该凭证描述符限制了允许的身份验证凭证

1.2 硬件令牌认证

请求方法：navigator.credentials.get()

接口功能： 弹起硬件令牌进行认证。

请求参数：

参数名必选类型参数说明
publicKey是字符串对象硬件令牌的数据业务数据，此数据为json格式数据，以下为此接口返回数据说明属性名称说明rpId代表依赖方，这是负责注册和验证用户的实体，即我们要向其注册的网站。 id必须是网站域的子集。challenge服务器收到的随机字符串，必须用公共密钥签名以证明用户拥有相应的私有密钥，需要base64解码处理。timeout包含以毫秒为单位的时间，脚本将等待注册过程完成allowCredentials是一个包含凭证描述符的数组，该凭证描述符限制了允许的身份验证凭证（需要把每个id都base64解码处理）

参数示例：

{
    "challenge": "jRjdvzWSHOnmhEVAGyxiUO_XPS4gQV87ITpodQigNHw",
    "rpId": "cloudentify.com",
    "allowCredentials": [
        {
            "id": "8hV8x0dZFKEhmxx3d4szCLYDGOGxIgCMiFtokMtGudw6drlUjNB2BIh\",
            "type": "public-key"
        }
    ]
}

1.3 硬件令牌登录

HTTP Method：POST
请求地址：https://serverurl/api/v1/login/fido2AuthConfirm
Header Content-Type：application/json

接口功能： 使用令牌登录。

请求参数：

参数名必选类型参数说明
reqId是String硬件令牌id，获取参数时接口获取
username是String登录用户名
u2fData是字符串对象需要JSON序列化，硬件令牌校验成功后的数据参数业务数据，以下为参数数据说明属性名称说明id是新创建的凭据的ID，在用户尝试进行身份验证时用于标识它。type硬件认证返回的硬件类型，当前可能仅保留值“ public-key”。rawId是二进制格式的idresponse此数据全部需要base64编码处理，为json格式数据，以下为参数数据说明属性名称说明clientDataJSON作为response是从浏览器传递到身份验证器的数据，用于将凭据与服务器和浏览器关联。authenticatorData在注册步骤中类似于attestationObject ，但其中不包含公钥。 用于身份验证期间的验证。signature是由检索到的凭证的私钥生成的(意外)签名，将使用私钥对其进行验证以检查其是否有效。userHandle是在注册步骤中提供的user.id的值，将用于将用户与凭证关联。

参数示例：

{
    "reqId":"fido20m0p0e0c0",
    "username":"zyq",
    "fido2Data":"{
        "id":"tokMtGudw6drlUjNB2BIh",
        "type":"public-key",
        "rawId":{},
        "response":{
            "clientDataJSON":"eyJ0eXBlIjoid2ViYXV0aG4uZ",
            "authenticatorData":"lQ6cfvzWiiVHp42UsGFx931BVTmmydUJcLkq6X5YX3oFAAAeSw",
            "signature":"MEUCIQCdgUBc8I3dJbSU2EDQL0QYR2TfO07OCYEGqc3exBAZIe6c1InMlE",
            "userHandle":"JbSU2EDQL0QYR2TfO07OCY"
        }
    }"
}

响应结果：

参数名参数说明
code响应码，具体参见附录：响应码
message结果描述