环境准备 - 应用身份服务

在使用 Go SDK 获取 M2M 客户端令牌前，需按照本文提供的步骤来准备环境。

环境要求

安装 Go 1.18 及以上版本（需支持泛型）；
已配置 GOPROXY（推荐：https://goproxy.cn,direct 或 https://proxy.golang.org,direct），保证可以正常拉取模块。

安装 Go SDK

Core SDK

Core SDK 仓库地址：https://github.com/cloud-idaas/idaas-go-core-sdk

Core SDK 最新版本参考：https://pkg.go.dev/github.com/cloud-idaas/idaas-go-core-sdk

在你的 Go 项目根目录下，通过 go get 安装依赖：

go get github.com/cloud-idaas/idaas-go-core-sdk

# 或安装指定版本
go get github.com/cloud-idaas/idaas-go-core-sdk@vX.Y.Z

在代码中按需导入对应的子包即可使用，例如：

import (
    "github.com/cloud-idaas/idaas-go-core-sdk/config"
    "github.com/cloud-idaas/idaas-go-core-sdk/factory"
)

阿里云认证扩展插件

此外，IDaaS SDK 支持 OpenAPI 认证方式，在函数计算（FC）等场景下，可以使用阿里云的身份凭证（AK/SK、STS）获取 M2M 客户端令牌。使用该认证方式，还需要额外安装阿里云认证方式扩展插件。

阿里云认证扩展插件仓库地址：https://github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin

阿里云认证扩展插件最新版本参考：https://pkg.go.dev/github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin

go get github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin

# 或安装指定版本
go get github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin@vX.Y.Z

安装完成后，在代码中匿名导入插件包即可触发自动注册，无需手动初始化：

import _ "github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin"

路径说明

配置文件的默认路径：~/.cloud_idaas/client-config.json。如未明确指定，SDK 默认从该路径下获取配置文件。

也可以通过环境变量或初始化传参指定配置文件路径：

环境变量名：CLOUD_IDAAS_CONFIG_PATH
环境变量示例：export CLOUD_IDAAS_CONFIG_PATH=/.../client-config.json
初始化传参示例：reader.LoadWithPriority("/.../client-config.json")

配置加载优先级（从高到低）：

显式文件路径（作为 LoadWithPriority 参数传入）
环境变量 CLOUD_IDAAS_CONFIG_PATH
默认路径 ~/.cloud_idaas/client-config.json
各个独立的环境变量

配置文件说明

配置文件示例如下：

{
    "idaasInstanceId": "idaas_xxx",
    "clientId": "app_xxx",
    "issuer": "https://xxx/api/v2/iauths_system/oauth2",
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|read:file",
    "openApiEndpoint": "eiam.[region_id].aliyuncs.com",
    "developerApiEndpoint": "eiam-developerapi.[region_id].aliyuncs.com",
    "authnConfiguration": {
        "authnMethod": "CLIENT_SECRET_POST",
        "identityType": "CLIENT",
        "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
    },
    "httpConfiguration": {
        "connectTimeout": 5000,
        "readTimeout": 10000
    }
}

参数说明

