Processo de autenticação v0.6

SDK do Diretório de Aplicativos

Processo de autenticação (v0.6, obsoleta)

A maioria dos aplicativos procura fornecer conteúdo específico ao usuário e recursos de interação. Antes de implementar a autenticação, seu aplicativo não reconhecerá o usuário da Hootsuite que o está utilizando. Esta página descreve técnicas para autenticar um usuário da Hootsuite em seu aplicativo.

Note que essas técnicas NÃO proporcionam métodos para autenticação com provedores de serviços externos. É sua responsabilidade configurar a autenticação com um provedor externo, usando o método que ele oferece.

Para escolher o tipo de autenticação que melhor atende às suas necessidades, considere estas características:

  • Login Único informa a ID do usuário para que um fluxo de aplicativo saiba qual usuário da Hootsuite o está visualizando. Um valor hash (token de segurança) é usado para evitar a falsificação dessa ID de usuário, autenticando a solicitação.
  • O OAuth age como o Login Único. Porém, em vez de passar uma ID de usuário e um valor hash, ele passa uma ID de sessão (token de sessão) que foi anteriormente negociado entre a Hootsuite e seu aplicativo. Além disso, durante a instalação de seu aplicativo, o usuário precisa acessar a conta existente em sua própria base de usuários, e você terá que armazenar a ID da conta desse usuário (para correspondê-la ao token de sessão ao visualizar os fluxos). A ID de conta inserida é, portanto, associada à instalação de seu aplicativo.

Consequentemente, o OAuth é útil para conectar um usuário de sua própria base de usuários ao seu aplicativo. Porém, o usuário precisa instalar seu aplicativo várias vezes se quiser se conectar a várias contas. Digamos que essa é uma característica por aplicativo.

Obviamente, você também pode permitir que o usuário acesse qualquer conta de usuário e você mesmo o associa manualmente a seu aplicativo usando a autenticação por Login Único. Acessar uma conta de usuário dessa maneira fica inteiramente a seu critério. Você pode oferecer acesso a contas de sua própria base de usuários ou implementar a autenticação com um provedor de serviços externo (usando o método de autenticação que ele oferece). Independente da opção escolhida, elas serão chamadas de contas de terceiros neste documento para facilitar a compreensão. Lembre-se do seguinte: se você quiser associar uma conta de terceiros a seu aplicativo pelo método por aplicativo, como na característica do OAuth descrita acima, podem ocorrer problemas porque o usuário pode adicionar fluxos de seu aplicativo várias vezes e, assim, você não conseguirá refletir o estado de autenticação atual em todos os fluxos depois que o usuário concluir a autenticação/desautenticação da conta de terceiros em um dos fluxos. Portanto, em termos gerais, é aconselhável associar uma conta de terceiros a um único fluxo. Digamos que essa é uma característica por fluxo.

Esse tipo de autenticação de conta de terceiros por fluxo também oferece ao usuário a vantagem de poder se conectar a várias contas simultaneamente, cada qual em seu próprio fluxo, sem necessidade de instalar seu aplicativo várias vezes.

Um dos parâmetros de URL passados para os fluxos é a ID de localização do fluxo, o pid. Exclusivo de cada fluxo que o usuário adicionou, isso é útil na implementação da autenticação por fluxo de uma conta de terceiros.

Login Único

Um identificador do usuário, um carimbo de data/hora e uma chave secreta (salt) compartilhada pela Hootsuite e o desenvolvedor são criptografados com o algoritmo SHA-1 e passados para o aplicativo. O hash de verificação pode ser recalculado pelo desenvolvedor e comparado com o que foi passado. Se coincidirem, o usuário associado ao identificador pode ser conectado.

Com esse método, ninguém pode falsificar um hash de verificação se não souber qual é a chave secreta compartilhada. Contudo, esse método é vulnerável a ataques de repetição (replay) se o invasor conseguir interceptar tráfego da rede não criptografado e visualizar a string de consulta. Para que isso seja atenuado, é preciso usar https e verificar se o carimbo de data/hora é recente.

Por padrão, o identificador de usuário fornecido é um identificador exclusivo associado à conta da Hootsuite do usuário. Uma alternativa é permitir que o usuário insira um identificador (endereço de e-mail, nome de usuário, etc) a ser passado para seu aplicativo. Essa alternativa, entretanto, só deve ser usada se os dados exibidos por seu aplicativo forem de natureza pública, já que qualquer usuário poderia inserir o endereço de e-mail de outro.

Exemplo de URL:

https://app.somewhere.com?i=1667985&ts=1310681657&token=231a3fb74139c74c37e9111ceb59ce02a349ef88

O aplicativo valida esses parâmetros da seguinte maneira:

