How to connect to account synchronization address book events - Identity as a Service

Address book events describe the callback mechanism that Alibaba Cloud IDaaS uses to notify your application when account, organizational unit, or group data changes. By subscribing to these events, you can keep your application synchronized with IDaaS in real time.

Overview

This topic describes the event parameters and their categories. For integration principles and call flows, see Account synchronization overview.

IDaaS delivers events in three modes:

Event mode	Trigger	Use case
Test event	Administrator clicks The test is successful. in the console	Validates connectivity, signature verification, and encryption after configuring app sync
Incremental event	Automatically triggered when a change occurs in the IDaaS address book	Keeps your app in sync by processing individual changes as they happen
Full event	Manually triggered by an administrator from the IDaaS console	Imports all IDaaS data into the target app at once; typically used for initial onboarding or a full data refresh

For all account and organizational unit events, IDaaS sends the complete record as event parameters. If the payload contains sensitive data, use an HTTPS channel or enable Business Data Encryption.

Event reference

The following table lists all supported event types and their URN codes.

Event module	Event type	Type code
Test event	Test connection	`urn:alibaba:idaas:app:event:common:test`
Incremental — user	Account creation	`urn:alibaba:idaas:app:event:ud:user:create`
	Account deletion	`urn:alibaba:idaas:app:event:ud:user:delete`
	Account basic information update	`urn:alibaba:idaas:app:event:ud:user:update_info`
	Account password update	`urn:alibaba:idaas:app:event:ud:user:update_password`
	Account disable	`urn:alibaba:idaas:app:event:ud:user:disable`
	Account enable	`urn:alibaba:idaas:app:event:ud:user:enable`
	Account lock	`urn:alibaba:idaas:app:event:ud:user:lock`
	Account unlock	`urn:alibaba:idaas:app:event:ud:user:unlock`
	Account shift	`urn:alibaba:idaas:app:event:ud:user:update_primary_ou`
Incremental — organizational unit	Organization creation	`urn:alibaba:idaas:app:event:ud:organizational_unit:create`
	Organization deletion	`urn:alibaba:idaas:app:event:ud:organizational_unit:delete`
	Organization update	`urn:alibaba:idaas:app:event:ud:organizational_unit:update`
	Move organization	`urn:alibaba:idaas:app:event:ud:organizational_unit:update_parent_organizational_unit`
Incremental — group	Group creation	`urn:alibaba:idaas:app:event:ud:group:create`
	Group basic information update	`urn:alibaba:idaas:app:event:ud:group:update`
	Group deletion	`urn:alibaba:idaas:app:event:ud:group:delete`
	Add member to group	`urn:alibaba:idaas:app:event:ud:group:add_user`
	Remove member from group	`urn:alibaba:idaas:app:event:ud:group:remove_user`
Full	Full push of organizational units	`urn:alibaba:idaas:app:event:ud:organizational_unit:push`
	Full push of accounts	`urn:alibaba:idaas:app:event:ud:user:push`
	Full push of groups	`urn:alibaba:idaas:app:event:ud:group:push`

Test event

Test connection

Event type: urn:alibaba:idaas:app:event:common:test

Tests the connectivity, signature verification, and encryption capabilities of your configuration.

Note

This event can only be triggered by a one-click test in the console and does not support API calls.

The following example shows the payload after the request parameters are signature-verified:

{
  "iss": "urn:alibaba:idaas:app:event",
  "sub": "idaas_rhhoqmlnyu3cv7ow657gyvurky",
  "aud": "app_mjavzivahje6zxkbc4i2bierdu",
  "exp": 1648711369,
  "iat": 1648709570,
  "jti": "bNRrCYrqXjqe8B1xweqlZw",
  "dataEncrypted": false,
  "cipherData": "",
  "plainData": {
    "instanceId": "idaas_rhhoqmlnyu3cv7ow657gyvurky",
    "aliUid": 151971404963****,
    "eventVersion": "V1.0",
    "eventData": [
      {
        "eventId": "evnt_aaaac766x2somw2ptotoyk6ag6bmfkt5xpqprpq",
        "eventType": "urn:alibaba:idaas:app:event:common:test",
        "eventTime": "1648709509849",
        "bizId": "evnt_aaaac766x2somw2ptotoyk6ag6bmfkt5xpqprpq",
        "bizData": "{\"bizData\":\"req_xxxxxxxxxxsdfsdfsfd\"}"
      }
    ]
  }
}

