Describes how to configure the IDaaS Python SDK in a cloud environment, including installing Python dependencies, configuring the authentication method, and setting parameters for multiple credential types. - Identity as a Service

Environment requirements

Install Python 3.9 or later.
Install pip.

Install the Python SDK

For the latest version of the Core SDK, see cloud-idaas-core on PyPI.

Install the dependency in your Python environment with pip:

pip install cloud-idaas-core

# Or install a specific version, replacing x.x.x with the version number
pip install cloud-idaas-core==x.x.x

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

For the latest version of the Alibaba Cloud authentication extension plugin, see cloud-idaas-core-alibabacloud-authentication-plugin on PyPI.

pip install cloud-idaas-core-alibabacloud-authentication-plugin

# Or install a specific version, replacing x.x.x with the version number
pip install cloud-idaas-core-alibabacloud-authentication-plugin==x.x.x

Configuration file path

Default configuration file path: ~/.cloud_idaas/client-config.json.

You can also specify the configuration file path by using an environment variable or an initialization parameter:

Environment variable name: CLOUD_IDAAS_CONFIG_PATH

Environment variable example:

CLOUD_IDAAS_CONFIG_PATH=/.../client-config.json

Initialization parameter example:

IDaaSCredentialProviderFactory.init("/.../client-config.json")

Configuration file

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": {
    "identityType": "CLIENT",
    "authnMethod": "CLIENT_SECRET_POST",
    "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Parameters

Field	Description
idaasInstanceId	Required. The instance ID of IDaaS EIAM.
clientId	Required. The application ID of the IDaaS application. You can view it in the IDaaS application.
issuer	Required. The Issuer endpoint of the IDaaS EIAM instance. You can view it in any M2M application under the IDaaS EIAM instance.
tokenEndpoint	Required. The token endpoint of the IDaaS EIAM instance. You can view it in any M2M application under the IDaaS EIAM instance.
scope	Required. The audience identifier and the permission identifier of the M2M server-side application that you want to access. Format: `Audience identifier\|Permission identifier`. To obtain an STS token or the credentials of a RAM role hosted in IDaaS, set this field to the fixed value `urn:cloud:idaas:pam\|.all`, which indicates a built-in IDaaS scope.
openApiEndpoint	Optional. The OpenAPI endpoint of IDaaS, used for OpenAPI authentication. Get the service endpoint from the Identity as a Service (IDaaS EIAM) - Alibaba Cloud OpenAPI Developer Portal. If your application is deployed in an Alibaba Cloud VPC in the same region as the IDaaS instance, you can access the endpoint through the internal VPC address. See the VPC address in the Alibaba Cloud OpenAPI Developer Portal.
developerApiEndpoint	Optional. The DeveloperAPI endpoint of IDaaS, used to obtain an STS token or the credentials of a RAM role hosted in IDaaS. Get the service endpoint from the Identity as a Service (IDaaS EIAM) - Alibaba Cloud OpenAPI Developer Portal. If your application is deployed in an Alibaba Cloud VPC in the same region as the IDaaS instance, you can access the endpoint through the internal VPC address. See the VPC address in the Alibaba Cloud OpenAPI Developer Portal.
authnConfiguration	identityType: Optional. Default value: `CLIENT`. Only `CLIENT` is supported, which indicates that the M2M client application authenticates as a machine identity. authnMethod: Required. The authentication method. The required authnConfiguration fields vary with the authentication method. For details about the mapping, see Mapping between authnMethod values and authnConfiguration fields.
httpConfiguration	HTTP-related configuration, which contains two fields: connectTimeout: Optional. The maximum period of time, in milliseconds, that the client waits to establish a connection to the server. Default value: 5000. readTimeout: Optional. The maximum period of time, in milliseconds, that the client waits for the server to return data after the connection is established. Default value: 10000.

Mapping between authnMethod values and authnConfiguration fields

