Preparations

Event Callback Configuration

As an administrator, you can configure event callback on the administrator portal.

1. Log in to the administrator portal.
2. On the top navigation bar, choose Resources > Applications.
3. Click Add Custom Application in the Custom Applications section, set the logo and application name, and click Save.
4. Click the application created in 3. In the General Information area, click next to Synchronization and select Event callback. Click Save.
   Figure 1 Enabling event callback
   

5. In the General Information area, click Configure next to Synchronization. On the Parameters tab, set parameters according to Table 1 and click Save.

   Table 1 Parameters

   Parameter	Description
   Callback URL	URL used by enterprise applications to receive events pushed by OneAccess.
   Security Token	The request header of each event callback API carries a bear token. The callback service of the enterprise application needs to be authenticated.
   Encryption/Decryption Algorithm	AES/GCM/NOPadding (default) algorithms are recommended. NULL indicates that data is not encrypted, which has security risks. Exercise caution when using this method.
   Encryption Key	Keys used to encrypt a message. The value is left blank by default. Otherwise, the value must contain 16 digits.
   Signature Key	Signature key used to generate a data signature based on the message content. The value is left blank by default. Otherwise, the value must contain 16 digits.

6. (Optional) Click the application icon. In the navigation pane, choose Synchronization Integration and select the General tab to modify the mapping during synchronization, including deleting and deactivating accounts and organizations.
7. (Optional) Click the application icon. In the navigation pane, choose Object Models > Application Organization and click to enable the application organization.
   

   Skip this step if you will not synchronize organization data to the application.

8. (Optional) Configure organization attributes and mappings. Skip this step if you only need to synchronize the built-in attributes of the organization.
   1. In the navigation pane, choose Object Models > Application Organization. On the Attributes tab, click Add to configure the organization attributes synchronized to enterprise applications.
      

      • When synchronizing built-in attributes to enterprise applications, ensure that the added attribute names are the same as those in application organizations.
      • When synchronizing non-built-in attributes to enterprise applications, ensure that the attribute names are the same as those set by administrators.

      Table 2 Attribute parameters

      Parameter	Description
      Attribute (Mandatory)	Custom field ID synchronized to enterprise applications, which cannot be changed after being set.
      Label (Mandatory)	Attribute name of an organization. It is recommended that the value be the same as that of Attribute.
      Description	Description of the Attribute.
      Attribute Type (mandatory)	Type of the Attribute. You can select a value from the drop-down list. The value cannot be changed after being set.
      Format	When Attribute Type is set to Text, you can select a value from the drop-down list.
      Required	This option is not selected by default.
      Unique	When Attribute Type is set to Text, you can select Unique. If this option is selected, the attribute value must be unique when organization data is synchronized to the application. If the attribute value is duplicate, a message is displayed, indicating that the label already exists.
      Sensitive	It is required only when Attribute Type is set to Text. If this option is selected, the application data is hidden when it is synchronized to an application. You can click to view the content.

   2. On the Mappings tab, click Modify and set the mappings of the organization attribute.
      

      • When Conversion Mode is set to Script-based, compile the script by referring to Developing Mapping Scripts.
      • To prevent synchronization exceptions, you are advised to add organization attributes of the same type as the application organization attributes to be mapped.

      Table 3 Mapping parameters

      Parameter	Description
      Organization	Organization attribute mapped to the Application Organization. You can select a value from the drop-down list.
      Conversion Mode	Mode of attribute mapping between Organization and Application Organization.
      Script Expression	When Conversion Mode is set to Script-based, enter the specific mapping script.
      Execution Mode	Mode of attribute mapping between Organization and Application Organization.
      Application Organization	Organization attributes defined in 1.

   3. On the Configure tab, Delete System Org is set to Delete application organization and Disable System Org is set to Disable application organization by default. You can click Modify to modify the configuration. You can set Delete System Org to Disable application organization or Do not affect, and set Disable System Org to Do not affect. Click Save for the modification to take effect.

9. (Optional) Configure account attributes and mappings. Skip this step if you only need to synchronize the built-in attributes of the account.
   1. In the navigation pane, choose Object Models > Application Accounts. On the Attributes tab, click Add to configure account attributes synchronized to enterprise applications.
      

      • When synchronizing built-in attributes to enterprise applications, ensure that the added attribute names are the same as those in application accounts.
      • When synchronizing non-built-in attributes to enterprise applications, ensure that the attribute names are the same as those set by administrators.

      Table 4 Attribute parameters

      Parameter	Description
      Attribute (Mandatory)	Custom field ID synchronized to enterprise applications, which cannot be changed after being set.
      Label (mandatory)	Attribute name of an account. It is recommended that the value be the same as that of Attribute.
      Description	Description of the Attribute.
      Attribute Type (mandatory)	Type of the Attribute. You can select a value from the drop-down list. The value cannot be changed after being set.
      Format	When Attribute Type is set to Text, you can select a value from the drop-down list.
      Required	This option is not selected by default.
      Unique	When Attribute Type is set to Text, you can select Unique. If this option is selected, the attribute value must be unique when user data is synchronized to the application. If the attribute value is duplicate, a message is displayed, indicating that the label already exists.
      Sensitive	It is required only when Attribute Type is set to Text. If this option is selected, the user data is hidden when it is synchronized to an application. You can click to view the content.

   2. On the Mappings tab, click Modify and set the mappings of the organization attribute.
      

      • When Conversion Mode is set to Script-based, compile the script by referring to Developing Mapping Scripts.
      • To prevent synchronization exceptions, you are advised to add account attributes of the same type as the user attributes to be mapped.

      Table 5 Mapping parameters

      Parameter	Description
      User	User attribute mapped to the Application Accounts. You can select a value from the drop-down list.
      Conversion Mode	Mode of attribute mapping between User and Application Accounts.
      Script Expression	When Conversion Mode is set to Script-based, enter the specific mapping script.
      Execution Mode	Mode of attribute mapping between User and Application Accounts.
      Application Accounts	Account attributes defined in 1.

   3. On the Configure tab, Delete System User is set to Delete application account and Disable System User is set to Disable application account by default. Click Modify to modify the configuration. If you select to disable or retain the application account for Delete System User, the account automatically changes to an orphan account because the user has been deleted. You can select to retain an application account for Disable System User. Click Save for the modification to take effect.

