1. Introdução

Este documento descreve, em uma "linguagem natural estruturada", O problema da integração entre um "Robô" (uma URA hipotética) e o Keycloak (ou o RH-SSO dependendo do caso).

No futuro este documento poderá ser atualizado para utilizar BPMN no lugar dessa "linguagem natural estruturada".

O objetivo deste documento é auxiliar desenvolvedores que precisem fazer uma integração do Keycloak com uma URA a entender quais seriam os participantes dessa integração e quais seriam seus papéis nela.

De forma bem específica, O RobôHelper é o componente participante que precisaria ser criado pelo desenvolvedor de uma solução de integração onde houvessem os fluxos descritos abaixo que são categorizados em dois: Atendimento Robótico e Atendimento Humano.

2. O problema

  1. Uma pessoa deseja acessar o "Sistema1" da empresa "XPTO". Essa empresa também possui vários outros sistemas, além do Sistema1. Para acessar o Sistema1, a pessoa inicia sua interação com este através de um Robô da empresa. Esse Robô lhe oferece um Atendimento Robótico.

  2. O Robô é de confiança da empresa. Isso significa que a pessoa pode informar sua senha para o Robô (quando solicitado por ele). Também significa que o Robô é capaz de conceder acesso ao Sistema1 (ou a qualquer outro da empresa).

  3. O Robô utiliza uma extensão do único software de Single Sing-On (SSO) da empresa: o Keycloak. Essa extensão é chamada de "RobôHelper".

  4. O RobôHelper funciona completamente acoplado (e integrado) ao Keycloak. Nele são configurados parâmetros de segurança que são averiguados pelo Robô. Esses parâmetros indicam, por exemplo, se uma senha deve ser numérica e de 6 dígitos e se ela não pode ser igual as duas últimas senhas utilizadas. Ele é invocado por operações do Robô e, também, por operações do Atendimento Humano.

  5. O Robô jamais armazena a senha de uma pessoa e também não valida detalhes a respeito dela. Sendo assim, ele não sabe se a senha precisa ser numérica ou se não pode ser igual as últimas senhas (por exemplo). Por esse motivo é que ele precisa da ajuda do RobôHelper.

  6. O Robô pode transferir a pessoa para o Atendimento Humano. O atendente pode apenas criar uma senha temporária para a pessoa (através do RobôHelper). O atendente não pode, jamais, saber qual é a senha final da pessoa para o Sistema1 (ou qualquer outro).

    1. Somente o RobôHelper pode cadastrar a pessoa no Sistema1 (e apenas através de uma requisição oriunda de um atendente). Essa senha temporária é de alteração obrigatória quando o atendente transfere o fluxo do Atendimento Humano para o Atendimento Robótico encerrando o cadastro da pessoa. Novamente: isso é para impedir que o atendente saiba qual é senha que será utilizada pela pessoa elevando, assim, o nível de segurança do Sistema1.

  7. A senha utilizada pela pessoa para acessar o Sistema1 também pode ser utilizada para que ela tenha acesso a outros sistemas. Para isso é necessário que esses outros sistemas estejam no mesmo "Realm" do Sistema1.

3. Atendimento Robótico

3.1. Visão geral

No "Atendimento Robótico" um Robô repetidamente {
   Observa um status oriundo do "Atendimento Humano" ou pergunta à pessoa que ele está atendendo, o que ela deseja.
   Caso o status do oriundo do "Atendimento Humano" ou a resposta da pessoa, seja {
      "Cadastrar pessoa" {
         O Robô transferirá a pessoa ao "Atendimento Humano" com o status: "Cadastrar pessoa".
            Essa operação será realizada pelo atendente que utilizará o RobôHelper.
      }
      "Alterar senha" {
         O Robô executará o fluxo "Alterar senha".
      }
      "Validar senha" {
         O Robô executará o fluxo "Validar senha".
      }
   }
}

3.2. Fluxo "Alterar senha"

"Alterar senha" {
   Se uma senha não foi informada OU é preciso confirmar a senha informada {
      A pessoa informará a senha falando-a para o Robô (ou digitando-a no teclado oferecido por ele).
      O Robô, por uma chamada ao RobôHelper, verificará se a senha tem uma formação válida e salvará a resposta retornada por ele.
         Essa chamada do Robô ao RobôHelper é necessária pois ele não guarda (em si) a senha da pessoa e nem suas características.
         É o RobôHelper que verifica, por exemplo, se a senha é numérica, de seis dígitos, e se não é igual as duas últimas senhas utilizadas pela pessoa.
      Se a senha informada pela pessoa não tiver uma formação válida {
         O Robô incrementará o número da tentativa da pessoa para criar uma senha.
         Se ainda não for a terceira tentativa que a pessoa teve para criar uma senha {
            O Robô informará à pessoa a resposta que salvou do retorno da chamada ao RobôHelper.
            O Robô reentrará no fluxo "Alterar senha" sem informar uma senha mas com o número de tentativa incrementado.
         } senão {
            O Robô transferirá a pessoa ao "Atendimento Humano" com o status: "Dificuldade para criar senha".
         }
      }
      Se uma senha não foi informada {
         O Robô reentrará no fluxo "Alterar senha" passando a senha informada e a informação de que é preciso confirmar essa senha.
      }
   }
   Se a senha informada pela pessoa for diferente da senha passada para o fluxo {
      O Robô informará à pessoa: "As senhas digitadas não são iguais. Vamos tentar novamente."
   } senão {
      O Robô informará à pessoa: "Sua nova senha foi confirmada."
   }
}