Your application must return a response after receiving the event. The eventId in the successEvents field must match the eventId from the request. If they do not match, the test fails.

{
  "successEvents": [
    {
      "eventId": "evnt_aaaac766x2somw2ptotoyk6ag6bmfkt5xpqprpq",
      "eventCode": "SUCCESS",
      "eventMessage": "SUCCESS"
    }
  ],
  "skippedEvents": [
    {
      "eventId": "",
      "eventCode": "",
      "eventMessage": ""
    }
  ],
  "failedEvents": [
    {
      "eventId": "",
      "eventCode": "",
      "eventMessage": ""
    }
  ],
  "retriedEvents": [
    {
      "eventId": "",
      "eventCode": "",
      "eventMessage": ""
    }
  ]
}

Address book incremental events

User events

Account creation

Event type: urn:alibaba:idaas:app:event:ud:user:create

Subscribe to this event to handle employee onboarding. IDaaS sends the full account record when a new user is created.

Example bizData:

{
  "password": "ssGp96",
  "userId": "user_4alcbywzc7jyl23lu2srljsw7i",
  "username": "zhangsan",
  "displayName": "Zhang San",
  "passwordSet": true,
  "phoneRegion": "",
  "phoneNumber": "155****5620",
  "phoneVerified": false,
  "email": "zh***@163.com",
  "emailVerified": false,
  "userExternalId": "user_4alcbywzc7jyl23lu2srljsw7i",
  "userSourceType": "build_in",
  "userSourceId": "idaas_rhhoqmlnyu3cv7ow657gyvurky",
  "status": "enabled",
  "accountExpireTime": "-1",
  "registerTime": "1648531553621",
  "lockExpireTime": "-1",
  "createTime": "1648531553621",
  "updateTime": "1648531553621",
  "description": "",
  "customFields": [
    {
      "fieldName": "test_custom_field",
      "fieldValue": "test_value"
    }
  ],
  "primaryOrganizationalUnitId": "ou_bvluxnp2ef36uupdwob6km34a4",
  "organizationalUnits": [
    {
      "organizationalUnitId": "ou_bvluxnp2ef36uupdwob6km34a4",
      "organizationalUnitName": "R&D Department",
      "primary": true
    }
  ]
}

Parameters:

Parameter	Data type	Description
userId	String	Unique user ID.
username	String	Username.
displayName	String	Display name. Usually the user's full name.
passwordSet	boolean	Specifies whether a password is set.
phoneRegion	String	Area code for the phone number.
phoneNumber	String	Phone number.
phoneVerified	boolean	Specifies whether the phone number is verified. Verification is not currently performed.
email	String	Email address.
emailVerified	boolean	Specifies whether the email address is verified. Verification is not currently performed.
userExternalId	String	External ID. For a self-built account, this is the same as `userId`. For an account synchronized from an external source, this is the user ID from that source. For example, if the source is DingTalk, this is the DingTalk `userId`.
userSourceType	String	Source type. For a self-built account, the value is `build_in`.
userSourceId	String	Source type ID.
password	String	Password. Included only when password synchronization is enabled for the application and the user has set a password.
status	String	Account status. `enabled` indicates the account is enabled. `disabled` indicates the account is disabled.
accountExpireTime	Long	User expiration time.
registerTime	Long	Registration time.
lockExpireTime	Long	Lock expiration time. The account is unlocked at this time.
createTime	Long	Creation time.
updateTime	Long	Last modification time.
description	String	Description.
customFields	List	Extension fields.
-fieldName	String	Field name.
-fieldValue	String	Field value.
primaryOrganizationalUnitId	String	ID of the user's primary organizational unit.
organizationalUnits	List	All organizational units the user belongs to.
-organizationalUnitId	String	Unique ID of the organizational unit.
-organizationalUnitName	String	Name of the organizational unit.
-primary	boolean	Specifies whether this is the primary organizational unit. `true` indicates it is the primary organizational unit.

