IDaaS Python SDK prerequisites - installation, authentication, configuration - Identity as a Service

Environment requirements

Python 3.9 or later.
pip.

Install the Python SDK

Core SDK on PyPI: https://pypi.org/project/cloud-idaas-core/.

Install 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 like Function Compute (FC), use an Alibaba Cloud identity credential (AK/SK pair or Alibaba Cloud STS) to obtain an M2M client token. This requires the Alibaba Cloud authentication extension plugin.

Plugin on PyPI: 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

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

Override the path with an environment variable or initialization parameter:

Environment variable name: CLOUD_IDAAS_CONFIG_PATH

Environment variable:

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

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 IDaaS EIAM instance ID.
clientId	Required. The IDaaS application ID. Find it in the application settings in the IDaaS console.
issuer	Required. The issuer endpoint of your IDaaS EIAM instance. Find it in any M2M application's settings.
tokenEndpoint	Required. The token endpoint of your IDaaS EIAM instance. Find it in any M2M application's settings.
scope	Required. The audience and permission identifiers for the target M2M server-side application. Format: `Audience Identifier\|Permission Identifier`. To obtain an Alibaba Cloud STS token or RAM role credentials managed by IDaaS, set this to `urn:cloud:idaas:pam\|.all` (built-in IDaaS scope).
openApiEndpoint	Optional. The OpenAPI endpoint for IDaaS. Used for OpenAPI authentication. Get the endpoint from the Alibaba Cloud OpenAPI Developer Portal. For applications deployed in a VPC in the same region as your IDaaS instance, use the internal VPC endpoint available in the Alibaba Cloud OpenAPI Developer Portal.
developerApiEndpoint	Optional. The DeveloperAPI endpoint for IDaaS. Used to obtain Alibaba Cloud STS tokens or RAM role credentials managed by IDaaS. Get the endpoint from the Alibaba Cloud OpenAPI Developer Portal. For applications deployed in a VPC in the same region as your IDaaS instance, use the internal VPC endpoint available in the Alibaba Cloud OpenAPI Developer Portal.
authnConfiguration	identityType: Optional. Defaults to `CLIENT`. Only `CLIENT` is supported (M2M client 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	HTTP settings: `connectTimeout`: Optional. Connection timeout in milliseconds. Default: 5000. `readTimeout`: Optional. Read timeout in milliseconds. 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. 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	Deployment environment. Only `KUBERNETES` is supported.
	oidcTokenFilePath	Optional. Path to the Service Account Token file. Falls back to the `oidcTokenFilePathEnvVarName` environment variable, then to the default Kubernetes path: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
	oidcTokenFilePathEnvVarName	Optional. Environment variable for the Service Account Token file path. Used when `oidcTokenFilePath` is not set.
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. Format: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	x509CertChains	Intermediate certificates. Concatenate with line breaks: -----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 extension plugin name. The only supported value is `alibabacloudPluginCredentialProvider` (Alibaba Cloud OpenAPI authentication). To use this method, complete the following: 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

Configuration examples for each authentication method.

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