Integração com SSO (Single Sign-On)

O que é Single Sign-on ? 

Single Sign On (SSO) é um mecanismo pelo qual torna-se possível que um usuário obtenha acesso a múltiplos serviços após autenticar-se somente uma vez em qualquer um destes serviços. 

Usando o recurso SSO portal

Neste momento o Tolvdesk implementa apenas a autenticação para acesso SSO ao portal (para seus clientes). Para utilizar o SSO para acesso dos seus agentes, entre em contato com nosso suporte via chat ou via e-mail: suporte@tolv12.com. 

Para utilizar o recurso de single sign on e integrar suas aplicações com o Tolvdesk, siga os passos abaixo.  

Criando um Token Privado para SSO portal

Acesse o sistema de Help desk com a senha de administrador e vá no menu administrador, em Avançado clique em SSO portal.



Na tela de configuração do SSO portal, clique no botão Novo. No campo "Permitir requisições apenas deste IP" você deve informar o IP público do servidor de sua aplicação. Caso não seja informado, serão permitidas requisições de qualquer origem. 



Clique em Continuar para gerar o Token privado, que será utilizado para você criar os tokens de sessão. 

Após, clique em editar e irá aparecer a seguinte tela:



Atenção: o token privado não deve nunca ser exposto para seu usuário. Todas as operações feitas com o Token privado devem ocorrer no backend da sua aplicação (no servidor) e jamais no frontend. 

Token de sessão

Com o Token privado você poderá gerar tokens de sessão. Estes tokens de sessão permitirão que você redirecione seu cliente ao seu portal, de forma que ele já entre autenticado. 

Criando Tokens de sessão

Em uma requisição síncrona, faça uma requisição HTTP/GET no endereço http://api.tolvdesk.com/v1/sso passando por parâmetro o e-mail do cliente (aquele você cadastrou no Tolvdesk). Nesta mesma requisição você deve incluir um header com nome Authorization e valor:  'JWT ' + Token privado que você criou:
OBS: Caso o e-mail passado na requisição HTTP/GET, não esteja cadastrado como um contato, este e-mail será cadastrado como um contato, aonde o que estiver antes do @, será o nome do contato.

 como no exemplo abaixo:
Authorization: JWT [token] 

Exemplo:  
GET 
http://api.tolvdesk.com/v1/sso?email=seucliente@empresa.com.br 

Retorno: 
error: [eventuais erros na requisição], 
accessToken: "[TOKEN DE SESSÃO]"

Opcional: Você pode cadastrar o contato, vinculando-o a uma empresa previamente cadastrada no sistema, usando duas opções:

1 - Domínio da empresa: tendo uma empresa previamente cadastrada e com o domínio informado em seu cadastro, a API SSO ao receber o e-mail do contato, identificará o domínio que encontra-se depois de "@" e vinculará o contato à empresa que tenha este mesmo domínio em seu cadastro.

2 - Identificação: no cadastro da empresa, existe um campo chamado "Identificação". Adicione ao final da requisição, o seguinte valor sem as aspas:
"&identificacao_empresa=meu_cliente", onde "meu_cliente" é a identificação da empresa cadastrada no sistema. 

Obs.: Para contatos já cadastrados sem empresa vinculada ou com empresa vinculada, não será efetuada nenhuma alteração. Para alterar este contato e vinculá-lo a uma empresa, utilize a API Rest.

Exemplo:  
GET 
http://api.tolvdesk.com/v1/sso?email=seucliente@empresa.com.br&identificacao_empresa=meu_cliente

Importante: o token de sessão tem validade de 5 minutos. Você deve utilizá-la apenas para direcionar o usuário, pois depois disso, ele ganhará uma nova sessão dentro do portal. 

Códigos de erros possíveis no retorno:

400 - Conteúdo não encontrado 
300 - Erro de validação 
100 - Erro interno da aplicação 

Direcionando a navegação do cliente

O passo seguinte é redirecionar seu cliente para a URL formada conforme abaixo, passando o Token de sessão (accessToken).

http://[seu endereço do portal]/portal/sso/[accessToken] 

Exemplo de utilização do SSO com PHP: 

[EMAIL DO CLIENTE] => Substitua pelo email do seu cliente / contato
[TOKEN_PRIVADO] => Substitua pelo token criado no gerenciador da sua conta
[URL DA CONTA] => Substitua pela URL personalizada da sua conta (empresa.tolvdesk.com ou seu domínio personalizado)


$url = 'http://api.tolvdesk.com/v1/sso?email=[EMAIL DO CLIENTE]';
$token_privado = "JWT [TOKEN_PRIVADO]";

try {

  $ch = curl_init($url);
  curl_setopt($ch,CURLOPT_HTTPHEADER,array("Authorization: $token_privado"));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $retorno = curl_exec($ch);
  curl_close($ch);

} catch(Exception $e) {
  var_dump($e);
  $retorno = false;
}

if($retorno) {
  $json = json_decode($retorno);
  $url_redirecionamento = "http://[URL DA CONTA]/portal/sso/".$json->accessToken;
  echo "Redirecionar para: ".$url_redirecionamento;
} else {
  echo "Erro";
}

Caso você tenha dúvidas sobre o processo ou precise de alguma ajuda, entre em contato com nosso suporte via chat ou via e-mail: suporte@tolv12.com.