Connect DingTalk first-party application - Identity as a Service

This document describes how to bind a DingTalk internal enterprise application (first-party application) to Identity as a Service (IDaaS). This includes steps such as creating an application, assigning permissions, selecting scenarios, and mapping fields.

Scenario

After connecting to a DingTalk first-party application, you can have following integration capabilities:

Category	Capabilities
Account management	Full synchronization: Supports complete synchronization of DingTalk address book data to the IDaaS platform. You can use following synchronization methods. Manual-triggered synchronization Scheduled synchronization (configurable frequency) Incremental synchronization: Monitors DingTalk address book change events real time. Synchronizes data to IDaaS automatically.
Logon integration	Unified authentication: Supports login by scanning DingTalk QR code to Directly logon to the IDaaS platform Logon to application systems integrated with IDaaS

Configuration steps

Important

DingTalk has strict permission requirements. You need to ensure that your account has developer permissions. Otherwise, you will not be able to use core features such as data synchronization. Please complete the permission configuration first before the binding operation.

Step 1: Create an application

Create in DingTalk.
1. Log on to the DingTalk Open Platform to access the developer backend. On the Internal Enterprise Applications page, click Create An Application. Then fill in the Application Name and Description, and upload an Application Icon (optional).
  Note
  DingTalk Open Platform does not have an English interface.
2. Go to the application details page, click Credentials And Basic Information to get AppKey and AppSecret. Then click the icon in the upper right corner. Copy the CorpID and fill it in IDaaS.
Create in IDaaS side.
1. Log on to the Alibaba Cloud IDaaS console, and select the IDaaS instance. In the Identity Providers menu, select Other Identity Providers > DingTalk - Inbound (First-party Application) to enter the connecting process.
2. Fill in the basic information. Enter the Display Name and CorpId.
3. Fill in the application information. Confirm the information, then enter the AppKey and AppSecret, and click Next to continue. confirming the information is correct.
  Note
  The system will automatically verify the validity of the AppKey, AppSecret, and CorpID. Note that the CorpID must be unique within the same instance.

Step 2: Assign permissions

In the DingTalk application details page, go to Permission Management > Address Book Management, and complete the authorization configuration for permissions of address book query. This is to enable data synchronization and user login.

Permission	Value	Notes
Enterprise employee mobile number information	fieldMobile	You must select at least one of these 2 attributes. Enable the field that you need for your business requirements.
Email and other personal information	fieldEmail
Obtain the basic information of contacts	qyapi_get_department_list	--
Permission to read department members in contacts	qyapi_get_department_member	--
Permissions to read information about members	qyapi_get_member	--

Configure data permissions in Permission Management. This setting decides which users and organizational data can be synchronized to IDaaS and used for DingTalk logon.
After the permission configuration, click Next in IDaaS. The system will automatically verify the API and data permissions. You can continue after the verification.

Step 3: Select scenarios

Synchronization target: Select Alibaba Cloud IDaaS from the dropdown menu. This will import DingTalk address book data under this node in IDaaS.
Incremental synchronization: Please enable it after the IDaaS configurations (depends on the DingTalk event callback mechanism, which requires IDaaS to be in an active state).
Scheduled verification: Supports configuring synchronization policies through scheduled tasks or cron expressions. It applys incremental updates to refresh local user data.
QR code login: You can quickly log on by scanning a DingTalk QR code.

Step 4: Field mapping

If you need to associate DingTalk Address Book Users/departments with existing IDaaS Accounts/organizations, or map DingTalk user fields (such as name) to IDaaS account attributes (such as display name) and historical data already exist, you need to complete the field mapping configuration. Click the Save button to complete configuration.

Step 5: Security settings

You need to configure DingTalk security settings in the IDaaS application modification page. This includes obtaining shared public network egress IP whitelist and application homepage address, and entering them into DingTalk internal enterprise application. The shared endpoints use shared IPs to implement basic network policies. The dedicated endpoints provide strict data synchronization and login control through dedicated IPs.
1. Shared endpoints
  - From the IDaaS application modification page, get Shared Public Network Egress IP List and Application Homepage Address. Then configure them in DingTalk security settings.
2. Dedicated endpoints
  - If you need strict network policies, select dedicated endpoints and obtain dedicated IP addresses. To add a dedicated endpoint, see: Create a dedicated endpoint.
  - Configure the dedicated IP in the same security settings to implement independent data synchronization and QR code login. This can enhance controllability.
Go to DingTalk application details, click Security Settings. Then fill in IDaaS Server Egress IP and Redirect URL (callback Domain).
1. Server egress IP: When IDaaS calls DingTalk interfaces, DingTalk verifies the service originating address from the trusted IP list of DingTalk.
2. Redirect URL: Corresponds to the application login homepage address in IDaaS. When DingTalk QR code login is called, DingTalk will redirect to this address with an authorization code after QR code authorization.

Data synchronization

Manual-triggered synchronization: The system will automatically perform incremental updates when Manual-triggered full data retrieval in the console is enabled.
In the IDP list, click the corresponding Trigger Synchronization. You can check the synchronization results by clicking View Details in the upper left corner, or verify the synchronization results through the user directory structure.

Incremental synchronization: DingTalk will actively push notifications when data changes after enabling event subscription. IDaaS will perform real-time incremental synchronization.

In the DingTalk Open Platform, click Event Subscription.
1. For Push Method, select HTTP Push.
2. Click the refresh button after the Encryption AesKey and Signature Token boxes to generate the corresponding information.
3. The Request URL format is: {Application Homepage Address}/callback/idp/dingtalk/orgapp/{CoprId}.
  Note
  - {Application Homepage Address} is the login homepage address in the application details of the IDaaS application list.
  - {CoprId} is the current DingTalk enterprise ID.
4. A click cannot save changes. You need to configure the encryption aesKey and encryption token information in IDaaS first, and then click to save them in DingTalk.
In IDaaS, go to the Identity Providers page, and click Modify in the Identity Provider column to configure. Fill in the Encryption AesKey, Signature Token, and Request URL from the DingTalk Open Platform.

Click Save Event Subscription in the DingTalk Open Platform.

The DingTalk server will initiate an authorization verification request to IDaaS while saving. This verification process will use the aesKey and encryption token generated by the DingTalk.
On the Event Subscription page, find the corresponding list of events to be subscribed and enable them.

Description of event subscription

Number	Interface name	Change type	Description
1	user_add_org	User change	Address book user added.
2	user_modify_org	User change	Address book user modified.
3	user_leave_org	User change	Address book user resigned.
4	org_dept_create	Department change	Address book enterprise department created.
5	org_dept_modify	Department change	Address book enterprise department modified.
6	org_dept_remove	Department change	Address book enterprise department deleted.

Enable incremental synchronization in IDaaS to complete the incremental synchronization configuration. It can verify event subscription based on logs or changes in the organizational structure.

Scheduled synchronization: By configuring synchronization scheduled tasks, IDaaS will periodically retrieve DingTalk full user data and convert to incremental updates.
IDaaS scheduling periods can be set as decided by fixed daily times or Cron expressions. IDaaS will actively retrieve DingTalk full user information to achieve incremental data synchronization during the settled time.