How to synchronize accounts using address book events - Identity as a Service

This guide explains the event callback mechanism of Alibaba Cloud IDaaS (EIAM). Learn how to integrate the application synchronization feature, understand event parameters, and achieve efficient system integration.

Event types

This section describes the event categories. For a detailed explanation of the integration principles and call flow, see Account Synchronization Overview.

Test event

To validate the application synchronization configuration, an administrator clicks the The test is successful. button. This triggers a test event, which the application processes to verify the configuration.
Incremental event

A change in the IDaaS internal directory automatically triggers an incremental event. These events are used to continuously update and synchronize data between IDaaS and third-party applications. Listening for these events maintains data consistency between the two systems, which is ideal for real-time or near-real-time data synchronization.
Full event

A full event is a synchronization operation that an administrator manually triggers from the IDaaS console to import all data from IDaaS into the target application. This is typically used for an initial integration or when a complete data refresh is needed.

Event list

Event module	Event type	Type code
Test event	Test connection	urn:alibaba:idaas:app:event:common:test
Directory Incremental event	Account creation	urn:alibaba:idaas:app:event:ud:user:create
	Account deletion	urn:alibaba:idaas:app:event:ud:user:delete
	Basic account information update	urn:alibaba:idaas:app:event:ud:user:update_info
	Account password update	urn:alibaba:idaas:app:event:ud:user:update_password
	Account disablement	urn:alibaba:idaas:app:event:ud:user:disable
	Account enablement	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 move	urn:alibaba:idaas:app:event:ud:user:update_primary_ou
	Organizational unit creation	urn:alibaba:idaas:app:event:ud:organizational_unit:create
	Organizational unit deletion	urn:alibaba:idaas:app:event:ud:organizational_unit:delete
	Organizational unit update	urn:alibaba:idaas:app:event:ud:organizational_unit:update
	Organizational unit move	urn:alibaba:idaas:app:event:ud:organizational_unit:update_parent_organizational_unit
	Group creation	urn:alibaba:idaas:app:event:ud:group:create
	Basic group information update	urn:alibaba:idaas:app:event:ud:group:update
	Group deletion	urn:alibaba:idaas:app:event:ud:group:delete
	Add group member	urn:alibaba:idaas:app:event:ud:group:add_user
	Remove group member	urn:alibaba:idaas:app:event:ud:group:remove_user
Directory Full event	Full organizational unit push	urn:alibaba:idaas:app:event:ud:organizational_unit:push
	Full account push	urn:alibaba:idaas:app:event:ud:user:push
	Full group push	urn:alibaba:idaas:app:event:ud:group:push

For all account and organizational unit events, IDaaS sends the complete account or organizational unit information as parameters to the event listener. If the data is sensitive, use an HTTPS channel or select the business data encryption option to protect it in transit.

Test event

Test connection

This test verifies your configuration's connectivity, signature verification, and encryption.

The test event uses a dedicated event type: urn:alibaba:idaas:app:event:common:test.

Note

This event can be triggered only by a one-click test in the console; API calls are not supported.

The following example shows the payload after the signature of the request parameters has been 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\"}"
         }
     ]
  }
}

After receiving the event, your application must return a response. Ensure the eventId in the successEvents field matches the eventId from the request.

Otherwise, the test request fails.

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

Incremental address book event

User events

Account creation

Subscribe to this event to handle employee onboarding.

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

Example of the parsed 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	Type	Description
userId	String	The unique user ID.
username	String	The username.
displayName	String	The display name, typically the user's full name.
passwordSet	boolean	Indicates whether a password is set.
phoneRegion	String	The phone region code.
phoneNumber	String	The phone number.
phoneVerified	boolean	Indicates whether the phone number is verified. Currently, this verification is not performed.
email	String	The email address.
emailVerified	boolean	Indicates whether the email address is verified. Currently, this verification is not performed.
userExternalId	String	The external ID. For a self-built account, this value is the same as `userId`. For an account synchronized from an external source, this is the user's ID from that source. For example, if a user is from DingTalk, this is their DingTalk `userId`.
userSourceType	String	The account's source type. For a self-built account, the value is `build_in`.
userSourceId	String	The ID of the account source.
password	String	The password. This parameter is included if password synchronization is enabled for the application and the user has set a password.
status	String	The account status. Valid values: `enabled` and `disabled`.
accountExpireTime	Long	The account expiration time.
registerTime	Long	The registration time.
lockExpireTime	Long	The lock expiration time. The account is unlocked at this time.
createTime	Long	The creation time.
updateTime	Long	The last modification time.
description	String	The description.
customFields	List	The extension fields.
-fieldName	String	The field name.
-fieldValue	String	The field value.
primaryOrganizationalUnitId	String	The ID of the primary organizational unit.
organizationalUnits	List	A list of organizational units to which the user belongs.
-organizationalUnitId	String	The organizational unit ID.
-organizationalUnitName	String	The organizational unit name.
-primary	boolean	Indicates whether this is the user's primary organizational unit. `true` for the primary unit; `false` otherwise.

