Account synchronization integration overview

Background

Identity as a Service (IDaaS) supports integration with custom applications to synchronize organizations and accounts from IDaaS to your application. To synchronize accounts from your application to IDaaS, see API reference for application development.

For information about application synchronization configuration, see Account Synchronization - Synchronize from IDaaS to Application. This topic describes how to integrate an application for account synchronization according to the IDaaS specification.

• Account changes must be synchronized from IDaaS promptly. For example, during employee onboarding, an account is created in IDaaS. The HR application must create a corresponding account almost simultaneously to prevent delays in the onboarding process. To achieve this, subscribe to the Create account event.

• Your application needs to respond to user actions promptly. For example, if a user updates their mobile number after logging in, your application must reflect this change immediately. To do this, subscribe to the Update account event.

Event callback mechanism

The preceding examples are two simple use cases. You can subscribe to different events and handle them according to your specific needs.

IDaaS provides a standardized, secure, and convenient method to synchronize data to your application. This method allows your application to receive synchronization requests with minimal setup.

This system is built on an event callback mechanism.

In IDaaS, you configure the events that you want to monitor, such as account creation. When a specified event occurs, IDaaS automatically sends an HTTP POST request to the event subscriber.

The process consists of two main parts:

• Subscribing to events: Configure the events you want to monitor in the IDaaS console.

• Receiving events: Develop your application to handle incoming event data according to the specifications.

Subscribe to events

After creating an application in IDaaS, go to the Provisioning menu to configure account synchronization for the application.

For detailed configuration steps, see Synchronize from IDaaS to an application - SCIM.

In the callback event configuration, you can select the events that you want your application to subscribe to. When a subscribed event occurs, IDaaS sends a request to your application.

Receive callbacks

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

The following code shows a sample request:

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

// Example of the body of a POST request from IDaaS. Your application verifies the signature after receiving the parameters.
{
 "event":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

All parameters are passed in the event field. The value of this field is a signed JSON Web Token (JWT), as specified in RFC 7515 JWS.

Event format

You must use a standard, open-source library for your programming language to parse the JWT.

For testing purposes, you can paste the JWT value into a tool like https://jwt.io/ to inspect its contents.

The event value consists of a header and a 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 instance ID.
    "eventVersion":"V1.0",  // The event version.
    "eventData":[
      {
        "eventId":"",     // The event ID.
        "eventType":"",   // The event type.
        "eventTime":121313,  // The time when the event occurred.
        "bizId":"Business data ID",  // The business data ID. For an organization, this is the organization ID.
        "bizData":{}       // The detailed data. This field varies depending on the event type. For more information, see the address book event reference.
      }
    ]   
  }
}

The following table describes the fields in the event.

Signature verification

First, verify the JWT signature to confirm that the event was issued by IDaaS. If you skip this verification, a malicious actor could forge the request.

You can obtain the public key information used to verify JWT signatures from the Public Key Endpoint in the sync menu, and use it to verify that the event content sent to your application is from a valid source. We recommend that you use an open-source JWT toolkit for your development language to perform the signature verification.

Data decryption (optional)

IDaaS supports encrypted transmission of event data. When enabled, the encrypted data is passed in the cipherData field of the payload.

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

After enabling this feature, you can either provide your own encryption key or have IDaaS generate one for you. Before sending an event callback, IDaaS uses this key to encrypt the entire request data.

IDaaS uses the AES-256 symmetric encryption algorithm and the JSON Web Encryption (JWE) format to encrypt events.

Your application must use the same key to decrypt the data.

For a development example, see Java application integration example for account synchronization.

Response format

Your application must return the event processing result according to IDaaS specifications. IDaaS logs this result and acts on the information returned.

Success response

If the request is processed successfully, you must return an HTTP 200 status code and a response body that includes the eventId and the processing result. The format is as follows:

Sample success response:

{
    "successEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "SUCCESS",
            "eventMessage": "SUCCESS"
        }
    ],
    "skippedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "A skip code",
            "eventMessage": "A skip message"
        }
    ],
    "failedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "An error code",
            "eventMessage": "An error message"
        }
    ],
    "retriedEvents": [
        {
            "eventId": "The event ID",
            "eventCode": "An error code",
            "eventMessage": "An error message"
        }
    ]
}

Failure response

If processing fails, you must return an HTTP status code in the 4xx or 5xx range.

The parameters to return in the response body for a failure are as follows:

We recommend that you use the following error codes for common failure scenarios:

Sample failure response:

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