Account deletion

Event type: urn:alibaba:idaas:app:event:ud:user:delete

Subscribe to this event to handle employee offboarding. When an employee leaves and their account is removed from the address book, this event notifies your application.

Example bizData: Same as account creation.

Account basic information update

Event type: urn:alibaba:idaas:app:event:ud:user:update_info

Subscribe to this event to receive notifications when an employee's basic information changes, such as their phone number, email address, or name.

Example bizData: Same as account creation.

Account password update

Event type: urn:alibaba:idaas:app:event:ud:user:update_password

Subscribe to this event to receive the updated password when an account password changes, for example, when an administrator resets it or a user modifies it.

Important

To receive this event, you must also configure the synchronization scope. Otherwise, synchronization will not occur. For more information, see Account Synchronization - Synchronize from IDaaS to Applications.

Example bizData: Same as account creation.

Account enable

Event type: urn:alibaba:idaas:app:event:ud:user:enable

Triggered when an account status changes from disabled to enabled. Subscribe to this event to receive this change notification.

Example bizData: Same as account creation.

Account disable

Event type: urn:alibaba:idaas:app:event:ud:user:disable

Triggered when an account status changes from enabled to disabled. Subscribe to this event to receive this change notification.

Example bizData: Same as account creation.

Account lock

Event type: urn:alibaba:idaas:app:event:ud:user:lock

Triggered when an account is locked, for example, when a user enters an incorrect password multiple times and the account becomes temporarily unavailable. Subscribe to this event to receive this change notification.

Example bizData: Same as account creation.

Account unlock

Event type: urn:alibaba:idaas:app:event:ud:user:unlock

Triggered when an account status changes from locked to normal. Subscribe to this event to receive this change notification.

Example bizData: Same as account creation.

Account shift

Event type: urn:alibaba:idaas:app:event:ud:user:update_primary_ou

Triggered when the primary organizational unit of an account changes. Subscribe to this event to receive this change notification.

Example bizData: Same as account creation.

Organizational unit (OU) events

Organization creation

Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:create

Subscribe to this event to handle organizational unit creation.

Example bizData:

{
  "organizationalUnitId": "ou_dqdvxesykpfhig2kvgrzpeoeyu",
  "organizationalUnitName": "Organization Department",
  "parentId": "ou_dqdvxesykpdfasdfaseoeyu",
  "organizationalUnitExternalId": "ou_dqdvxesykpfhig2kvgrzpeoeyu",
  "organizationalUnitSourceType": "build_in",
  "organizationalUnitSourceId": "idaas_rhhoqmlnyu3cv7ow657gyvurky",
  "createTime": "1648451475209",
  "updateTime": "1648451475209",
  "description": "Self-built"
}

Parameters:

Parameter	Data type	Description
organizationalUnitId	String	Unique organization ID.
organizationalUnitName	String	Organization name.
parentId	String	Parent organizational unit ID.
organizationalUnitExternalId	String	External ID. For a self-managed organization, this is the same as `organizationalUnitId`. For an organization synchronized from an external source such as DingTalk, this is the department ID from DingTalk.
organizationalUnitSourceType	String	Source type.
organizationalUnitSourceId	String	Source type ID.
createTime	Long	Creation time.
updateTime	Long	Last modification time. Same as `lastUpdatedTime`.
description	String	Description.

Organization deletion

Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:delete

Subscribe to this event to handle organizational unit deletion.