Account deletion

Subscribe to this event to handle employee offboarding. This event is triggered when an account is removed from the address book.

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

Example of the parsed bizData: Same as for account creation.
Account basic information update

Subscribe to this event to receive timely updates when a user's basic information, such as their phone number, email address, or name, changes.

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

Example of the parsed bizData: Same as for account creation.
Account password update

This event is triggered when a user's password is changed, either by the user or an administrator. Subscribe to this event to receive the new password.

Important
Note: You must configure the synchronization scope to receive this event. Otherwise, the system does not send it. For more information, see Account Synchronization - Synchronize from IDaaS to Applications.

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

Example of the parsed bizData: Same as for account creation.
Account enable

Subscribe to this event to be notified when an account's status changes from disabled to enabled.

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

Example of the parsed bizData: Same as for account creation.
Account disable

Subscribe to this event to be notified when an account's status changes from enabled to disabled.

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

Example of the parsed bizData: Same as for account creation.
Account lock

Subscribe to this event to be notified when an account is locked, for example, due to multiple incorrect password attempts.

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

Example of the parsed bizData: Same as for account creation.
Account unlock

Subscribe to this event to be notified when a locked account is unlocked.

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

Example of the parsed bizData: Same as for account creation.
Account move

Subscribe to this event to be notified when an account's primary organizational unit changes.

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

Example of the parsed bizData: Same as for account creation.

Organizational unit (OU) events

Organizational unit creation

Subscribe to this event to handle organizational unit creation.

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

Example bizData payload:

{
    "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	Type	Description
organizationalUnitId	String	The unique ID of the organizational unit.
organizationalUnitName	String	The name of the organizational unit.
parentId	String	The ID of the parent organizational unit.
organizationalUnitExternalId	String	The external ID. This ID matches `organizationalUnitId` if the organizational unit is created internally. If synchronized from an external source like DingTalk, this ID corresponds to the department ID from that source.
organizationalUnitSourceType	String	The source type.
organizationalUnitSourceId	String	The ID of the source.
createTime	Long	The creation time.
updateTime	Long	The last modification time.
description	String	A description of the organizational unit.

Organizational unit deletion

Subscribe to this event to handle organizational unit deletion.

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

The bizData payload is identical to the one for organizational unit creation.
Organizational unit update

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

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

The bizData payload is identical to the one for organizational unit creation.
Organizational unit move

Subscribe to this event to handle the movement of an organizational unit to a new parent.

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

The bizData payload is identical to the one for organizational unit creation.

Group events

Group creation

Use this event to handle group creation.

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

Example of the parsed bizData:

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

Parameters:

Parameter	Type	Description
groupId	String	A unique identifier for the group.
groupName	String	The display name of the group.
groupExternalId	String	The external ID of the group.
allMembers	List	All current members of the group.
memberId	String	A unique identifier for the user.
memberName	String	The display name of the user.

Basic information update

Use this event to handle updates to basic group information.

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

Example of the parsed bizData: Same as for group creation.
Group deletion

Use this event to handle group deletion.

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

Example of the parsed bizData: Same as for group creation.

Member addition

Use this event to handle adding a member to a group.

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

Example of the parsed bizData:

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

Parameters:

Parameter	Type	Description
groupId	String	A unique identifier for the group.
groupName	String	The display name of the group.
groupExternalId	String	The external ID of the group.
addedMembers	List	A list of members to add to the group.
-memberId	String	A unique identifier for the user.
-memberName	String	The display name of the user.

Member removal

Use this event to handle removing a member from a group.

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

Example of the parsed bizData:

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

Parameters:

Parameter	Type	Description
groupId	String	A unique identifier for the group.
groupName	String	The display name of the group.
groupExternalId	String	The external ID of the group.
removedMembers	List	A list of members to remove from the group.
-memberId	String	A unique identifier for the user.
-memberName	String	The display name of the user.

Address book full events

Full push events

Full push of organizational units

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

Parsed bizData example: Same as for organizational unit creation.
Full push of accounts

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

Parsed bizData example: Same as for account creation.

Full push of groups

Subscribe to this event to receive a complete list of all groups and their members.

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

Parsed bizData example:

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

Parameters:

Parameter	Type	Description
groupId	String	The unique ID of the group.
groupName	String	The display name of the group.
groupExternalId	String	The external ID of the group.
allMembers	List	All current members of the group.
-memberId	String	The unique ID of the member.
-memberName	String	The display name of the member.