Skip to main content

DingTalk Identity Source

Connect your enterprise directory through a DingTalk internal enterprise app and configure credentials, permissions, and field mappings.

A DingTalk identity source connects your enterprise directory to Qoder through a DingTalk internal enterprise app (first-party app). Qoder uses the configured field mappings to identify members and departments in DingTalk. This guide is for administrators responsible for Qoder identity management and DingTalk app configuration. Before you begin, make sure you have Qoder administrative permissions and permission to view and configure the target DingTalk internal enterprise app.
A DingTalk identity source synchronizes identity directory data. It is separate from SAML or OIDC single sign-on configuration.

Prerequisites

Before connecting the identity source:
  • Confirm that you can sign in to the DingTalk Developer Console and create an internal enterprise app for your organization.
  • Confirm that you can access the enterprise CorpId and the app's AppKey and AppSecret.
  • Confirm that you can request address book permissions and configure their scope. If different administrators handle app creation and permission requests, coordinate with them in advance.
DingTalk supports several integration methods, including QR-code authorization for third-party apps and internal enterprise app integration. This guide covers DingTalk (first-party app) in Qoder. An administrator must create an internal enterprise app in DingTalk and manually configure credentials and permissions. It does not use the third-party app QR-code authorization flow.

Setup workflow

You will alternate between the DingTalk Developer Console and Qoder:
Qoder DingTalk identity source setup
  1. Create an internal enterprise app in DingTalk and obtain CorpId, AppKey, and AppSecret.
  2. Add a DingTalk identity source in Qoder, enter the app credentials, and obtain the callback domain generated by Qoder.
  3. Return to DingTalk to configure the callback domain, request the 6 permissions listed in Qoder, and set their scope.
  4. Return to Qoder to verify permissions, configure field mappings, and complete setup.

Create an app in DingTalk

DingTalk Developer Console setup

Create an internal enterprise app

App creation entry in the DingTalk Developer Console (Chinese interface)
Click Create in the app development guide on the console home page, or open App Development from the top navigation to create an internal enterprise app.
  1. Sign in to the DingTalk Developer Console.
  2. Go to App Development > Internal Enterprise Development.
  3. Click Add App.
  4. Enter the app name, description, icon, and other required information, then create the app.
  5. Open the app details page.
The app name identifies the app in DingTalk. You can use the same name as the identity source's display name in Qoder. Do not create a third-party enterprise app: its credentials cannot be used for the first-party integration described here.

Obtain enterprise and app credentials

  1. Obtain the current enterprise's CorpId in DingTalk.
  2. Open Credentials & Basic Information on the app details page.
  3. Copy the app's AppKey and AppSecret.
  4. Store all three values securely until you enter them in Qoder.
The following credentials must belong to the same DingTalk enterprise and internal enterprise app:
CredentialPurposeLocation
CorpIdIdentifies the DingTalk enterprise.DingTalk Developer Console
AppKeyIdentifies the internal enterprise app.Credentials & Basic Information in the app details
AppSecretAuthenticates the app when Qoder calls DingTalk APIs.Credentials & Basic Information in the app details
AppSecret is a sensitive credential. Do not send it in chat, email, or ticket text, or include it in public documentation or code repositories.

Add a DingTalk identity source

  1. In the Qoder organization admin console, go to Settings > Security & Identity > Access & Authentication.
  2. Find DingTalk Identity Source and click Add.
  3. Continue to app configuration.
  4. Follow the wizard to configure the app, assign permissions, and map fields.

Configure the app

Enter the following information:
FieldRequiredDescription
Display nameYesThe identity source's name in Qoder, used to distinguish it from other sources. For example, “DingTalk Enterprise Directory.”
CorpIdYesThe current DingTalk enterprise's ID.
AppKeyYesThe DingTalk internal enterprise app's identifier.
AppSecretYesThe secret paired with AppKey. Its value is hidden by default and can be temporarily revealed when needed.
The page also generates a callback domain:
AddressConfiguration
Callback domainCopy the value generated on the page into the app's callback domain configuration in DingTalk.
Always copy the complete address generated by your current Qoder page. Do not use example domains from this guide, screenshots, or demo environments, and do not alter the protocol, domain, port, or path.

Configure the callback domain in DingTalk

Keep the Qoder configuration page open and complete these steps in the DingTalk app details:
  1. Copy the Callback domain displayed in Qoder.
  2. Paste it into the DingTalk app's callback domain configuration.
  3. Save the DingTalk app configuration.
Return to Qoder and click Next. If the display name, CorpId, AppKey, or AppSecret is empty, the page highlights the missing fields. Fill them in to continue.

Assign API permissions

The identity source needs to read member and department information. In DingTalk, go to App Development > Select App > Permission Management, then search for and request these 6 permissions:
PermissionPermission valuePurpose
Enterprise employee mobile phone informationfieldMobileRead members' mobile phone numbers.
Email and other personal informationfieldEmailRead members' email addresses.
Basic address book informationqyapi_get_department_listRead department lists and other basic directory information.
Department member read accessqyapi_get_department_memberRead membership relationships between departments and members.
Member information read accessqyapi_get_memberRead member information.
Address book personal information read accessContact.User.ReadRead personal information in the address book.
Complete authorization in DingTalk:
  1. Click Permission Management on the app details page.
  2. Search for each permission using its permission value from the table.
  3. Select the permissions and submit the request. If the page supports batch requests, you can submit several at once.
  4. Under Permission Management > Data Permissions, set the address book scope the app can access. Select all employees to synchronize the complete directory, or select only the members you need to connect to Qoder.
  5. Complete authorization and wait for the permissions to take effect in DingTalk.