3.3. Fluxo "Validar senha"

"Validar senha" {
   O Robô questionará à pessoa o seu "username" (ou seu CPF).
   O Robô validará, através do RobôHelper, se a pessoa já está cadastrada.
   Se a pessoa não estiver cadastrada {
      O Robô transferirá a pessoa ao "Atendimento Humano" com o status: "Cadastrar pessoa".
   } senão {
      "Validar tentativa de senha" {
         Se o número da tentativa for menor que 3 {
            O Robô solicitará que a pessoa informe sua senha para validá-la através do RobôHelper.
            A pessoa informará sua senha para o Robô falando para ele qual é ela (ou digitando-a no teclado disponibilizado pelo Robô).
            O Robô validará, através do RobôHelper, a senha da pessoa junto ao Sistema1.
            Se a senha estiver correta {
               O Robô entregará o token de acesso ao Sistema1 para pessoa.
            } senão {
               O Robô incrementará o número da tentativa da pessoa de acertar sua senha.
               O Robô informará à pessoa: "Senha inválida. Por favor tente novamente."
               O Robô reentrará no fluxo "Validar tentativa de senha" informando o número da tentativa.
            }
         } senão {
            O Robô transferirá a pessoa ao "Atendimento Humano" com o status: "O número máximo de tentativas de senha foi excedido".
         }
      }
   }
}

4. Atendimento Humano

4.1. Visão geral

No "Atendimento Humano" um atendente aguarda solicitações para o atendimento de uma pessoa {
   Quando surge uma solicitação de atendimento para uma pessoa o atendente recebe, nela, o status do "Atendimento Robótico".
   O atendente confirma com a pessoa o atendimento desejado (em função do status recebido).
   Caso o atendimento desejado pela pessoa seja para {
      "Cadastrar pessoa" {
         O atendente executará o fluxo "Cadastrar pessoa".
      }
      "Dificuldade para criar senha" {
         TODO ...
      }
      "O número máximo de tentativas de senha foi excedido" {
         TODO ...
      }
   }
}

4.2. Fluxo "Cadastrar pessoa"

"Cadastrar pessoa" {
   O atendente {
      Perguntará à pessoa algumas informações necessárias para cadastrá-la no Sistema1.
      Executará o subfluxo "Cadastrar a pessoa e/ou definir uma senha temporária".
      Informará a senha temporária para a pessoa.
      Redirecionará a pessoa para o "Atendimento Robótico" com a opção "Alterar senha".
   }
}

4.2.1. Subfluxo "Cadastrar a pessoa e/ou definir uma senha temporária"

"Cadastrar a pessoa e/ou definir uma senha temporária" {
   Por uma solicitação do "Atendimento Humano", o RobôHelper receberá o "username" (ou o CPF).
   Se a pessoa ainda não estiver cadastrada {
      O RobôHelper fará o cadastro da pessoa.
   }
   O RobôHelper {
      Criará uma senha temporária para a pessoa.
      Finalizará este fluxo devolvendo, como resultado, a senha temporária gerada para a pessoa.
   }
}

5. O RobôHelper

Como observado pela descrição dos fluxos acima, o RobôHelper é um componente integrado ao Keycloak que deve:

  1. Implementar uma extensão da API REST do Keycloak que será acessível tanto ao Atendimento Robótico quanto ao Atendimento Humano. Dessa forma:

    1. Para ter acesso a essa API o Robô deverá estar autenticado no Keycloak. Essa autenticação deverá ser realizada via Client Credentials.

    2. Para poder invocar o Subfluxo "Cadastrar a pessoa e/ou definir uma senha temporária", o atendente deverá estar autenticado no sistema de atendimento e possuir um token contendo uma "Role" "atendente". Caso contrário, o acesso a esse subfluxo deverá ser negado.

  2. Criar uma configuração de Password Policies que possa ser validada pelo Fluxo "Alterar senha".

  3. Criar um Authenticator específico que validará as Password Policies configuradas e retornará, para o Robô, se o usuário é válido (ou não) conforme as políticas de senha configuradas.