Adding, Modifying, and Deleting Users

As an administrator, you can synchronize users on the administrator portal.

• Adding users

  In the navigation pane, choose Authorization > Application Accounts. Then click Add Accounts to authorize specific accounts to access the application. To synchronize accounts based on the authorization policy, see Configuring Authorization Policy for Application Accounts.

• Modifying users

  Choose Users > Organizations and Users from the top navigation bar. In the user list, move the cursor to the right of the target username and click . In the Modify User dialog box, update the user information.

  Figure 2 Modifying user information
  
• Deleting users

  Choose Users > Organizations and Users from the top navigation bar. In the user list, click next to the target username, select Delete, and click OK.

  Figure 3 Deleting users
  

Adding, Modifying, and Deleting Organizations

As an administrator, you can synchronize organizations on the administrator portal.

Enable the application synchronization before synchronizing organizations. For details, see 7.

• Adding organizations

  In the navigation pane, choose Authorization > Application Organizations, click Authorization Policy, and click to enable Automatic Organization Authorization. Select the organizations to be synchronized as prompted and click Save.

• Modifying organizations

  Choose Users > Organizations and Users from the top navigation bar. On the Organizations page, click Modify in the Operation column of the target organization to update the organization information.

  Figure 4 Modifying an organization
  
• Deleting an organization

  Choose Users > Organizations and Users from the top navigation bar. On the Organizations page, click Delete in the Operation column of the target organization to delete it.

  Figure 5 Deleting an organization
  

Event Synchronization

When OneAccess synchronizes data to downstream applications, all synchronization operations are recorded.

1. Log in to the administrator portal.
2. On the top navigation bar, choose Resources > Applications.
3. On the displayed page, click an application name to access the application details page.
4. Click the application icon to access the general information page.
5. In the navigation pane, choose Authorization > Synchronization Events to access the page. You can filter synchronization records by time, operation type, object type, and synchronization status.
   

   If synchronization failed:

   • Check the response and rectify the fault, and click Retry in the Operation column.
   • Click Retry to quickly perform synchronization. After you successfully retry the synchronization event of the parent organization, the synchronization events of the sub-organizations and accounts under the parent organization will be triggered.

Full Synchronization

Full synchronization can be used to ensure full data consistency between downstream application systems and OneAccess. Full synchronization complies with the following rules:

• During full synchronization, all previous synchronization events are ignored, and new events are generated. If the application system does not return an ID, a new event is generated. However, if the application system returns an ID, an update event is generated. For details, see Table 2.
  

  An update event triggered by full synchronization synchronizes all attributes configured in mappings. A common update event synchronizes only changed attributes.

• If the dependent organization fails to be synchronized, all synchronization events of its sub-organizations and accounts are suspended. In this case, click Synchronize next to Application Organizations to trigger a full synchronization of application accounts. This will also activate Synchronize next to Application Accounts.

As an administrator, you can synchronize all data to application systems on the administrator portal.

In the navigation pane, choose Synchronization Integration, select Full Synchronization tab, and click Synchronize either next to Application Accounts or Application Organizations.

Synchronization Statuses

This section describes the different statuses after the synchronization is complete. This helps you locate faults.

The following is an example, in which App_acc01 is the application account, App_org01 application organization, E0 original synchronization event, and E1 new synchronization event.

• Pending

  When the application account App_acc01 generates a new synchronization event E1, if the execution of a previous synchronization event E0 for the same account is not yet completed, the status of the new event E1 is PENDING.

• Queuing

  When the synchronization event E1 for the application account App_acc01 is ready to be executed, the event is sent to the Kafka execution message queue. Once the event is successfully sent, the status of synchronization event E1 in ES is updated to QUEUING, indicating that the event has been successfully added to the execution queue.

• Running

  When the synchronization event E1 is ready to execute, its status in ES is updated to RUNNING before the execution starts. Once the status is successfully updated, the downstream application system API is triggered to start synchronization, indicating that the event is now in the running status.

• Success

  After a synchronization event is successfully executed, its status is updated to SUCCESS in ES, indicating that the event has been successfully executed.

• Failure

  After a synchronization event fails to execute, its status is updated to FAILURE in ES, indicating that the event failed to be executed.

• Ignored

  This status involves the following two scenarios:

  • When the application account App_acc01 executes an update synchronization event, if a new update event is found subsequently, this event is directly ignored, and the new update event will be executed instead.
  • During full synchronization, all previous synchronization events are ignored.
• Skipped

  This status is not used currently.

• Waiting

  When the application account App_acc01 has a dependency on the application organization App_org01, if the synchronization of App_org01 fails, all synchronization events of App_acc01 in the organization are suspended.