Background

You can integrate self-developed applications with Identity as a Service (IDaaS) to synchronize IDaaS organizations and accounts to the applications.

For more information about how to synchronize application accounts to IDaaS, see API operations for application development.

For more information about how to configure application synchronization, see Synchronize IDaaS accounts on an application in Provisioning. This topic describes how to integrate applications with IDaaS to implement account synchronization.

• Consistency of dependencies: Related parties may rely on the identity data in your application for marketing or verification. Therefore, you must promptly synchronize IDaaS account changes. For example, when an employee is onboarded, an account is created in IDaaS. To stay on schedule, an account must be created in the HR application at the same time. In this case, you can subscribe to the Create account event.

• Real-time requirements: Your application must promptly respond to user operations. For example, after a user logs on to the system and changes their mobile number, the mobile number of the user must be updated in your application by using the Update account event.

Event Callback Mechanism

The preceding examples are two simple scenarios. Based on different requirements, developers can subscribe to various events to process data accordingly.

IDaaS provides a convenient and secure method to synchronize IDaaS changes to applications. You can quickly integrate applications with IDaaS to allow the applications to receive synchronization requests.

This method is implemented by using an event callback mechanism.

In IDaaS, you can configure an event that you want to follow (such as the Create account event). When the event occurs, a synchronization request is automatically sent to the event subscriber by using HTTP POST.

The event mechanism consists of the following two parts:

• Subscribe to an event: Log on to the IDaaS console and configure the IDaaS event that you want to follow.

• Receive the event callback: The developer must integrate the application with IDaaS to implement account synchronization as required.

Subscribe to an Event

After you create an application in IDaaS, click Provisioning to configure account synchronization.

For more information, see Synchronize IDaaS accounts on an application in Provisioning.

You can subscribe the application to one or more events. The following figure shows the events that you can follow.

When a selected event occurs, IDaaS sends a request to the application.

Receive the Callback

When a selected event occurs, IDaaS sends a POST request to the configured URL for receiving synchronization requests.

The following code provides an example on how to configure request parameters:

Content-Type: application/json;charset=utf-8

// An example of the body of a POST request from IDaaS. After the application obtains the parameters, it verifies the signature.
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

All the parameters are passed in the event field in the JSON Web Token (JWT) format, which contains the signature. For more information, see RFC 7515: JSON Web Signature (JWS).

Event Format

You must use the universal open-source tools for various languages to parse the JWT information.

For testing purposes, you can also paste the value in the JWT format in the field at https://jwt.io/ to view the content.

The event value consists of two parts: header and payload.

Sample header:

{
    "kid": "KEYH1zR7XLCGcHw1hzhkCqVjnuyaAJUf6yMR",
    "typ": "JWT",
    "alg": "RS256"
}

Sample payload:

{
  "iss":"urn:alibaba:idaas:app:event", 
  "sub":"idaas-121313", 
  "aud":"app_12131313",
  "exp":1640966400, 
  "iat":1640966400, 
  "jti": "cNetm9OD5bXqfVfdvqGMYw",
  "dataEncrypted":false,
  "cipherData":"",    
  "plainData":{
    "aliUid":1231313,  // The ID of the Alibaba Cloud account.
    "instanceId":"instance ID",  // The ID of the instance.
    "eventVersion":"V1.0",  // The version number of the event.
    "eventData":[
      {
        "eventId":"",     // The ID of the event.
        "eventType":"",   // The type of the event.
        "eventTime":121313,  // The time when the event occurred.
        "bizId":"business ID",  // The ID of the business. If the business is an organization, the value is the ID of the organization.
        "bizData":{}       // The specific data details. This field value varies with event types. For more information, see address book events.
      }
    ]   
  }
}

The following table describes the fields contained.

Signature Verification

The JWT signature must be verified to confirm that the event information is issued by IDaaS. Signature verification prevents request forgery.

On the synchronization page, you can obtain the public key endpoint to verify the JWT signature and the source of the event sent to the application. We recommend that you use the open-source JWT toolkit of the programming language for signature verification.

Data Decryption (optional)

The encrypted transmission of event synchronization data is supported. The encrypted fields are passed in the cipher_data field in payload.

{
    ...
    "cipher_data": "ZePq7ckODWnL54vqZc3kTw0vF7tjvIRZjqqy/gZm9oTEt71WMufD9swlmHzZkniSqyDGQpkmMRLCXz9gzRJ4BY2RroLUPQW8ZDPSfmJKEf2m2w6wY1twoRlnHLoFCVhravsvN0afBqmxd3eK5tHd05Ze6MLOXS3fqxqH61dGAm2mwecvAFPRrKVeg6JXBYUvA2Uu6dmCOP3y938kFdhodD13O05MBIqWghq569wYvVjKMFMcnsZqmGGKXN0vRFhg+SR16sr24b1X/gQDbNqyMDICB9k3QMe09dOodwNEwvgxbf1v4PbyCRX1P9UO74nDQaWROWZFplE7qP/JMy3pBr0pxW+hJS9u/Zpvj/hvLlhBTAZkmhAKDKxlrYztqrgJbr4VOUv8mlqxWjDK4I7VZugODJMSwi1HdjXL+wlMzPMOeH8rkDFU+b5VH3dsxg3hZ64Ukd7exB62QyyeIJpfk0d57xw8UACiSsXadexQYpJPDycVdmJ7FAmIhxbJ8I6w9Kcv9U5sKybUz1YA8tONAw=="
    ...
}

After you enable the feature, you can enter an encryption key or generate an encryption key. Before IDaaS sends an event callback request, IDaaS uses this key to encrypt all the request data before transmission.

IDaaS uses the AES-256 algorithm for symmetric encryption and encrypts events in the JSON Web Encryption (JWE) format.

The application must use the same key for decryption to obtain the synchronization data.

For more information, see Integrate an application to implement user synchronization by using Java.

Response

The application must return the processing result of the event according to IDaaS specifications. IDaaS records the result and processes the data based on the returned information.

Success response

If the request is processed, the application must return eventId and the result in the following formats.

Sample success responses

{
    "successEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "The error code returned",
            "eventMessage": "The error message returned"
        }
    ],
    "failedEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "The error code returned",
            "eventMessage": "The error message returned"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "The ID of the event",
            "eventCode": "The error code returned",
            "eventMessage": "The error message returned"
        }
    ]
}

Failure response

If the processing fails, the application must return the HTTP 403, 429, or 500 status code.

The following parameters are returned if the processing fails.

Generally, the following error codes are returned.

Sample error responses

{
     "error": "invalid_token",
     "error_description": "The JWS token is invalid."
}