基于 API 密钥的集成

“SiX统一认证与授权” 除了提供直观的 控制台界面 用于管理租户内的身份验证与授权资产外，还支持通过 集成密钥 (Integration Key) 进行程序化集成。

适用场景

1. 自动化资产管理

如果您的业务逻辑需要通过代码自动化管理身份资产（如批量创建用户、配置应用或调整权限），而非通过手动操作 UI，您可以使用“集成密钥”调用底层的 RESTful API 来实现。

2. 保护自定义 API 服务

如果您正根据 基于 IAM 开发自己的 API 方案构建业务接口，并计划将这些接口开放给您的客户或合作伙伴，则可以利用“集成密钥”作为凭证，实现对这些 API 的细粒度访问控制。

授权模型

“集成密钥”采用了与 IdP (身份应用程序) 用户高度一致的授权模型，确保了权限管理的一致性与灵活性：

• 组权限映射：您可以将集成密钥分配至不同的用户组，从而使其继承该组定义的权限集。
• 自定义属性：支持为密钥设置自定义属性 (Custom Properties)，便于在后端逻辑中进行业务标签识别、多租户路由或配额管理。

访问平台 API 的基本步骤

使用以下步骤创建集成密钥以访问平台或您自己开发的 API。

注意

集成密钥需要先进行身份验证才能成功访问平台 API。

1. 创建集成密钥并授予授权

登录“SiX统一认证与授权”控制台，导航到“服务/集成密钥 -> 创建集成密钥”按照说明创建一个集成密钥。

提示

集成密钥需要先进行身份验证才能成功访问平台 API。

下载RSA256私钥并将密钥ID复制到本地PC以供后面的使用。

注意

RSA256 私钥只会在控制台上出现一次，并且不会保留在“SiX统一认证与授权”租户存储中。

切勿将此密钥暴露给无意使用，因为它充当集成密钥的凭据！

通过设置密钥的属性和或将其放入不同的授权组中来授予授权，根据您具体的设计。

2. 验证集成密钥并获取访问令牌

使用 RSA256 私钥和密钥 ID 生成 JWT

使用您下载的私钥和密钥ID创建JWT并对其进行签名。

创建 JWT 的示例代码片段：

创建 JWT 并使用私钥签名

  public static String createJwtBearerTokenWithRsaPrivateKey(String pemEncodedRSAPrivateKey, String keyId, int expiringInSeconds) throws JOSEException {
        //Convert the x509 RSA private key in PEM format to JWK
        JWK jwk = JWK.parseFromPEMEncodedObjects(pemEncodedRSAPrivateKey);
        RSAKey rsaJWK = jwk.toRSAKey();
        long expiringTime = new Date().getTime() + expiringInSeconds * 1000;
        JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
                .subject(keyId) //set the keyId as subject
                .expirationTime(new Date(expiringTime))
                .build();
        SignedJWT signedJWT = new SignedJWT(
                new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(keyId).build(),
                claimsSet);
        //Create signer from the private key
        JWSSigner signer = new RSASSASigner(rsaJWK);
        signedJWT.sign(signer);
        String jwt = signedJWT.serialize();
        System.out.println(jwt);
        return jwt;
    }

使用 JWT 交换访问令牌

使用“/oauth2/token”端点将JWT交换为访问令牌，授权标头需要如下：

标头名称	标头值
assertion	$JWT
grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer

3. 使用访问令牌访问平台API。

将访问令牌放入“Authorization: Bearer ${access token}”请求标头中，然后访问下面列出的平台 API：

IDaaS 和 IAM 管理 API

设备 API

访问您自己的 API 的基本步骤

1. 创建集成密钥并授予授权

登录“SiX统一认证与授权”控制台，导航到“服务/集成密钥 -> 创建集成密钥”按照说明创建一个集成密钥。

提示

集成密钥需要先进行身份验证，才能成功访问平台API。

下载RSA256私钥并将密钥ID复制到本地PC以供后面使用。

注意

RSA256 私钥只会在控制台上出现一次，并且不会保留在“SiX统一认证与授权”租户存储中。

切勿将此密钥暴露给无意使用，因为它充当集成密钥的凭据！

通过设置密钥的属性和或将其放入不同的授权组中来授予授权，根据您具体的设计。

2. 验证集成密钥并获取访问令牌

使用RSA256私钥和密钥ID生成 JWT

使用您下载的私钥和密钥ID创建JWT并对其进行签名。

创建 JWT 的示例代码片段：

创建 JWT 并使用私钥签名

public static String createJwtBearerTokenWithRsaPrivateKey(String pemEncodedRSAPrivateKey, String keyId, int expiringInSeconds) throws JOSEException {
        //Convert the x509 RSA private key in PEM format to JWK
        JWK jwk = JWK.parseFromPEMEncodedObjects(pemEncodedRSAPrivateKey);
        RSAKey rsaJWK = jwk.toRSAKey();
        long expiringTime = new Date().getTime() + expiringInSeconds * 1000;
        JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
                .subject(keyId) //set the keyId as subject
                .expirationTime(new Date(expiringTime))
                .build();
        SignedJWT signedJWT = new SignedJWT(
                new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(keyId).build(),
                claimsSet);
        //Create signer from the private key
        JWSSigner signer = new RSASSASigner(rsaJWK);
        signedJWT.sign(signer);
        String jwt = signedJWT.serialize();
        System.out.println(jwt);
        return jwt;
    }

使用JWT交换访问令牌

使用“/oauth2/token”端点将 JWT 交换为访问令牌，授权标头需要如下：

标头名称	标头值
assertion	$JWT
grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer

3. 使用访问令牌访问您自己的 API。

将访问令牌放入您的 API 请求中，例如放入标头中，然后调用您自己开发的 API。

提示

在允许 API 访问之前，您的资源服务器需要先验证访问令牌的真实性，有关更多信息，请参阅：

通过 JWK 验证访问令牌

对于平台API的访问，此验证将默认执行。