This document describes how to configure the IDaaS Python SDK in a cloud environment, including installing dependencies, setting up authentication methods, and configuring parameters for various credential types. - Identity as a Service

Environment requirements

Python 3.9 or later.
pip.

Install the Python SDK

For the latest version of the core SDK, see https://pypi.org/project/cloud-idaas-core/.

Install the dependencies with pip:

pip install cloud-idaas-core

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

The IDaaS SDK also supports OpenAPI authentication. In environments such as Function Compute (FC), you can use an Alibaba Cloud identity credential (such as an AK/SK pair or Alibaba Cloud 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 https://pypi.org/project/cloud-idaas-core-alibabacloud-authentication-plugin/.

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

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

Configuration path

The default path for the configuration file is ~/.cloud_idaas/client-config.json.

You can also specify the path using an environment variable or as an initialization parameter:

Environment variable name: CLOUD_IDAAS_CONFIG_PATH

Example of an environment variable:

CLOUD_IDAAS_CONFIG_PATH=/path/to/your/client-config.json

Example of an initialization parameter:

IDaaSCredentialProviderFactory.init("/path/to/your/client-config.json")

Configuration file

Example configuration file:

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx.example.com/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx.example.com/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

Parameter	Description
idaasInstanceId	Required. The ID of your Cloud Identity and Access Management (IDaaS EIAM) instance.
clientId	Required. The ID of your IDaaS application. You can find this ID in the application settings within the IDaaS console.
issuer	Required. The issuer endpoint of your IDaaS EIAM instance. You can find this endpoint in the settings of any M2M application within your IDaaS EIAM instance.
tokenEndpoint	Required. The token endpoint of your IDaaS EIAM instance. You can find this endpoint in the settings of any M2M application within your I********* instance.
scope	Required. Specify the audience and permission identifiers for the target M2M server-side application. The format is `Audience Identifier\|Permission Identifier`. When obtaining an Alibaba Cloud STS token or credentials for a RAM role managed by IDaaS, set this value to `urn:cloud:idaas:pam\|.all`, which represents the built-in scope for IDaaS.
openApiEndpoint	Optional. The OpenAPI endpoint for IDaaS. Used for OpenAPI authentication. You can obtain the endpoint from the Alibaba Cloud OpenAPI Developer Portal. If your application is deployed in an Alibaba Cloud VPC within the same region as your IDaaS instance, you can use the internal VPC endpoint for access. You can find the VPC endpoint in the Alibaba Cloud OpenAPI Developer Portal.
developerApiEndpoint	Optional. The DeveloperAPI endpoint for IDaaS. Use this endpoint to obtain an Alibaba Cloud STS token or credentials for a RAM role managed by IDaaS. You can obtain the endpoint from the Alibaba Cloud OpenAPI Developer Portal. If your application is deployed in an Alibaba Cloud VPC within the same region as your IDaaS instance, you can use the internal VPC endpoint for access. You can find the VPC endpoint in the Alibaba Cloud OpenAPI Developer Portal.
authnConfiguration	identityType: Optional. The default value is `CLIENT`. Currently, 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 depend on the selected authentication method. For more information, see authnMethod and authnConfiguration mapping.
httpConfiguration	Configures HTTP settings: `connectTimeout`: Optional. The maximum time in milliseconds to wait for a connection to be established. Default: 5000. `readTimeout`: Optional. The maximum time in milliseconds to wait for data from the server after a connection is established. Default: 10000.

authnMethod and authnConfiguration mapping

authnMethod	Required parameters	Description
CLIENT_SECRET_BASIC	clientSecretEnvVarName	The name of the environment variable that stores the M2M application's Client Secret.
CLIENT_SECRET_POST
CLIENT_SECRET_JWT
PRIVATE_KEY_JWT	privateKeyEnvVarName	The name of the environment variable that stores the M2M application's Private Key.
PKCS7	applicationFederatedCredentialName	The name of the PKCS7 federated credential. You must create a federated trust source in advance. For configuration details, see Create a federated credential.
PKCS7	clientDeployEnvironment	Deployment environment. Currently, 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 configuration details, see Create a federated credential.
	clientDeployEnvironment	The only currently supported deployment environment is `KUBERNETES`.
	oidcTokenFilePath	Optional. The path to the Service Account Token file. If this parameter is not set, the SDK reads the path from the `oidcTokenFilePathEnvVarName` environment variable. If neither is specified, the SDK defaults to the standard Kubernetes path: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
	oidcTokenFilePathEnvVarName	Optional. The name of an environment variable containing the path to the Service Account Token file. This is used if `oidcTokenFilePath` is not specified.
PCA	applicationFederatedCredentialName	The name of the PCA federated credential. You must create a federated trust source in advance. For configuration details, see Create a federated credential.
	clientX509Certificate	The client certificate, in the following format: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	x509CertChains	A list of intermediate certificates. Concatenate multiple certificates with line breaks, formatted as follows: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	privateKeyEnvVarName	The name of the environment variable that stores the client application's Private Key.
PLUGIN	pluginName	`pluginName` is the name of the extension plugin. The only supported value is `alibabacloudPluginCredentialProvider`, which is the Alibaba Cloud OpenAPI authentication method. To use this method, you must complete the following configurations: Install the Alibaba Cloud authentication extension plugin. For more information, see Install the Python SDK. Configure RAM permissions. For more information, see Alibaba Cloud OpenAPI authentication.

Configuration examples

This section provides configuration examples for different authentication methods.

Example: Client secret credential

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

Example: Public-private key credential

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx.example.com/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx.example.com/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.example.com/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx.example.com/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.example.com/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx.example.com/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.example.com/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx.example.com/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-----\nxxxxxx\n-----END CERTIFICATE-----",
    "x509CertChains": 
    "-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----",
    "privateKeyEnvVarName": "ENV_PRIVATE_KEY"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: OpenAPI authentication

{
  "idaasInstanceId": "idaas_xxx", 
  "clientId": "app_xxx", 
  "issuer":"https://xxx.example.com/api/v2/iauths_system/oauth2", 
  "tokenEndpoint": "https://xxx.example.com/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
  }
}