Agent Identity:Securely access DingTalk from an agent

Environment requirements

Your local test environment must have Python (version 3.10 or later) and the pip package manager installed.

User and permission requirements

1. User requirements:

   1. A DingTalk Open Platform administrator: To manage applications on the DingTalk Open Platform.

   2. A script execution user (RAM user): To run the setup script and test the application locally.

2. RAM permission requirements:

   The script execution user must have the following permissions:

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "agentidentity:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "agentidentitydata:*",
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": "ram:CreateServiceLinkedRole",
         "Resource": "*",
         "Condition": {
           "StringEquals": {
             "ram:ServiceName": ["agentidentity.aliyuncs.com"]
           }
         }
       },
       {
         "Effect": "Allow",
         "Action": [
           "ram:CreateApplication",
           "ram:CreateRole", 
           "ram:CreatePolicy",
           "ram:AttachPolicyToRole", 
           "ram:CreateAppSecret",
           "ram:DeleteApplication"
         ],
         "Resource": "*"
       }
     ]
   }

DashScope API key

Obtain a DashScope API key with permission to call Model Studio models. If you have not created one, see Create an API Key.

Create a DingTalk application

Follow the DingTalk OAuth credential provider setup tutorial to create a DingTalk application and configure it as an OAuth2 credential provider for Agent Identity.

Configure DingTalk application permissions

1. Log on to the DingTalk Open Platform. Find the DingTalk application that you created and go to its details page.

2. In the left-side navigation pane of the application details page, click Permission Management. In the permission search box, enter Document.Document.Write, and click Enable in the Actions column. This permission lets the DingTalk application overwrite the user's DingTalk documents on their behalf.

Get and prepare the sample code

1. Clone the code repository. Open a local terminal and run the following command to clone the sample code.

   git clone https://github.com/aliyun/agent-identity-dev-kit.git
   cd agent-identity-dev-kit/agent_identity_python_samples/end-to-end_sample

2. Install dependencies. Create and activate a Python virtual environment, and then install the required dependencies.

   pip install -r requirements.txt

3. Configure environment variables.

   export AGENT_IDENTITY_REGION_ID=cn-beijing # Agent Identity is currently available only in the China (Beijing) region
   export DASHSCOPE_API_KEY=<your-api-key> # Your DashScope API key

Prepare RAM user credentials

Configure credentials locally for the script execution user mentioned in the User and permission requirements section.

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

Run the setup script

In the root directory of your local project, run the setup script prepare.py to automatically create the required cloud resources:

python -m prepare

This script performs the following actions:

1. Creates an identity provider.

2. Creates an Alibaba Cloud OAuth 2.1 inbound application.

3. Creates an OAuth 2.1 native application required for Alibaba Cloud MCP services (not used in this tutorial).

4. Creates a workload identity and a role.

5. Configures the credential provider.

The script outputs information about the created resources to the .config.json file in the root directory.

If the script fails due to an exception, such as a network issue or an exceeded resource quota, clean up the created resources before running the script again:

python -m clear

Configure the DingTalk credential provider in the code

1. On the Agent Identity Credential Providers page, find the DingTalk credential provider that you created in Step 1 and copy its Credential Provider Name.

2. In the deploy_starter/tools/ding_talk_tool.py file of your project, find the following code:

   @requires_access_token(
       credential_provider_name="test-provider-for-dingtalk",
       scopes=["openid", "corpid"],
       auth_flow="USER_FEDERATION",
       on_auth_url= on_auth,
       # force_authentication=True,
       callback_url= f"{get_config_with_default('APP_REDIRECT_URI', 'http://localhost:8090')}/callback",
       inject_param_name="access_token",
   )

   Replace the existing code with the following, and update the credential_provider_name value to the name of your DingTalk credential provider.

   @requires_access_token(
       credential_provider_name="your-dingtalk-credential-provider-name",
       scopes=["openid", "corpid"],
       auth_flow="USER_FEDERATION",
       on_auth_url= on_auth,
       # force_authentication=True,
       callback_url= f"{get_config_with_default('APP_REDIRECT_URI', 'http://localhost:8090')}/callback",
       inject_param_name="access_token",
       custom_parameters={"prompt": "consent"},
   )