Set up environment for Go SDK - Identity as a Service - Alibaba Cloud Documentation Center

Before you use the Go SDK to obtain an M2M client token, you must prepare the environment as described in this topic.

Environment requirements

Install Go 1.18 or later (required for generics support).
Configure GOPROXY to ensure modules can be pulled successfully. Use a recommended proxy, such as https://goproxy.cn,direct or https://proxy.golang.org,direct.

Install the Go SDK

Core SDK

The Core SDK repository is available at https://github.com/cloud-idaas/idaas-go-core-sdk.

For the latest version of the Core SDK, see https://pkg.go.dev/github.com/cloud-idaas/idaas-go-core-sdk.

In the root directory of your Go project, use the go get command to install the dependencies:

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

# Or install a specific version
go get github.com/cloud-idaas/idaas-go-core-sdk@vX.Y.Z

You can import the required sub-packages in your code as needed. For example:

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

Alibaba Cloud authentication plugin

The IDaaS SDK supports OpenAPI authentication. In scenarios such as Function Compute (FC), you can use Alibaba Cloud identity credentials (AK/SK or STS) to obtain M2M client tokens. To use this authentication method, you must also install the Alibaba Cloud authentication plugin.

The Alibaba Cloud authentication plugin repository is available at https://github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin.

For the latest version of the Alibaba Cloud authentication plugin, see 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

# Or, install a specific version
go get github.com/cloud-idaas/idaas-go-core-alibabacloud-authentication-plugin@vX.Y.Z

After installation, you can anonymously import the plugin package in your code to trigger automatic registration. No manual initialization is required.

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

Path description

The default path for the configuration file is ~/.cloud_idaas/client-config.json. If you do not specify a path, the SDK loads the configuration file from this default location.

You can also specify the path to the configuration file using an environment variable or by passing the path as a parameter during initialization:

Environment variable name: CLOUD_IDAAS_CONFIG_PATH
Environment variable example: export CLOUD_IDAAS_CONFIG_PATH=/.../client-config.json
Initialization parameter example: reader.LoadWithPriority("/.../client-config.json")

Configuration loading priority (from highest to lowest):

The file path passed as a parameter to LoadWithPriority
The CLOUD_IDAAS_CONFIG_PATH environment variable
The default path: ~/.cloud_idaas/client-config.json
Individual environment variables

Configuration file

The following is an example configuration file:

{
    "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
    }
}

Parameters

Field name	Description
idaasInstanceId	Required. The instance ID of IDaaS EIAM.
clientId	Required. The ID of the IDaaS application. Find this ID in the corresponding IDaaS application.
issuer	Required. The issuer endpoint of the IDaaS EIAM instance. Find this endpoint in any M2M application under the IDaaS EIAM instance.
tokenEndpoint	Required. The token endpoint of the IDaaS EIAM instance. Find this endpoint in any M2M application under the IDaaS EIAM instance.
scope	Required. The audience and permission identifiers for the M2M server-side application that you want to access. The format is `Audience\|Permission`.
openApiEndpoint	Optional. The Alibaba Cloud EIAM OpenAPI endpoint. The format is `eiam.[region_id].aliyuncs.com`. This is used when a plugin calls the EIAM OpenAPI `GenerateOauthToken` for plugin-based authentication.
developerApiEndpoint	Optional. The Alibaba Cloud EIAM DeveloperAPI endpoint. The format is `eiam-developerapi.[region_id].aliyuncs.com`.
deployEnvironment	Optional. The deployment environment identifier. This field is specific to the Go software development kit (SDK) and identifies the current runtime environment. Common values are `LOCAL` for a local development environment and `ALIBABA_CLOUD_ECS` for an Alibaba Cloud ECS environment. This field differs from `clientDeployEnvironment` in `authnConfiguration`. `deployEnvironment` is a global identifier for the deployment environment, whereas `clientDeployEnvironment` specifies the source environment of the federated credential only in PKCS7 and OpenID Connect (OIDC) federation scenarios.
authnConfiguration	Authentication configuration. For details about the fields, see Relationship between authnMethod and authnConfiguration fields below. identityType: Optional. The default value is `CLIENT`. Currently, only `CLIENT` is supported. This indicates that the M2M client application authenticates as a machine identity.
httpConfiguration	HTTP protocol configuration. This includes two fields in milliseconds: `connectTimeout` (Optional. The maximum time to wait to establish a connection. The default is 5000.) and `readTimeout` (Optional. The maximum time to wait for data from the server after a connection is established. The default is 10000.).

Relationship between authnMethod and authnConfiguration fields

authnMethod	Required authnConfiguration fields	authnConfiguration field description
CLIENT_SECRET_BASIC	clientSecretEnvVarName	The name of the environment variable for the client secret of the M2M client application. The secret is sent in the HTTP Basic Auth header.
CLIENT_SECRET_POST	clientSecretEnvVarName	The name of the environment variable for the client secret of the M2M client application. The secret is sent in the form body.
PRIVATE_KEY_JWT	clientSecretEnvVarName	The name of the environment variable for the client secret of the M2M client application. The SDK uses the secret to generate a JSON Web Token (JWT) client assertion with an HS256 signature.
PRIVATE_KEY_JWT	privateKeyEnvVarName	The name of the environment variable for the private key (in PEM format) of the M2M client application. The SDK uses the private key to generate a JWT client assertion with an RS256 or ES256 signature.
PCA	privateKeyEnvVarName, clientX509Certificate, x509CertChains, applicationFederatedCredentialName	Private Certificate Authority (CA) authentication. Requires a PEM private key for signing JWTs, an end-entity certificate, an intermediate certificate chain, and a federated credential name.
PKCS7	applicationFederatedCredentialName, clientDeployEnvironment	PKCS#7 federated authentication. Use with `clientDeployEnvironment=ALIBABA_CLOUD_ECS`. The SDK automatically gets the attested document from the ECS Metadata Service.
OIDC	applicationFederatedCredentialName, clientDeployEnvironment	OIDC federated authentication. Use with `clientDeployEnvironment=KUBERNETES`. The SDK automatically reads the Kubernetes Service Account (SA) token.
PLUGIN	pluginName	The name of the plugin for the custom credential provider. It must be registered in the PluginRegistry.

Configuration parameter examples

Client secret credential configuration example

{
    "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
    }
}

Public and private key credential configuration example

{
    "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
    }
}

Alibaba Cloud ECS configuration example (PKCS7 federated authentication)

{
    "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 configuration example

{
    "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
    }
}

Plugin authentication configuration example (Alibaba Cloud OpenAPI authentication)

You can use the Alibaba Cloud authentication plugin with Alibaba Cloud identity credentials, such as an AccessKey/SecretKey (AK/SK) or a Security Token Service (STS) token, to obtain machine-to-machine (M2M) client tokens.

{
    "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
    }
}