Se você está testando ou criando um aplicativo interno, talvez não queira que suas solicitações de API sejam associadas a um usuário específico, como é o caso da autenticação básica, que requer um nome de usuário e uma senha, ou à autenticação do token de API, que ainda requer um nome de usuário. A terceira opção é o uso do token de acesso OAuth.

Num primeiro momento, a criação de um token de OAuth, junto com seu fluxo de autorização elaborado, pode parecer uma tarefa desafiadora. No entanto, é possível ignorar as partes mais complicadas do processo e obter um token de acesso diretamente da API. Este artigo descreve como criar seu próprio token de OAuth para fins de teste em poucas etapas.

Importante: a técnica descrita neste artigo consiste basicamente na troca de um nome de usuário e senha do Zendesk por um token de acesso. Como resultado, o token tem as mesmas vulnerabilidades de segurança de uma senha. Qualquer pessoa que tiver o token poderá acessar a conta. Guarde o token num local seguro e não faça uma codificação rígida dele no código do aplicativo. Em vez disso, armazene-o em uma variável de ambiente.

Criação do cliente OAuth

A primeira etapa é criar um cliente OAuth para fins de teste.

  1. Na Central de administração, clique no ícone Aplicativos e integrações () na barra lateral e selecione APIs > APIs do Zendesk.
  2. Na aba Clientes OAuth, clique em Adicionar cliente OAuth no canto superior direito da lista.

A configuração do cliente para fins de teste é um pouco diferente da criação de um cliente OAuth normal. Observe as diferenças a seguir:

  • O seu redirecionamento precisa ser uma URL HTTPS válida, mas não precisa ser um website real para esse projeto. Exemplo: https://algumsite.com.
  • O identificador exclusivo é o nome do seu cliente, usado no código. É possível obter a ID do cliente com o ponto de extremidade List Clients da API do cliente OAuth.
  • Você talvez queira copiar seu segredo para referência futura. Depois de criado, ele não será exibido novamente, mas será necessário se você pretende usá-lo para criar um aplicativo da web OAuth ou para outros projetos.
  • Todos os outros campos podem ser preenchidos com dados fictícios.

Criação de um token de acesso

Agora você tem tudo de que precisa para criar um token com a API de tokens de OAuth. Confira como fazer a solicitação com cURL:

 curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
   -H "Content-Type: application/json" \
   -d '{"token": {"client_id": "your_client_id", "scopes": ["read", "write"]}}' \
   -X POST -v -u {email_address}:{password}

É importante ressaltarmos algumas observações sobre este código:

  • Lembre-se de substituir o placeholder de subdomínio com seu próprio subdomínio
  • O valor de "client_id" é o número que você copiou da página Clientes de OAuth
  • Defina os escopos para ["read", "write"] a menos que você esteja testando em específico o acesso de somente leitura de um recurso
  • Se a sua organização usa single sign-on (SSO) e as senhas do Zendesk foram apagadas da conta do Zendesk, você terá de usar um token da API para autenticar a solicitação: -u {email_address}/token:{api_token}. Consulte API token (Token da API) nos documentos da Support API.

Execute a solicitação da cURL. Ela retorna um arquivo package.JSON composto por um objeto de token com diversas propriedades:

O valor de "full_token" corresponde ao seu token de acesso. Copie e guarde-o num local seguro!

Observe que a propriedade "expires_at" da resposta é "null", o que significa que o token somente irá parar de funcionar quando você apagar o próprio cliente. Na próxima vez que visitar a lista de clientes OAuth na Central de administração, o número de tokens ativos para o seu novo cliente terá aumentado para 1.

Uso do seu novo token de acesso

Qual é a utilidade de ter um token de acesso se você não tem no que usá-lo? Nenhum dos exemplos a seguir usa um nome de usuário ou senha. Esse é o padrão! Um token de acesso OAuth não depende de uma conta de usuário, essa é uma das vantagens para usar um token em seus aplicativos e scripts.

Uso de um token de acesso para a autenticação de uma solicitação de API

Qualquer chamada da API que requerer autenticação poderá ser feita com um token de acesso OAuth. Por exemplo, uma chamada para o ponto de extremidade dos tickets normalmente tem esta aparência:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
   -u {email_address}:{password}

Com o token de acesso, tem esta:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer {access_token}"

Uso de um token de acesso num cliente de API

Você também pode usar um token de acesso OAuth em qualquer um de nossos clientes de API. O cliente Ruby, por exemplo, normalmente requer autenticação com um nome de usuário e uma senha (ou token da API) como:

  config.username = "user email"
  config.password = "user password"

Veja como fica a aparência se você usar o token de acesso:

 config.access_token = "your OAuth access token"

 

Powered by Zendesk