上线代理
对于上线代理，必须执行以下步骤：
开通代理服务
为创建代理，需事先创建 asset type 和 asset。可以将 asset type 与 asset 的关系视为类似于类和对象之间的关系。对象是类的实例，类是对象的蓝图。这也同样适用于 asset type 和 asset。
创建新实体后，我们可以使用 Agent Management Service 的 agents 端点创建将绑定到此实体的代理：
POST /api/agentmanagement/v3/agents HTTP1/1
Content-Type:application/json
...
{
"entityId":"3b27818ea09a46b48c7eb3fbd878349f",
"name":"Nanobox Agent",
"securityProfile":"SHARED_SECRET"
}
| 参数 | 描述 | 备注 |
|---|---|---|
| entityId | 事先为代理创建的实体 ID。 | 每个代理均需要一个实体。 |
| name | 代理名称 | 与 Id 不同。要求每个租户的代理名称必须唯一。 |
| securityProfile | 定义代理将向 MindSphere 提供其凭证的方法： 共享密钥 对称加密（代理和 MindSphere 均知道的密码） RSA 非对称加密（公钥私钥对，其中 MindSphere 仅知道公钥，代理持有私钥） | SHARED_SECRET 或 RSA_3072 |
Agent Management Service 在创建代理时运行以下逻辑：
如果所有检查均通过，则 Agent Management 将创建代理。最初，新创建代理的上线状态是 NOT_ONBOARDED。Agent Management 为相关代理创建上线配置，并将上线状态设置为 ONBOARDING。这是一个自动过程，无需用户参与。
创建成功后，MindSphere 将返回带有 JSON 文本的 HTTP 响应 201 Created，其中包含有关新配置代理的其它数据：
HTTP/1.1 201 Created
Content-Type:Application/Json
...
{
"id":"3b27818ea09a46b48c7eb3fbd878349f",
"eTag":"2",
"entityId":"3b27818ea09a46b48c7eb3fbd878349f",
"name":"Nanobox Agent",
"securityProfile":"SHARED_SECRET"
}
| 参数 | 描述 | 备注 |
|---|---|---|
| id | 已创建的代理 Id | 代理 Id 与实体 Id 相同。二者为一一对应关系。 |
| eTag | eTag 版本 | 用于代理创建期间保持同步，无实际意义。 |
| entityId | 创建此代理的实体的 Id。 | |
| name | 代理名称 | |
| securityProfile | 代理的安全配置文件 | SHARED_SECRET 或 RSA_3072 |
获取代理的上线配置
创建代理后，代理需要获取上线配置以便上线 MindSphere。如果代理未上线，则无法使用提供的任何服务。
上线功能由 Agent Management Service 的 boarding 端点提供。使用代理 Id 作为路径参数发送GET /api/agentmanagement/v3/agents//boarding/configuration HTTP 请求将返回以下上线响应文本示例：
{
"content": {
"baseUrl": "https://southgate.eu1.mindsphere.io",
"iat": "yJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTQ0kiLCJzdWIiOiJ0ZXN0LWFnZW50IiwiYXVkIjpbIkFJQU0iXSwiaWF0IjoxNTEzNjA3NjQ3LCJuYmYiOjE1MTM2MDc2NDcsImV4cCI6MTUxNDIxMjQ0NywianRpIjoiODBkNGViYTAtZTQwMC0xMWU3LTlmMDYtM2QzOTg3NTQ1MjNjIiwic2NvcGUiOlsiSUFUIl0sInRlbmFudCI6InRlc3QtdGVuYW50IiwiY2xpZW50X2NyZWRlbnRpYWxzX3Byb2ZpbGUiOlsiUlNBXzMwNzIiXSwic2NoZW1hcyI6WyJ1cm46c2llbWVuczptaW5kc3BoZXJlOnYxIl19.F/C44dH0orAVrKXDxcdGTgDFGsYzxOLR84j49S1qQMcX4GKq0HGfN7mm9N2tAUo8+z9ISRIW+D/n81uioF4ro+cyjGFbstatsRVH8hFFbZe4WcSChBHpwmA9IBOL0iFo/8C/7FppjhmHnlJNTQrfdkPJbtgQljtlY46BqW2pKp3wPUPJb21nLhVwMv1AiAbISg17FazhzuV7n12pJxdtpEB+mYZZe16P9amW217iyaDyRZ0+UhldHyKYwX0in5SpvJ1gzFlhMNwYWhG8zk6EJ8OYY49OhTYLHtvoEm8IIxarPWWmMztwrEXvNvQi6svZ1NCcgbkuSTwdEyJDzPqmbw==",
"clientCredentialProfile": [
"SHARED_SECRET"
],
"clientId":"5fa51b64-dce2-11e7-9296-cec278b6b50a",
"tenant":"6e70640a-dce2-11e7-9296-cec278b6b50a"
},
"expiration":"2017-12-18T14:04:01.076Z"
}
| 参数 | 描述 | 备注 |
|---|---|---|
| baseUrl | Southgate URL | |
| iat | 初始访问令牌 (IAT) Agent Management 签名的 JSON Web 令牌，需要进行初始注册。 | IAT 可能会到期，默认有效期为 7 天。如果 IAT 到期，则代理需要调用此端点以获取新配置。 |
| clientCredentialProfile | 配置期间设置的代理的安全配置文件。 | SHARED_SECRET 或 RSA_3072 |
| clientId | 代理 Id | |
| tenant | 代理租户 | |
| expiration | 保持 IAT 的到期时间 | 默认值为 7 天。 |
注册代理
获取初始访问令牌 (IAT) 后，代理需要向 MindSphere 注册。注册过程根据 OAuth 2.0 授权协议进行。因此，代理将向 MindSphere 发送 HTTP POST 请求。构建此请求的方式略有不同，具体取决于代理的安全配置文件。
具有共享密钥安全配置文件的代理
注册代理由 Agent Management Service 的 register 端点提供。代理将发送带有空白文本的 HTTP POST 请求。
POST /api/agentmanagement/v3/register HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization:Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTQ0kiLCJzdWIiOiJ0ZXN0LWFnZW50IiwiYXVkIjpbIkFJQU0iXSwiaWF0IjoxNTEzNjA3NzI1LCJuYmYiOjE1MTM2MDc3MjUsImV4cCI6MTUxNDIxMjUyNSwianRpIjoiYWY2YzkwMzAtZTQwMC0xMWU3LTk4MjQtMTEwNzBjODYyZmRiIiwic2NvcGUiOlsiSUFUIl0sInRlbmFudCI6InRlc3QtdGVuYW50IiwiY2xpZW50X2NyZWRlbnRpYWxzX3Byb2ZpbGUiOlsiU0hBUkVEX1NFQ1JFVCJdLCJzY2hlbWFzIjpbInVybjpzaWVtZW5zOm1pbmRzcGhlcmU6djEiXX0=.Re1be4kiDfIs+tqZ+CEZ1/3UoBrHZ4azy3Lesse8bK6LvFtUIU626+g4JDjRdJV9gCstqfYsj15cPC+PJLOfxZFBMnoBY451RLDVJOJOtAncLPdvnPHXvvTu3VbU5Qpx0SCLY/VoDRva1a1/vMy/6S2lpOJ4dYcOMq1madzyf4iXGwmTMiKmfZEHAJuxmFRNosaEo+SkIm//OQ2SCGlWvAr1iM9QHIo8kpjYukOSt+5ubpXqlmeX7Gu5ouVABaC3T03uTzK620wNDTxhbPpNjG1RMzkUHfNcQJT0K5UuSJaMjSc1tolETAlzCz4fFevzS8UcfcUVR1Wre8qilt3khg==
Host: southgate.{region}-{env}.{mindsphere-domain}
{} //empty JSON Object
信息
{region} 、{env} 和 {mindsphere-domain} 是区域、环境和域的占位符。eu1 中 RC 环境的有效 URL 是 southgate.eu1-rc.mindsphere.io。
MindSphere 收到请求并进行验证（IAT 验证、强制性消息头验证等）。如果验证成功，MindSphere 将创建一个共享密钥（密码），并以预定义的共享密钥到期时间（默认为 7 天）将其存储在其数据库中。
同时，MindSphere 为客户端创建另一个名为注册访问令牌 (RAT) 的令牌。当共享密钥到期时，预计客户端将使用创建的 RAT 而不是 IAT 发送注册更新请求，以便可以更新注册和密码。
这是共享密钥安全配置文件的成功注册 HTTP 响应：
HTTP/1.1 201 Created
Content-Type:application/json
Cache-Control:no-store
Pragma:no-cache
{
"client_id":"008ceaf9dff443ee94205f903aa545c4",
"token_endpoint_auth_method": "client_secret_jwt",
"grant_types": [
"client_credentials"
],
"client_secret": "ly7zmXbz0Izla6B82xlAYRVBcKDcCFatwmnHQmR8Ycw",
"client_secret_expires_at":1514206768,
"registration_access_token": "eyJraWQiOiJrZXktaWQtMSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJTQ0kiLCJzdWIiOiIwMDhjZWFmOWRmZjQ0M2VlOTQyMDVmOTAzYWE1NDVjNCIsImF1ZCI6IkFJQU0iLCJpYXQiOjE1MTM2MDE5NjgsIm5iZiI6MTUxMzYwMTk2OCwiZXhwIjoxNTE0MjA2NzY4LCJqdGkiOiIwMTNiNzU2Zi02YWZhLTRiZjYtYjY2Yi1jZTU3NWUwYmIyNzMiLCJzY29wZSI6IlJBVCIsInRlbiI6ImNvbm50ZW5hbnRvbmVxYSIsImNsaWVudF9jcmVkZW50aWFsc19wcm9maWxlIjpbIlNIQVJFRF9TRUNSRVQiXSwic2NoZW1hcyI6WyJ1cm46c2llbWVuczptaW5kc3BoZXJlOnYxIl19.KFERGKzl5YKhEnNptKYHvZWngAs07iZLR_F2DoPAuAW_rowGk3ykooztfHJoEtWvi1HlWAbtn5MX7QOE0EYyNJN-4K3PEStKLeRc6Ony9vAIzdAUhn-aP5c0fKvKeSRNpd8pxXPtMbEOIwKWUa9XmpbOwem6qkD3bvnGzqnHMiYN4dXluNNBM1uhK8rCKafW3QwOKZVYkfJgyyvAlnr978hbEHzK28g5mBZWOjx7inDmAdiD0woI39S4NoeU031bYQ8N7gnDBrqo8ZE5C_VtigRmWCFbnz_6-Qna8akW_MkhobEjmF7v74E3orb2Dfj-FosxkX0J4VhJEgD3hAwPOQ",
"registration_client_uri": "https://southgate.eu1-rc.mindsphere.io/api/agentmanagement/v3/register/008ceaf9dff443ee94205f903aa545c4"
}
| 参数 | 描述 | 备注 |
|---|---|---|
| client_id | 代理 Id | |
| token_endpoint_auth_method | 请求的令牌端点身份验证方法的 String 指示符 | 在 RFC 7591 中定义 |
| grant_types | 请求访问令牌时使用的 OAuth 2.0 访问令牌流类型。 | |
| client_secret | 生成的客户端密钥，客户端将在请求访问令牌时使用。 | |
| client_secret_expires_at | 生成的客户端密钥到期的时间。 | 如果到期，客户需要重新注册 RAT。 |
| registration_access_token | 注册访问令牌 (RAT)。 | 客户需要 RAT 更新其注册。 |
| registration_client_uri | 客户端更新其注册时使用的 URI。 |
具有 RSA 3072 安全配置文件的代理
注册代理由 Agent Management Service 的 register 端点提供。代理将发送请求文本中带有其公钥的 HTTP POST 请求。
POST /api/agentmanagement/v3/register HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization:Bearer ey...{yourIAT}
Host:authorizationserver.mindsphere.com
{
"jwks": {"keys": [
{ // RSA key created by client
"e":"AQAB",
"n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
"kty":"RSA",
"kid": "key-1"
}
]}
}
| 参数 | 描述 | 备注 |
|---|---|---|
| jwks | 客户端的 JSON Web 密钥集，文档值 | 在 RFC 7517 中定义 |
| e | 公钥指数 e | 有关详细信息，请参见 RSA 算法。 |
| n | 模数 n | 有关详细信息，请参见 RSA 算法。 |
| kty | 密钥类型 | 确定密钥使用的加密算法系列。 |
| kid | 用于匹配特定密钥的密钥 ID。 | 例如，用于在密钥滚动过程中从 JWK 集内的一组密钥中进行选择。 |
MindSphere 收到请求并进行验证（IAT 验证、强制性消息头验证等）。如果验证成功，MindSphere 会将代理公钥存储在其数据库中。
同时，MindSphere 为客户端创建另一个名为注册访问令牌 (RAT) 的令牌。当客户端密钥到期时，预计客户端将使用创建的 RAT 而不是 IAT 发送注册更新请求，以便可以更新注册。
这是 RSA 3072 安全配置文件的成功注册 HTTP 响应：
HTTP/1.1 201 Created
Content-Type:application/json
Cache-Control:no-store
Pragma:no-cache
{
"client_id": "s6BhdRkqt3", //Client ID - equals value of "sub" claim in IAT
"token_endpoint_auth_method": "private_key_jwt",
"grant_types": ["client_credentials"],
"client_secret_expires_at":1234545 // 7 days after created.
"registration_access_token": "ey..."
"registration_client_uri": "https://authorizationserver.mindsphere.com/register/s6BhdRkqt3"
}
| 参数 | 描述 | 备注 |
|---|---|---|
| client_id | 代理 Id | |
| token_endpoint_auth_method | 请求的令牌端点身份验证方法的 String 指示符。MindSphere 使用两种类型的 JWT 身份验证，具体取决于用于保护断言的密钥：client_secret_jwt使用基于哈希的消息认证码 (HMAC) 对 JWT 进行保护，该认证码使用客户端密钥进行计算。 private_key_jwt使用属于客户端的非对称密钥（RSA 或 EC）对 JWT 进行签名。 | 有关详细信息，请参见 RFC 7591，第 2 节“客户端元数据”。 |
| grant_types | 请求访问令牌时使用的 OAuth 2.0 访问令牌流类型。 | |
| client_secret | 生成的客户端密钥，客户端将在请求访问令牌时使用。 | |
| client_secret_expires_at | 生成的客户端密钥到期的时间。 | 如果到期，客户需要重新注册 RAT。 |
| registration_access_token | 注册访问令牌 (RAT) | 客户需要 RAT 更新其注册。 |
| registration_client_uri | 客户端更新其注册时使用的 URI。 |
刷新注册
默认情况下，每个已注册代理（RSA 3072 或共享密钥安全配置文件）的凭证有效期为 7 天。在此期限之后，MindSphere 将不会向代理授予访问权限，并会使代理凭证无效。代理需要向 MindSphere 重新注册，并提供其注册访问令牌 (RAT)。代理需要对 registration_client_uri 的 URL 值执行此请求。此 URL 在成功注册的 HTTP 响应 201 Created 的 JSON 文本中提供（请参见 注册代理。 部分）。
注册访问令牌没有实际的到期时间（有效期至 1000000000-12-31T23:59:59.999999999Z），但每次客户端刷新其注册时，MindSphere 都会生成一个新的 RAT。代理应在其凭证到期之前刷新其注册。
刷新代理注册由 Agent Management Service 的 register 端点提供。以下是具有共享密钥安全配置文件的代理的刷新请求示例：
PUT /api/agentmanagement/v3/register/{agent-id} HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization:Bearer ey...{yourRAT}
Host:authorizationserver.mindsphere.com
{
client_id:agentid
}
如果 RAT 正确且提供的客户端 Id 匹配，则会向客户端返回新的注册访问令牌。旧的注册访问令牌 **必须**由客户端丢弃，MindSphere 会自动丢弃旧的 RAT。
MindSphere 将返回 HTTP 响应 200 OK。JSON 文本的结构与代理的初始注册相同：
HTTP/1.1 200 OK
Content-Type:application/json
Cache-Control:no-store
Pragma:no-cache
{
client_id: 'f1e45f31-0014-4e54-b58b-2065f965f7db',
token_endpoint_auth_method: 'client_secret_jwt',
grant_types: [ 'client_credentials' ],
client_secret: 'usiRBejgh6XhOEYXpedDJZzhA4TTOw_nFmsKuyTl0NQ',
client_secret_expires_at:1516898093,
registration_access_token: 'eyJraWQiOiJqd3QiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJTQ0kiLCJzdWIiOiJmMWU0NWYzMS0wMDE0LTRlNTQtYjU4Yi0yMDY1Zjk2NWY3ZGIiLCJhdWQiOiJBSUFNIiwiaWF0IjoxNTE2MjkzMjkzLCJuYmYiOjE1MTYyOTMyOTMsImV4cCI6MzE1NTY4ODk4NjQ0MDMxOTksImp0aSI6IjY0YmQxNTcyLTEyNmItNDI0My1hNWJmLWVjMzAxNTNmYTNmNCIsInNjb3BlIjoiUkFUIiwidGVuIjoibXlUZW5hbnRJZCIsImNsaWVudF9jcmVkZW50aWFsc19wcm9maWxlIjpbIlNIQVJFRF9TRUNSRVQiXSwic2NoZW1hcyI6WyJ1cm46c2llbWVuczptaW5kc3BoZXJlOnYxIl19.LOnsuClqKFMMf_5aE-y0al2cPIgrX8S92GBw_owVHPEfvPzVW_6ISffDy_Oa944dqHT0tmXg8VwR7PhnP0PQK4rQkFsuLOI_lf84xevVnmjbVov5Lqg4WTP9hxxIe9PFzQ8DdpTx4KSwEvUEftqv694sK4lY2EKAyuAQWfjPMifhUwpyCt9dQkcpHf87YygDThrj9AoBmC--LUnvYZzMGpS9IvnAZaq22AKuzv-B-j31L5vCO_J6GrqN7zS6goYewinFuKeS14rDCGE-bgdwyZMpkv4BdyUmnQgQIxlIrsWJH1X3j9ZIQKlFpN8F0eY1TlfpIJ4rqkqwnRbL_WsLUQ',
registration_client_uri: 'https://southgate.eu1.mindsphere.io/api/agentmanagement/v3/register/f1e45f31-0014-4e54-b58b-2065f965f7db'
}
| 参数 | 描述 | 备注 |
|---|---|---|
| client_id | 代理 Id | |
| token_endpoint_auth_method | 请求的令牌端点身份验证方法的 String 指示符 | 在 RFC 7591 中定义 |
| grant_types | 请求访问令牌时使用的 OAuth 2.0 访问令牌流类型。 | |
| client_secret | 生成的客户端密钥，客户端将在请求访问令牌时使用。 | |
| client_secret_expires_at | 生成的客户端密钥到期的时间。 | 如果到期，客户需要重新注册 RAT。 |
| registration_access_token | 注册访问令牌 (RAT)。 | 客户需要 RAT 更新其注册。 |
| registration_client_uri | 客户端更新其注册时使用的 URI。 |
对于具有 RSA 3072 安全配置文件的代理，注册刷新过程相同。只有注册刷新请求 HTTP 主体略有变化：
PUT /api/agentmanagement/v3/register/{agent-id} HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization:Bearer ey...{yourRAT}
Host:authorizationserver.mindsphere.com
{
"jwks": {"keys": [
{ // RSA key created by client
"e":"AQAB",
"n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
"kty":"RSA",
"kid": "key-1"
}
]}
}
代理状态和令牌处理
以下图表阐述了可用的代理状态和相关的令牌处理：
相关链接
还有问题?
除非另行声明，该网站内容遵循MindSphere开发许可协议.
Last update: June 26, 2019