Identity as a Service:Visão geral da integração de sincronização de contas

Este tópico é uma referência para desenvolvedores sobre o Application Identity and Access Management (EIAM). Ele aborda os principais recursos, casos de uso e diretrizes de integração para gerenciamento unificado de identidades e single sign-on.

Contexto

O Identity as a Service (IDaaS) permite integrar aplicações personalizadas para sincronizar organizações e contas do IDaaS para sua aplicação. Para sincronizar contas da sua aplicação para o IDaaS, consulte Referência de API para desenvolvimento de aplicações.

Para obter informações sobre a configuração de sincronização de aplicações, veja Sincronização de contas - Sincronizar do IDaaS para a aplicação. Este tópico descreve como integrar uma aplicação para sincronização de contas conforme a especificação do IDaaS.

• Sincronize as alterações de conta do IDaaS rapidamente. Por exemplo, durante a admissão de um funcionário, o IDaaS cria uma conta. A aplicação de RH deve criar a conta correspondente quase simultaneamente para evitar atrasos no processo de integração. Para isso, assine o evento Create account.

• Sua aplicação deve responder prontamente às ações do usuário. Se um usuário atualizar o número de celular após fazer login, por exemplo, a aplicação precisa refletir essa mudança imediatamente. Nesse caso, assine o evento Update account.

Mecanismo de callback de eventos

Os exemplos anteriores ilustram dois casos de uso simples. Assine diferentes eventos e processe-os conforme suas necessidades específicas.

O IDaaS oferece um método padronizado, seguro e prático para sincronizar dados com sua aplicação. Esse método permite que a aplicação receba solicitações de sincronização com configuração mínima.

Esse sistema baseia-se em um mecanismo de callback de eventos.

No IDaaS, configure os eventos que deseja monitorar, como a criação de contas. Quando um evento especificado ocorre, o IDaaS envia automaticamente uma solicitação HTTP POST para o assinante do evento.

O processo consiste em duas partes principais:

• Assinatura de eventos: Configure os eventos que deseja monitorar no console do IDaaS.

• Recebimento de eventos: Desenvolva sua aplicação para tratar os dados dos eventos recebidos de acordo com as especificações.

Assinar eventos

Após criar uma aplicação no IDaaS, acesse o menu Provisioning para configurar a sincronização de contas da aplicação.

Para obter etapas detalhadas de configuração, consulte Sincronizar do IDaaS para uma aplicação - SCIM.

Na configuração de eventos de callback, selecione os eventos aos quais sua aplicação deve se inscrever. Quando um evento assinado ocorrer, o IDaaS enviará uma solicitação para sua aplicação.

Receber callbacks

Quando um evento ocorre, o IDaaS envia uma solicitação POST para a URL for receiving synchronization requests configurada.

O código a seguir mostra um exemplo de solicitação:

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"
}

Todos os parâmetros são passados no campo event. O valor desse campo é um JSON Web Token (JWT) assinado, conforme especificado em RFC 7515 JWS.

Formato do evento

Utilize uma biblioteca padrão e open-source da sua linguagem de programação para analisar o JWT.

Para fins de teste, cole o valor do JWT em uma ferramenta como https://jwt.io/ para inspecionar seu conteúdo.

O valor de event consiste em um header e um payload.

Exemplo de header:

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

Exemplo de 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.
      }
    ]   
  }
}

A tabela a seguir descreve os campos do evento.

Verificação de assinatura

Primeiramente, verifique a assinatura JWT para confirmar que o IDaaS emitiu o event. Ignorar essa verificação pode permitir que agentes mal-intencionados forjem a solicitação.

Obtenha as informações da chave pública usadas para validar assinaturas JWT no Public Key Endpoint dentro do menu de sincronização. Utilize-as para validar se o conteúdo do evento enviado à sua aplicação provém de uma fonte legítima. Recomendamos o uso de um toolkit JWT open-source compatível com sua linguagem de desenvolvimento para verificar a assinatura.

Descriptografia de dados (opcional)

O IDaaS suporta transmissão criptografada dos dados de eventos. Quando ativada, os dados criptografados são passados no campo cipherData do payload.

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

Ao ativar esse recurso, forneça sua própria chave de criptografia ou permita que o IDaaS gere uma para você. Antes de enviar um callback de evento, o IDaaS usa essa chave para criptografar todos os dados da solicitação.

Para criptografar eventos, o IDaaS utiliza o algoritmo de criptografia simétrica AES-256 e o formato JSON Web Encryption (JWE).

Sua aplicação precisa usar a mesma chave para descriptografar os dados.

Para um exemplo de desenvolvimento, consulte Exemplo de integração de aplicação Java para sincronização de contas.

Formato de resposta

Sua aplicação deve retornar o resultado do processamento do evento conforme as especificações do IDaaS. O IDaaS registra esse resultado e age com base nas informações retornadas.

Resposta de sucesso

Caso a solicitação seja processada com êxito, retorne um código de status HTTP 200 e um corpo de resposta que inclua o eventId e o resultado do processamento. O formato é o seguinte:

Exemplo de resposta de sucesso:

{
    "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"
        }
    ]
}

Resposta de falha

Se o processamento falhar, retorne um código de status HTTP na faixa 4xx ou 5xx.

Retorne os seguintes parâmetros no corpo da resposta em caso de falha:

Recomendamos utilizar os seguintes códigos de erro para cenários comuns de falha:

Exemplo de resposta de falha:

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