The permission scope determines which members and departments the app can read, and therefore limits the directory data Qoder can obtain. To change the scope later, update the app's permission or visibility scope in DingTalk, then return to Qoder and check again.
Request only the permissions listed in Qoder. Do not select all permissions unrelated to the integration.
After requesting permissions, return to Qoder:
  • Click Verify Permission next to a permission to check it individually.
  • Click Full Check to check all 6 permissions at once.
  • If a permission is Not Authorized, confirm in DingTalk that it has been requested and has taken effect, then verify it again.
For permission values and request instructions, see the DingTalk permission scope reference.

Configure field mappings

Field mappings determine which Qoder identity fields receive DingTalk member attributes. Configure these 3 account fields:
DingTalk identity source field mapping example (Chinese interface)
Qoder fieldAttribute pathDingTalk fieldConfiguration
emailuser.emailemail (email) or org_email (enterprise email)Required as the unique identifier for account linking.
displayNameuser.displayNameSelect according to your organization's needs.Determines the member's display name in Qoder.
phoneNumberuser.phoneNumbermobile (mobile phone number)Synchronizes the member's mobile phone number.
Both email and org_email can map to Qoder's email field, but they have different sources:
  • email: The email address in the member's DingTalk profile.
  • org_email: The member's enterprise email address in the current DingTalk enterprise.
Choose the field that reliably matches members' Qoder account email addresses. If your organization centrally maintains enterprise email addresses and target members have valid, complete org_email values, you can use org_email; otherwise, use email. If both exist but differ, choose the field matching the member's Qoder account email to avoid duplicate accounts or incorrect account associations. When configuring mappings:
  • Email is the account identifier required for the integration. The selected DingTalk field must provide a valid email address for each member you need to connect.
  • Before completing setup, check members from different departments and member types to confirm that the selected email field is populated.
  • Changing or removing a mapping changes how future data from the source is written to Qoder. Before saving, confirm that it will not cause missing member information or incorrect associations.
Click Complete Setup. Qoder opens the identity source details page and checks the app credentials and authorization status.

Check connection status

When you open the identity source details page, Qoder automatically checks AppKey, AppSecret, and the granted permissions.
  • A normal configuration status means the credentials and permissions are valid in the current check.
  • If Qoder detects a change to the authorization scope in DingTalk, it warns that the local configuration may no longer be valid. Correct the DingTalk configuration, then click Check Again.
  • After dismissing the automatic notification, you can still click Check Again under Authorization to see each permission's status and the number granted.
  • Under App Credentials, click Check Pairing to check whether the current AppKey and AppSecret match.
Permission verification checks whether Qoder can currently use the corresponding permission. If DingTalk shows that it has been requested but Qoder reports it as unauthorized, confirm that you configured the same internal enterprise app and that the permission has taken effect.

Manage the identity source

After setup, use the details page to view or maintain app credentials, field mappings, basic information, callback configuration, and authorization.

Update app credentials

CorpId identifies the connected DingTalk enterprise on the details page. You can update AppKey and AppSecret separately.
  1. Edit AppKey or AppSecret.
  2. Click Save next to the field.
  3. Click Check and Save in the confirmation dialog.
  4. Wait for the system to verify that the new value matches its paired credential.
If validation succeeds, the new credential is saved and takes effect immediately. If validation fails, the change is not saved. Confirm that AppKey and AppSecret belong to the same DingTalk app, then check again.

Update field mappings

The mapping section shows mapping identifiers, the number of mapped fields, and the DingTalk field associated with each Qoder field. After editing mappings, confirm that the email identifier is still valid and all 3 account fields are complete.

View callback configuration

The callback domain is in the collapsed Callback & Advanced Configuration section. The domain configured in DingTalk must match the value currently displayed in Qoder.

Enable or disable the identity source

The details page shows the current connection status and controls to enable or disable the source. After a status change, the page displays Enabled or Disabled. After re-enabling the source, check credential pairing and authorization to confirm that the configuration remains valid.

Delete the identity source

Clicking Delete Identity Source and confirming permanently removes the following information from that source:
  • App credentials
  • Permission configuration
  • Field mappings
  • Synchronized data
Deletion cannot be undone. To restore the integration afterward, you must add and configure the identity source again. Before deleting it, confirm that the source and its synchronized data are no longer needed.

FAQ

Why can't I continue to the next step?

Make sure the display name, CorpId, AppKey, and AppSecret are all filled in. The page highlights empty required fields.

Why did credential validation fail?

Common causes include an AppKey and AppSecret from different internal enterprise apps, or missing characters when copying. Obtain the credentials again from the same DingTalk app, without adding leading or trailing spaces.

Why are permissions still unauthorized?

Check the following:
  1. The credentials configured in Qoder belong to the DingTalk app you are authorizing.
  2. All 6 permissions have been requested for that app.
  3. The permission changes have taken effect in DingTalk.
  4. You have returned to Qoder and run individual verification or a full check again.

Should I map email to email or org_email?

email comes from the member's profile; org_email comes from the current DingTalk enterprise. Select the field that consistently provides valid values for target members and matches their Qoder account email addresses. Before completing setup, sample different departments and member types to avoid missing account-linking email addresses.

What should I do after changing DingTalk permissions?

Return to the identity source details page and click Check Again under Authorization. If Qoder reports configuration changes, correct the permissions in DingTalk and check again until all required permissions are authorized.