太空地图开放鉴权指南
更新时间：2024-03-29 15:30:00
概述
太空地图服务采用OAuth 2.0开放授权协议，允许第三方应用在获得用户授权后安全访问太空地图资源，而无需获取用户的用户名和密码。
接入前准备
在开始集成前，您需要完成以下步骤：
- 注册太空地图账号：访问太空地图平台并完成注册。
- 创建应用：在个人中心-我的应用创建一个新应用，获取应用的唯一标识：应用ID（app_id）。
- 添加授权：在弹出的界面中创建当前应用标识码
- 配置回调地址：设置一个用于接收授权码的重定向URI（redirect_uri）。
支持的授权模式
太空地图服务支持以下两种授权模式，请根据您的应用类型选择：
| 授权模式 | 描述 | 适用场景 |
|---|---|---|
| 授权码模式（Authorization Code） | 用户授权后，服务端返回授权码（Code），应用再使用此Code向后端令牌端点交换访问令牌（Access Token）。 | 应用有后端服务器，能够安全地存储和使用客户端密钥（client_secret），例如传统的Web应用。 |
| 授权码扩展模式（PKCE） | 授权码模式的增强扩展，通过动态创建并验证代码验证器（code_verifier）和挑战值（code_challenge）来提升安全性，无需使用客户端密钥。 | 应用没有后端服务器或无法安全存储密钥，例如单页应用（SPA）、移动应用程序（App）。 |
授权码模式（Authorization Code）接入流程
第一步：构造授权请求
构建太空地图授权请求端点，请求用户授权。接口地址为 GET /cgi/oauth/authorize。
请求示例URL
https://spacemapp.cn/cgi/oauth/authorize?
response_type=code&
client_id=<您的客户端ID>&
redirect_uri=<应用的回调地址>&
state=<随机串>&
scope=
主要请求参数说明：
| 参数 | 必选 | 说明 |
|---|---|---|
response_type | 是 | 填写为 code，表示为授权码模式。 |
client_id | 是 | 应用的唯一标识。使用应用ID（app_id） |
redirect_uri | 是 | 用户授权后重定向的URI，需与注册时设置的一致。 |
scope | 否 | 留空 |
state | 是 | 用户用于保持状态跟踪的数据，在授权完成后原样返回，例如:goodsld=1®ld=201208e393f0e423。在值中应有部份内容是一个具有随机性短时间内是唯一的值，例如上述的reqId，用于CSRF安全。 |
access_type | 否 | 设置为 offline 以在首次授权时获取刷新令牌（Refresh Token）。 |
第二步：用户登录与授权
用户被引导至太空地图登录页面，并在此登录。
第三步：接收授权码
用户授权后，浏览器将被重定向到您指定的 redirect_uri，并在URL中附带授权码。
成功响应示例
https://yourapp.com/callback?
code=<返回的授权码Code>&
state=state_parameter_passthrough_value第四步：使用授权码换取访问令牌
应用后端使用收到的授权码，向令牌端点请求访问令牌。接口地址为 POST /cgi/oauth/token。
请求示例
POST /cgi/oauth/oauth/token HTTP/1.1
Host: spacemapp.cn
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=<返回的授权码Code>&
client_id=<您的客户端ID>&
client_secret=<您的客户端密钥>&
redirect_uri=<应用的回调地址>请求参数说明：
| 参数 | 必选 | 说明 |
|---|---|---|
grant_type | 是 | OAuth 2.0规范定义的字段，必须为authorization_code。 |
code | 是 | 上一步获取的授权码。Code有效期为5分钟，且只能请求一次。 |
client_id | 是 | 在接入前准备中得到的OAuth 2.0客户端ID，对于AppGallery Connect类应用，该值为应用的APP ID。 |
client_secret | 是 | 在接入前准备中给客户端ID分配的密钥，对于AppGallery Connect类应用，该值为应用的APP SECRET。 |
redirect_uri | 是 | 与第一步中的 redirect_uri 一致。 |
成功响应示例
{
"access_token": "<返回的Access Token>",
"expires_in": 3600,
"refresh_token": "<返回的Refresh Token>",
"token_type": "Bearer",
"scope": "profile openid"
}| 参数 | 必选 | 说明 |
|---|---|---|
access_token | 是 | 用户的Access Token。 |
expires_in | 是 | Access Token的剩余有效期，单位：秒。 |
token_type | 是 | 固定返回Bearer，标识返回Access Token的类型。 |
scope | 是 | 生成的Access Token中包含的scope。 |
refresh_token | 是 | 若入参中包含access_type=offline，则会返回此参数，该参数用于刷新Access Token。 |
授权码扩展模式（PKCE）接入流程
PKCE模式通过一个由客户端动态生成的代码验证器（Code Verifier）和其转换后的代码挑战（Code Challenge）来增强安全性，特别适合公共客户端。
第一步：生成 Code Verifier 和 Code Challenge
在发起授权请求前，客户端需要先生成一个高熵的随机字符串作为 Code Verifier，然后对其进行哈希（通常使用S256算法）和Base64URL编码，得到 Code Challenge。
第二步：构造授权请求（附带PKCE参数）
接口地址同样为 GET /cgi/oauth/authorize，但需额外携带PKCE相关参数。
请求示例URL
https://spacemapp.cn/cgi/oauth/authorize?
response_type=code&
client_id=<客户端ID>&
redirect_uri=<应用的回调地址>&
scope=openid+<业务的权限scope>&
state=state_parameter_passthrough_value&
code_challenge=ovoy4lehgHbv8uNmif_hak3bH2_Ylk6_fWP0UL232QQ&
code_challenge_method=S256新增PKCE参数说明：
| 参数 | 必选 | 说明 |
|---|---|---|
response_type | 是 | 填写为"code"，表示为授权码扩展模式。 |
client_id | 是 | 在接入前准备中得到的OAuth 2.0客户端ID，对于AppGallery Connect类应用，该值为应用的APP ID。 |
redirect_uri | 是 | 授权后要回调的地址URL，即开发者应用接收授权码code的URL。 |
code_challenge_method | 是 | 对code_verifier进行编码的方法。当前支持两个枚举值，建议S256。 · plain：原文，不编码 · S256：code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) |
code_challenge | 是 | code_verifier进行编码后的值。 |
scope | 是 | 固定值，profile |
state | 是 | 用户用于保持状态跟踪的数据，在授权完成后原样返回，例如:goodsld=1®ld=201208e393f0e423。在值中应有部份内容是一个具有随机性短时间内是唯一的值，例如上述的reqId，用于CSRF安全。 |
第三步：用户登录与授权
用户被引导至太空地图登录页面，并在此登录。
第四步：接收授权码
用户授权后，浏览器将被重定向到您指定的 redirect_uri，并在URL中附带授权码。
成功响应示例
https://yourapp.com/callback?
code=<返回的授权码Code>&
state=state_parameter_passthrough_value第五步：使用授权码和Code Verifier换取访问令牌
应用在请求令牌时，必须提供之前生成的 Code Verifier。接口地址为 POST /cgi/oauth/token。
请求示例
POST /cgi/oauth/token HTTP/1.1
Host: spacemapp.cn
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=<返回的授权码Code>&
client_id=<客户端ID >&
redirect_uri=<应用的回调地址>&
code_verifier=123444444dfd4sadfsdwew321454567587658776t896fdfgdscvvbfxdgfdgfdsfasdfsdgd233| 参数 | 必选 | 说明 |
|---|---|---|
grant_type | 是 | OAuth 2.0规范定义的字段，必须为"authorization_code"。 |
code | 是 | 上一步获取的授权码。Code有效期为5分钟，且只能请求一次。 |
client_id | 是 | 在接入前准备中得到的OAuth 2.0客户端ID，对于AppGallery Connect类应用，该值为应用的APP ID。 |
code_verifier | 是 | 随机字符串，必须与编码前的字符串一致，用来验证authorize请求和token请求来自于同一个客户端。 |
redirect_uri | 是 | 授权后要回调的地址URL，即开发者应用接收授权码code的URL。与上一步中传入的回调地址一致。 |
注意：在PKCE流程中，请求通常不包含 client_secret。
成功响应示例
{
"access_token": "<返回的Access Token>",
"expires_in": 3600,
"refresh_token": "<返回的Refresh Token>",
"token_type": "Bearer",
"scope": "profile openid"
}| 参数 | 必选 | 说明 |
|---|---|---|
access_token | 是 | 用户的Access Token。 |
expires_in | 是 | Access Token的剩余有效期，单位：秒。 |
token_type | 是 | 固定返回Bearer，标识返回Access Token的类型。 |
scope | 是 | 生成的Access Token中包含的scope。 |
refresh_token | 是 | 若入参中包含access_type=offline，则会返回此参数，该参数用于刷新Access Token。 |
使用访问令牌调用API
获取到访问令牌（Access Token）后，即可在请求头中携带它来调用受保护的太空地图API。例如，获取用户信息的接口为 GET /cgi/oauth/userinfo。
请求示例
GET /cgi/oauth/userinfo HTTP/1.1
Host: spacemapp.cn
Authorization: Bearer ACCESS_TOKEN安全注意事项
- 令牌安全：访问令牌和刷新令牌是敏感凭证，必须妥善存储，防止泄露。所有通信必须通过HTTPS进行。
- state参数：这是一个必填项，值中需要包含一个在一段时间内不重复的值，以有效防范CSRF攻击。
测试终端
- 为了方便用户使用，我们提供了用于验证的客户端，覆盖两种模式：
- 模式一 授权码认证模式：
- 适用场景：具备后端服务器的Web应用，移动ＡPP，可安全存储密钥
- 访问地址：https://aseem.cn/examples/oauth2/client/auth-code.html
- 模式二 PKCE认证模式：
- 适用场景：原生应用，单页应用，H5应用
- 访问地址：https://aseem.cn/examples/oauth2/client/pkce.html