Example bizData: Same as organization creation.

Organization update

Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:update

Subscribe to this event to handle updates to basic organizational unit information, such as the organization name.

Example bizData: Same as organization creation.

Move organization

Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:update_parent_organizational_unit

Subscribe to this event to handle changes to an organizational unit's parent organization.

Example bizData: Same as organization creation.

Group events

Group creation

Event type: urn:alibaba:idaas:app:event:ud:group:create

Subscribe to this event to handle group creation.

Example bizData:

{
  "groupId": "group_yvx3ugdi3yzaehnsd3uqzb4xha",
  "groupName": "test_2024",
  "groupExternalId": "test_2024"
}

Parameters:

Parameter	Data type	Description
groupId	String	Unique group ID.
groupName	String	Group display name.
groupExternalId	String	Group external ID.
allMembers	List	All current members of the group.
memberId	String	Unique user ID.
memberName	String	User display name.

Group basic information update

Event type: urn:alibaba:idaas:app:event:ud:group:update

Subscribe to this event to handle updates to basic group information.

Example bizData: Same as group creation.

Group deletion

Event type: urn:alibaba:idaas:app:event:ud:group:delete

Subscribe to this event to handle group deletion.

Example bizData: Same as group creation.

Add member to group

Event type: urn:alibaba:idaas:app:event:ud:group:add_user

Subscribe to this event to handle members being added to a group.

Example bizData:

{
  "addedMembers": [
    {
      "memberId": "user_zakg7oeeaftqqff2bzcv7wpqs4",
      "memberName": "Xiao Ming"
    }
  ],
  "groupId": "group_yvx3ugdi3yzaehnsd3uqzb4xha",
  "groupName": "test_2024_test",
  "groupExternalId": "test_2024"
}

Parameters:

Parameter	Data type	Description
groupId	String	Unique group ID.
groupName	String	Group display name.
groupExternalId	String	Group external ID.
addedMembers	List	Members added to the group.
-memberId	String	Unique user ID.
-memberName	String	User display name.

Remove member from group

Event type: urn:alibaba:idaas:app:event:ud:group:remove_user

Subscribe to this event to handle members being removed from a group.

Example bizData:

{
  "removedMembers": [
    {
      "memberId": "user_zakg7oeeaftqqff2bzcv7wpqs4",
      "memberName": "Xiao Ming"
    }
  ],
  "groupId": "group_yvx3ugdi3yzaehnsd3uqzb4xha",
  "groupName": "test_2024_test",
  "groupExternalId": "test_2024"
}

Parameters:

Parameter	Data type	Description
groupId	String	Unique group ID.
groupName	String	Group display name.
groupExternalId	String	Group external ID.
removedMembers	List	Members removed from the group.
-memberId	String	Unique user ID.
-memberName	String	User display name.

Address book full events

Full push events

Full push of organizational units

Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:push

Example bizData: Same as organization creation.

Full push of accounts

Event type: urn:alibaba:idaas:app:event:ud:user:push

Example bizData: Same as account creation.

Full push of groups

Event type: urn:alibaba:idaas:app:event:ud:group:push

Subscribe to this event to handle a full push of groups. The bizData includes all current group members.

Example bizData:

{
  "allMembers": [
    {
      "memberId": "user_zakg7oeeaftqqff2bzcv7wpqs4",
      "memberName": "Xiao Ming"
    },
    {
      "memberId": "user_zakg7oeea1234ff2bzcexample",
      "memberName": "Zhang San"
    }
  ],
  "groupId": "group_yvx3ugdi3yzaehnsd3uqzb4xha",
  "groupName": "test_2024",
  "groupExternalId": "test_2024"
}

Parameters:

Parameter	Data type	Description
groupId	String	Unique group ID.
groupName	String	Group display name.
groupExternalId	String	Group external ID.
allMembers	List	All current members of the group.
-memberId	String	Unique user ID.
-memberName	String	User display name.