字段名	备注
idaasInstanceId	必填，IDaaS EIAM 的实例 ID。
clientId	必填，IDaaS 应用的应用 ID，可在对应 IDaaS 应用中查看。
issuer	必填，IDaaS EIAM 实例的 Issuer 端点，可在 IDaaS EIAM 实例下的任意 M2M 应用中查看。
tokenEndpoint	必填，IDaaS EIAM 实例的令牌端点，可在 IDaaS EIAM 实例下的任意 M2M 应用中查看。
scope	必填，指定要访问的 M2M 服务端应用的受众标识和权限标识，格式为 `受众标识
openApiEndpoint	可选，阿里云 EIAM OpenAPI 端点，格式为 `eiam.[region_id].aliyuncs.com`，插件认证方式下由插件调用 EIAM OpenAPI `GenerateOauthToken` 时使用。
developerApiEndpoint	可选，阿里云 EIAM DeveloperAPI 端点，格式为 `eiam-developerapi.[region_id].aliyuncs.com`。
deployEnvironment	可选，部署环境标识。Go SDK 特有字段，用于标识当前运行环境。常用取值：`LOCAL`（本地开发环境）、`ALIBABA_CLOUD_ECS`（阿里云 ECS 环境）。该字段与 authnConfiguration 中的 `clientDeployEnvironment` 不同：前者为全局部署环境标识，后者仅在 PKCS7/OIDC 联邦认证场景下指定联邦凭证来源环境。
authnConfiguration	认证配置，详细字段参见下方 authnMethod 字段值和 authnConfiguration 字段对应关系。 identityType：可选，默认值为`CLIENT`，目前只支持`CLIENT`，表示 M2M 客户端应用以机器身份进行认证。。
httpConfiguration	HTTP 协议相关配置，包含 2 个字段（单位为毫秒）：connectTimeout（可选，客户端与服务端建立连接的最大等待时间，默认 5000）、readTimeout（可选，连接建立后客户端等待服务端返回数据的最大等待时间，默认 10000）。

authnMethod 字段值和 authnConfiguration 字段对应关系

authnMethod	需要的 authnConfiguration 字段	authnConfiguration 字段说明
CLIENT_SECRET_BASIC	clientSecretEnvVarName	M2M 客户端应用的 Client Secret 的环境变量名称，secret 通过 HTTP Basic Auth 头发送。
CLIENT_SECRET_POST	clientSecretEnvVarName	M2M 客户端应用的 Client Secret 的环境变量名称，secret 通过 form body 字段发送。
PRIVATE_KEY_JWT	clientSecretEnvVarName	M2M 客户端应用的 Client Secret 的环境变量名称，SDK 用 secret 做 HS256 签名生成 JWT 客户端断言。
PRIVATE_KEY_JWT	privateKeyEnvVarName	M2M 客户端应用的 Private Key（PEM 格式）的环境变量名称，SDK 用私钥做 RS256/ES256 签名生成 JWT 客户端断言。
PCA	privateKeyEnvVarName、clientX509Certificate、x509CertChains、applicationFederatedCredentialName	Private CA 证书认证。需要 PEM 私钥（用于签 JWT）+ 终端证书 + 中间证书链 + 联邦凭证名。
PKCS7	applicationFederatedCredentialName、clientDeployEnvironment	PKCS#7 联邦认证，配合 `clientDeployEnvironment=ALIBABA_CLOUD_ECS` 使用。SDK 自动从 ECS Metadata Service 获取 attested document。
OIDC	applicationFederatedCredentialName、clientDeployEnvironment	OIDC 联邦认证，配合 `clientDeployEnvironment=KUBERNETES` 使用。SDK 自动读取 K8s SA Token。
PLUGIN	pluginName	自定义凭证提供器的插件名称，必须在 PluginRegistry 中注册。

配置参数示例

Client Secret 凭证配置示例

{
    "idaasInstanceId": "idaas_xxx",
    "clientId": "app_xxx",
    "issuer": "https://xxx/api/v2/iauths_system/oauth2",
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|read:file",
    "authnConfiguration": {
        "authnMethod": "CLIENT_SECRET_POST",
        "identityType": "CLIENT",
        "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
    },
    "httpConfiguration": {
      "connectTimeout": 5000,
      "readTimeout": 10000
    }
}

公私钥凭证配置示例

{
    "idaasInstanceId": "idaas_xxx",
    "clientId": "app_xxx",
    "issuer": "https://xxx/api/v2/iauths_system/oauth2",
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|read:file",
    "authnConfiguration": {
        "authnMethod": "PRIVATE_KEY_JWT",
        "identityType": "CLIENT",
        "privateKeyEnvVarName": "IDAAS_PRIVATE_KEY"
    },
    "httpConfiguration": {
      "connectTimeout": 5000,
      "readTimeout": 10000
    }
}

阿里云 ECS 配置示例（PKCS7 联邦认证）

{
    "idaasInstanceId": "idaas_xxx",
    "clientId": "app_xxx",
    "issuer": "https://xxx/api/v2/iauths_system/oauth2",
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|.all",
    "authnConfiguration": {
        "authnMethod": "PKCS7",
        "identityType": "CLIENT",
        "applicationFederatedCredentialName": "aliyun_ecs",
        "clientDeployEnvironment": "ALIBABA_CLOUD_ECS"
    },
    "httpConfiguration": {
      "connectTimeout": 5000,
      "readTimeout": 10000
    }
}

Kubernetes OIDC 配置示例

{
    "idaasInstanceId": "idaas_xxx",
    "clientId": "app_xxx",
    "issuer": "https://xxx/api/v2/iauths_system/oauth2",
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|read:file",
    "authnConfiguration": {
        "authnMethod": "OIDC",
        "identityType": "CLIENT",
        "applicationFederatedCredentialName": "k8s_federation",
        "clientDeployEnvironment": "KUBERNETES"
    },
    "httpConfiguration": {
      "connectTimeout": 5000,
      "readTimeout": 10000
    }
}

插件认证配置示例（阿里云 OpenAPI 认证）

使用阿里云身份凭证（AK/SK、STS）获取 M2M 客户端令牌时，需配合阿里云认证扩展插件使用。

{
    "idaasInstanceId": "idaas_xxx",
    "clientId": "app_xxx",
    "issuer": "https://xxx/api/v2/iauths_system/oauth2",
    "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
    "scope": "api.example.com|read:file",
    "openApiEndpoint": "eiam.cn-hangzhou.aliyuncs.com",
    "authnConfiguration": {
        "authnMethod": "PLUGIN",
        "identityType": "CLIENT",
        "pluginName": "alibabacloudPluginCredentialProvider"
    },
    "httpConfiguration": {
      "connectTimeout": 5000,
      "readTimeout": 10000
    }
}