authnMethod	Required authnConfiguration fields	authnConfiguration field description
CLIENT_SECRET_BASIC	clientSecretEnvVarName	The field value is the name of an environment variable. The Client Secret of the M2M client application is read from this environment variable.
CLIENT_SECRET_POST
CLIENT_SECRET_JWT
PRIVATE_KEY_JWT	privateKeyEnvVarName	The field value is the name of an environment variable. The Private Key of the M2M client application is read from this environment variable.
PKCS7	applicationFederatedCredentialName	The name of the PKCS7 federated credential. You must create a federated trust source in advance. For details about the configuration, see Create a federated credential.
PKCS7	clientDeployEnvironment	The deployment environment. Only `ALIBABA_CLOUD_ECS` is supported.
OIDC	applicationFederatedCredentialName	The name of the OIDC federated credential. You must create a federated trust source in advance. For details about the configuration, see Create a federated credential.
	clientDeployEnvironment	The deployment environment. Only `KUBERNETES` is supported.
	oidcTokenFilePath	Optional. Specifies the path of the Service Account Token file. If this field is not configured, the path is read from the environment variable specified by oidcTokenFilePathEnvVarName. If neither is set, the standard Kubernetes path is used by default: /var/run/secrets/kubernetes.io/serviceaccount/token.
	oidcTokenFilePathEnvVarName	Optional. This field takes effect when oidcTokenFilePath is not specified. The field value is the name of an environment variable. The file path of the Service Account Token is read from this environment variable.
PCA	applicationFederatedCredentialName	The name of the PCA federated credential. You must create a federated trust source in advance. For details about the configuration, see Create a federated credential.
	clientX509Certificate	The end-entity certificate. Format: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	x509CertChains	The list of intermediate certificates. Multiple certificates are concatenated with line breaks. Format: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	privateKeyEnvVarName	The field value is the name of an environment variable. The Private Key of the M2M client application is read from this environment variable.
PLUGIN	pluginName	pluginName is the extension plugin name. Only `alibabacloudPluginCredentialProvider` is supported, which indicates the Alibaba Cloud OpenAPI authentication method. To use Alibaba Cloud OpenAPI authentication, complete the following configuration: Install the Alibaba Cloud authentication extension plugin. For instructions, see Install the Python SDK. Configure RAM permissions. For instructions, see Alibaba Cloud OpenAPI authentication.

Configuration examples

The following examples show the configuration for different authentication methods.

Example: Client secret credential

{
  "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": {
    "identityType": "CLIENT",
    "authnMethod": "CLIENT_SECRET_BASIC" or "CLIENT_SECRET_POST" or "CLIENT_SECRET_JWT",
    "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
  }
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: Public-private key credential

{
  "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": {
    "identityType": "CLIENT",
    "authnMethod": "PRIVATE_KEY_JWT",
    "privateKeyEnvVarName": "ENV_PRIVATE_KEY"
  }
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: PKCS7 federated credential

{
  "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": {
    "identityType": "CLIENT",
    "authnMethod": "PKCS7",
    "applicationFederatedCredentialName": "your_pkcs7_federated_credential_name",
    "clientDeployEnvironment": "ALIBABA_CLOUD_ECS"
  }
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: OIDC federated credential

{
  "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": {
    "identityType": "CLIENT",
    "authnMethod": "OIDC",
    "applicationFederatedCredentialName": "your_oidc_federated_credential_name",
    "clientDeployEnvironment": "KUBERNETES",
 "oidcTokenFilePath": "/var/run/secrets/.../token"(Optional),
 "oidcTokenFilePathEnvVarName": "ENV_OIDC_TOKEN_FILE_PATH"(Optional)
  }
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: PCA federated credential

{
  "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": {
    "identityType": "CLIENT",
    "authnMethod": "PCA",
 "applicationFederatedCredentialName": "your_pca_federated_credential_name",
    "clientX509Certificate": 
    "-----BEGIN CERTIFICATE-----
    xxxxxx
    -----END CERTIFICATE-----",
    "x509CertChains": 
    "-----BEGIN CERTIFICATE-----
    xxxxxx
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    xxxxxx
    -----END CERTIFICATE-----",
    "privateKeyEnvVarName": "ENV_PRIVATE_KEY"
  }
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

OpenAPI authentication configuration reference

{
  "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",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "PLUGIN",
    "pluginName": "alibabacloudPluginCredentialProvider"
  }
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}