$secret = 'sharedSecretABCD1234'; // defined in App configuration at hootsuite.com/developers
$user_id   = $_REQUEST['i'];
$timestamp = $_REQUEST['ts'];
$token     = $_REQUEST['token'];
if (sha1($user_id . $timestamp . $secret) == $token)
{
    echo "Logon bem-sucedido!";
}

Parâmetros de URL passados para o iframe do fluxo de aplicativo:

lang=en
timezone=7200
pid=2823         // placement ID, unique for each stream per user
uid=1234567      // Hootsuite user ID
i=1234567        // user identifier (optionally entered by user upon App installation)
ts=1318362023    // timestamp
token=123abc...  // security token (sha1 hash)

OAuth

Configurar a autenticação do OAuth requer um conhecimento abrangente da arquitetura do OAuth, pois é preciso implementar o endpoint de um "provedor de serviços" segundo as especificações do OAuth, como indica o fluxograma abaixo. Embora esse procedimento seja mais demorado que uma autenticação por Login Único, os principais benefícios são maior segurança e uma experiência de usuário mais simples, porque o usuário acessa seu aplicativo quando o instala.

A Hootsuite usa uma implementação padrão do OAuth, com um etapa extra em que a Hootsuite recupera uma ID de sessão no endpoint de autenticação do aplicativo (usando uma busca autenticada pelo OAuth). Você precisará implementar esse endpoint de autenticação além do "provedor de serviços" do OAuth.

O fluxograma abaixo indica o procedimento de autenticação, começando com o processo padrão do OAuth que é acionado quando o usuário instala o aplicativo até a validação do token de acesso pelo endpoint de autenticação, finalizando com o acesso do usuário ao aplicativo.

hsOauth.45b015e3

Endpoint de autenticação

Quando o fluxo de aplicativo é aberto pela primeira vez, nenhum token de sessão é passado porque ainda não há um arquivado na Hootsuite. Nesse momento, o aplicativo deve chamar hsp.startAppTokenAuth() para que a Hootsuite solicite um token de sessão ao endpoint de autenticação do aplicativo. Depois que a Hootsuite recebe o token, ela recarrega o fluxo de aplicativo, agora passando o token, que, por sua vez, é validado pelo aplicativo. Se for igual ao fornecido pelo endpoint de autenticação, pode-se considerar o usuário autenticado.

Outra alternativa para esse processo é a etapa de troca de token usar o OAuth para que o usuário tenha acesso ao site. Você gera uma ID de sessão, como faria para qualquer outra ação de logon do usuário; porém, você passa a ID à Hootsuite, que poderá enviá-la quando o aplicativo for carregado para identificar o usuário conectado.

Explicando melhor:

  • O usuário da Hootsuite carrega o fluxo de aplicativo. O aplicativo é carregado do servidor do provedor de aplicativo e nenhuma credencial de autenticação é transmitida.
  • O aplicativo detecta que não existe uma sessão do usuário e que nenhuma credencial de autenticação foi passada. Ele exibe uma mensagem do tipo "Acessando" e faz a chamada hsp.startAppTokenAuth() de javascript que iniciará uma troca de token de sessão.
  • É feita uma solicitação no backend dos servidores da Hootsuite para o endpoint de autenticação do aplicativo, que verifica os tokens do OAuth e retorna uma ID de sessão.
  • O iframe do aplicativo é recarregado, que passa, então, a ID de sessão. O aplicativo valida a ID de sessão e a utiliza para iniciar uma sessão de usuário.

A Hootsuite continuará passando o token de sessão que tem arquivado toda vez que um fluxo de aplicativo for carregado. Cabe ao desenvolvedor decidir o tempo de validade do token de sessão. Se seu aplicativo considerar que uma sessão está prestes a expirar ou está, de alguma outra forma, inválida, será preciso chamar hsp.startAppTokenAuth() novamente para acionar a criação de um novo token de sessão.

Validação de token de acesso

O endpoint de autenticação do aplicativo deve validar um token de acesso segundo as especificações do OAuth e retornar uma string com codificação JSON contendo 'session_token':

echo json_encode(array('result'=>'success', 'session_token'=>'abcd1234'));

{"result":"success","session_token":"abcd1234"}

Ou se o token não puder ser validado:

{"result":"fail","reason":"Some error message"}

Se as credenciais transmitidas para o endpoint de autenticação forem inválidas, o aplicativo poderá instruir a Hootsuite a abrir a janela de diálogo "editar aplicativo" do usuário usando a chamada da função hsp.editAppAuth(), que possibilita ao usuário da Hootsuite inserir novas credenciais ou reiniciar o processo do OAuth.

Para obter uma lista de links para implementações do OAuth em vários idiomas (muitos com código que pode ser usado para criar um provedor de OAuth), consulte http://oauth.net/code/