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

This document explains the event callback mechanism of Alibaba Cloud IDaaS and provides a comprehensive guide for developers on integrating application synchronization. It covers event parameter categories and processing flows to help you achieve efficient system integration.

Basic information

This section describes the event parameters and their categories. For more information about the integration principles and call flows, see Account synchronization overview.

Test event
After an administrator configures application synchronization, they can click the The test is successful. button to validate the configuration. This action triggers a test event. The application must receive and process this event to confirm that the configuration is correct.
Incremental event
Incremental events are automatically triggered when changes occur in the IDaaS internal address book. These events are used for continuous data updates and synchronization between IDaaS and third-party applications. By listening for these events, you can maintain data consistency between both systems. This is especially useful for scenarios that require 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 interface. Its purpose is to import all data from IDaaS into the target application at once. This type of synchronization is typically used for initial integration or for scenarios that require a complete data update.

Event checklist

Event module	Event type	Type code
Test event	Test connection	urn:alibaba:idaas:app:event:common:test
Address book incremental events	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
	Organization creation	urn:alibaba:idaas:app:event:ud:organizational_unit:create
	Address book events	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
	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
Address book full events	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

For all account and organization events, IDaaS sends the complete account or organization information as parameters to the event listener. If the data contains sensitive information, you can use an HTTPS encrypted channel or select Business Data Encryption to protect the data during transmission.

Test event

Test connection

This event tests the connectivity of the configuration information. It also validates signature verification and encryption capabilities.

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

Note

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

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

The application must return a response after it successfully receives an event. Ensure that the eventId in the successEvents field of the response 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": ""
    }
  ]
}

Address book incremental events

User events

Account creation

You can 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
        }
    ]
}

Parameter descriptions:

Parameter	Data type	Description
userId	String	Unique user ID.
username	String	Username.
displayName	String	Display name. Usually the user's full name.
passwordSet	boolean	Indicates whether a password is set.
phoneRegion	String	Area code for the phone number.
phoneNumber	String	Phone number.
phoneVerified	boolean	Indicates whether the phone number is verified. Verification is not currently performed.
email	String	Mailbox.
emailVerified	boolean	Indicates whether the mailbox is verified. Verification is not currently performed.
userExternalId	String	External ID. If it is a self-built account, this ID is the same as the `userId`. If it is 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	The source type for a self-built account is "build_id".
userSourceId	String	Source type ID.
password	String	Password. This value is passed if password synchronization is enabled for the application and the user has set a password.
status	String	Status. `enabled` indicates that the account is enabled. `disabled` indicates that 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	Modification time.
description	String	Description.
customFields	List	List of extension fields.
-fieldName	String	Field name identity.
-fieldValue	String	Field value.
primaryOrganizationalUnitId	String	The primary organizational unit to which the user belongs.
organizationalUnits	List	Affiliated organizations
-organizationalUnitId	String	Unique ID of the organizational unit.
-organizationalUnitName	String	Name of the organizational unit.
-primary	boolean	Primary organizational unit. `true` indicates it is the primary organizational unit. `false` indicates it is not.

Account deletion
When an employee leaves, their account information in the address book changes. You can subscribe to this event to receive these updates.
Event type: urn:alibaba:idaas:app:event:ud:user:delete.
Example of the parsed bizData: Same as for account creation.
Account basic information update
If an employee's basic information, such as their phone number, mailbox, or name, changes, the application needs to receive the updated information promptly. You can subscribe to this event to receive these updates.
Event type: urn:alibaba:idaas:app:event:ud:user:update_info.
Example of the parsed bizData: Same as for account creation.
Account password update
When an account password changes, for example, when an administrator resets it or a user modifies it, the application can subscribe to this event to receive the new password.
Important
To subscribe to this event, you must also configure the synchronization scope for the subscription to take effect. Otherwise, synchronization will not occur. 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
This event is triggered when the account status changes from disabled to enabled. You can subscribe to this event to receive this change notification.
Event type: urn:alibaba:idaas:app:event:ud:user:enable.
Example of the parsed bizData: Same as for account creation.
Account disable
This event is triggered when the account status changes from enabled to disabled. You can subscribe to this event to receive this change notification.
Event type: urn:alibaba:idaas:app:event:ud:user:disable.
Example of the parsed bizData: Same as for account creation.
Account lock
This event is triggered when the account status changes to locked. For example, if a user enters the wrong password multiple times, the account is locked and becomes temporarily unavailable. You can subscribe to this event to receive this change notification.
Event type: urn:alibaba:idaas:app:event:ud:user:lock.
Example of the parsed bizData: Same as for account creation.
Account unlock
This event is triggered when the account status changes from locked to normal. You can subscribe to this event to receive this change notification.
Event type: urn:alibaba:idaas:app:event:ud:user:unlock.
Example of the parsed bizData: Same as for account creation.
Account shift
This event is triggered when the primary organizational unit of an account changes. You can subscribe to this event to receive this change notification.
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

Organization creation

You can subscribe to this event to handle organizational unit creation.

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

Example of the parsed 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"
}

Parameter descriptions:

Parameter	Data type	Description
organizationalUnitId	String	Unique organization ID.
organizationalUnitName	String	Organization name.
parentId	String	Parent organizational unit ID.
organizationalUnitExternalId	String	The external ID for a self-managed organization. organizationalUnitId. If it is 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	Modification time. Same as lastUpdatedTime.
description	String	Description.

Organization deletion
You can use this event subscription to delete an organization.
Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:delete.
Example of the parsed bizData: Same as for organization creation.
Organization update
You can subscribe to this event to handle updates to basic organizational unit information, such as the organization name.
Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:update.
Example of the parsed bizData: Same as for organization creation.
Organization shift
You can subscribe to this event to handle changes to an organizational unit's parent organization.
Event type: urn:alibaba:idaas:app:event:ud:organizational_unit:update_parent_organizational_unit.
Example of the parsed bizData: Same as for organization creation.

Group events

Group creation

You can create them in this event subscription group.

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

Example of the parsed bizData:

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

Parameter descriptions:

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

Group basic information update
You can update the basic information for an event subscription group.
Event type: urn:alibaba:idaas:app:event:ud:group:update.
Example of the parsed bizData: Same as for group creation.
Group deletion
You can delete this event subscription group.
Event type: urn:alibaba:idaas:app:event:ud:group:delete.
Example of the parsed bizData: Same as for group creation.

Add member to group

You can add members to this event subscription 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"
}

Parameter descriptions:

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

Remove member from group

You can remove members from an event subscription 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"
}

Parameter descriptions:

Parameter	Data type	Description
groupId	String	Unique group identity.
groupName	String	Group display name.
groupExternalId	String	Group external ID.
removedMembers	List	Members to be removed.
-memberId	String	Unique user identity.
-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 of the parsed bizData: Same as for organization creation.
Full push of accounts
Event type: urn:alibaba:idaas:app:event:ud:user:push.
Example of the parsed bizData: Same as for account creation.

Full push of groups

You can subscribe to this event to handle a full push of groups.

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

Example of the parsed bizData:

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

Parameter descriptions:

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