cloud-idaas-core

简体中文 | English

Python SDK for IDaaS (Identity as a Service) M2M products, providing convenient machine-to-machine authentication capabilities for developers.

Features

• Multiple Authentication Methods: Supports various M2M authentication methods including JWT Client Secret, JWT Private Key, OIDC Token, PKCS7 Attested Document, etc.
• Plugin Extension: Supports custom credential providers to meet special scenario requirements
• Intelligent Caching Mechanism: Built-in credential caching strategy with prefetch and stale value handling to reduce unnecessary network requests
• Flexible Configuration: Supports configuration files, environment variables, and programmatic configuration
• Token Exchange (RFC 8693): Supports token exchange to obtain access tokens with different scopes or audiences, suitable for token downgrading and service-to-service call scenarios

Requirements

• Python >= 3.9
• Dependencies:
  • requests >= 2.31.0
  • cryptography >= 44.0.0
  • PyJWT >= 2.8.0
  • urllib3 >= 2.5.0

Installation

pip install cloud-idaas-core

# or install a specific version
pip install cloud-idaas-core==x.x.x

Latest SDK Version

Specify Configuration File

The default path for the configuration file is: ~/.cloud_idaas/client-config.json. If not explicitly specified, the configuration file will be loaded from this path by default.

You can specify the configuration file path via environment variable or 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 Description

Configuration file example:

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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
    }
}

Parameter Description

authnMethod Field Values and authnConfiguration Field Mapping

Configuration Examples

Configuration examples for different authentication methods.

Client Secret Credential Configuration Example

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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",
        "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
    },
    "httpConfiguration": {
        "connectTimeout": 5000,
        "readTimeout": 10000
    }
}

Private Key Credential Configuration Example

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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
    }
}

PKCS7 Federated Credential Configuration Example

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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
    }
}

OIDC Federated Credential Configuration Example

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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",
        "oidcTokenFilePathEnvVarName": "ENV_OIDC_TOKEN_FILE_PATH"
    },
    "httpConfiguration": {
        "connectTimeout": 5000,
        "readTimeout": 10000
    }
}

PCA Federated Credential Configuration Example

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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-----\nxxxxxx\n-----END CERTIFICATE-----",
        "x509CertChains": "-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----",
        "privateKeyEnvVarName": "ENV_PRIVATE_KEY"
    },
    "httpConfiguration": {
        "connectTimeout": 5000,
        "readTimeout": 10000
    }
}

OpenAPI Authentication Configuration Example

{
    "idaasInstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "clientId": "app_mkv7rgt4d7i4u7zqtzev2mxxxx",
    "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
    }
}

Code Integration

SDK Initialization

Read the configuration file specified during the environment setup phase and complete the IDaaS configuration initialization.

from cloud_idaas.core import IDaaSCredentialProviderFactory

IDaaSCredentialProviderFactory.init()

Important:

• All SDK features depend on the init() initialization method, so the init() method must be completed first, otherwise getting IDaaSCredentialProvider will fail and cause business interruption.
• Initialization will check the configuration and obtain the Access Token for the scope specified in the configuration file. If the configuration is missing or incorrect, causing the Access Token acquisition to fail, it will directly report an error and cause business interruption.

Get Access Token

1. Get IDaaS credentialProvider to obtain Access Token.

   • Get IDaaS credentialProvider through no-argument constructor to obtain Access Token for the scope specified in the configuration file:

     credential_provider = IDaaSCredentialProviderFactory.get_idaas_credential_provider()
     

   • Get IDaaS credentialProvider through parameterized constructor, scope can be specified to obtain Access Token for the specified scope. Format is audience|scope, corresponding to the audience identifier and permission identifier of the M2M server application to access:

     credential_provider = IDaaSCredentialProviderFactory.get_idaas_credential_provider(scope)
     

2. Access Token is of Bearer type, obtained through the get_bearer_token() method of credentialProvider:

   access_token = credential_provider.get_bearer_token()
   

Code Example

For complete examples, see the samples/ directory:

• samples/client_secret_authentication.py - Get Access Token example

from cloud_idaas.core import IDaaSCredentialProviderFactory

def main():
    # Initialize the factory with configuration
    IDaaSCredentialProviderFactory.init()

    # Get credential provider with scope from config file
    # credential_provider = IDaaSCredentialProviderFactory.get_idaas_credential_provider()

    # scope format: <audience>|<scope>
    scope = "api.example.com|read:file"
    # Get credential provider with scope specified by parameter
    credential_provider = IDaaSCredentialProviderFactory.get_idaas_credential_provider(scope)

    access_token = credential_provider.get_bearer_token()

    print(access_token)

if __name__ == "__main__":
    main()

Token Exchange

Token Exchange (RFC 8693) allows you to exchange a subject token for a new access token with different scopes or audiences. This is useful for token downgrading and service-to-service access scenarios.

Basic Token Exchange

For complete examples, see the samples/ directory:

• samples/token_exchange_with_client_secret_authentication.py - Token exchange example

from cloud_idaas.core import IDaaSCredentialProviderFactory, OAuth2Constants

def main():
    # Initialize the factory with configuration
    IDaaSCredentialProviderFactory.init()

    # The subject token to exchange
    subject_token = ""

    # Get token exchange credential provider with scope from config file
    # token_exchange_provider = IDaaSCredentialProviderFactory.get_idaas_token_exchange_credential_provider()

    # scope format: <audience>|<scope>
    scope = "api.example.com|read:file"
    # Get token exchange credential provider with scope specified by parameter
    token_exchange_provider = IDaaSCredentialProviderFactory.get_idaas_token_exchange_credential_provider_by_scope(scope)

    # Perform token exchange
    access_token = token_exchange_provider.get_issued_token(
        subject_token,
        OAuth2Constants.ACCESS_TOKEN_TYPE_VALUE,
    )

    print(access_token)

if __name__ == "__main__":
    main()

Token Exchange Parameters

Use Cases

1. Token Downgrading: Exchange a token with broader permissions for a token with limited scope
2. Service-to-Service Access: Pass the same user identity between services to obtain the required access token

Support and Feedback

• Email: cloudidaas@list.alibaba-inc.com
• Issues: Please submit an Issue for questions or suggestions

License

This project is licensed under the Apache License 2.0.