Uso de autenticação OAuth com seu aplicativo

Caminho rápido: Central de administração > Aplicativos e integrações > APIs > API do Zendesk

Você pode usar o OAuth 2 para autenticar todos as solicitações de API do seu aplicativo para o Zendesk. O OAuth proporciona uma maneira segura para seu aplicativo acessar os dados do Zendesk sem ter que armazenar e usar senhas de usuários do Zendesk, que são informações confidenciais.

Para usar a autenticação OAuth, você precisa registrar seu aplicativo no Zendesk. Também é necessário adicionar alguns recursos ao seu aplicativo para dar suporte ao fluxo de autorização OAuth.

Os tópicos abordados neste artigo são:

• Registro de seu aplicativo no Zendesk
• Implementação de um fluxo de autorização OAuth em seu aplicativo

Tópicos relacionados:

• Para aprender a criar um aplicativo da web que implemente um fluxo de autorização OAuth, consulte o artigo sobre Criação de um aplicativo da web OAuth.
• Para implementar o fluxo de autorização OAuth em aplicativos do Zendesk, consulte Adição de OAuth de terceiros a um aplicativo do Support.
• Se você não precisa que usuários concedam acesso às contas deles para o seu aplicativo, você tem a opção de usar tokens de OAuth para autenticar as solicitações da API. Consulte Criação e uso de tokens de OAuth com a API.

Registro de seu aplicativo no Zendesk

Você deve registrar seu aplicativo para gerar credenciais OAuth que ele pode usar para autenticar chamadas da API para o Zendesk.

Observação: esta seção descreve como configurar um cliente de OAuth para usuários de uma conta do Zendesk. Se seu aplicativo interagirá com várias contas do Zendesk, você pode solicitar um cliente de OAuth global. Um cliente de OAuth global é uma maneira segura e mais clara de realizar autenticações da API com várias instâncias do Zendesk. Para obter informações, consulte Configuração do cliente OAuth global.

Como registrar seu aplicativo

1. Na Central de administração, clique no ícone Aplicativos e integrações () na barra lateral e selecione APIs > API do Zendesk.
2. Clique na aba Clientes OAuth na página de API do Zendesk e em Adicionar cliente OAuth no canto superior direito da lista de clientes de OAuth.
3. Preencha os campos a seguir para criar um cliente:
   • Nome do cliente - insira um nome para seu aplicativo. Esse é o nome que os usuários verão quando seu aplicativo solicitar permissão de acesso e quando eles verificarem a lista de aplicativos de terceiros que têm acesso ao Zendesk deles.
   • Descrição - opcional. Essa é uma descrição breve do seu aplicativo que os usuários verão quando for solicitada a permissão de acesso.
   • Empresa - opcional. Esse é o nome da empresa que os usuários verão quando for solicitada a permissão de acesso ao seu aplicativo. Essas informações podem ajudá-los a entender para quem estão concedendo o acesso.
   • Logotipo - opcional. Esse é o logotipo que os usuários verão quando seu aplicativo solicitar permissão de acesso. A imagem pode ser um JPG, GIF ou PNG. Para obter os melhores resultados, carregue uma imagem quadrada. Ela será redimensionada para a página de autorização.
   • Identificador único - o campo é preenchido automaticamente com uma versão reformatada do nome que você inseriu para seu aplicativo. Você pode alterá-lo, se desejar.
   • URLs de redirecionamento - insira a URL ou as URLs que o Zendesk deverá usar para enviar a decisão do usuário de permitir acesso ao seu aplicativo. As URLs devem ser absolutas e não relativas, https (a menos que sejam localhost ou 127.0.0.1) e separadas por linhas.
4. Clique em Salvar.

   Após a página atualizar um novo campo Segredo já-preenchido será exibido no canto inferior direito. Esse é o valor de "client_secret" especificado em Especificações do OAuth2.

5. Copie o valor do Segredo para a área de transferência e salve-o em um lugar seguro. Observação: os caracteres podem ir além da largura da caixa de texto, então certifique-se de selecionar tudo antes de copiar.
   Importante: por motivos de segurança, seu segredo é exibido por completo apenas uma vez. Após clicar em Salvar, você terá acesso apenas aos primeiros nove caracteres.
6. Clique em Salvar.

Use o identificador exclusivo e o valor do segredo em seu aplicativo como descrito no tópico a seguir.

Implementação de um fluxo de autorização OAuth em seu aplicativo

O Zendesk oferece suporte a diversos tipos de concessão de OAuth. Este artigo descreve o tipo de concessão de código de autorização em detalhes. Outro fluxo, o tipo de concessão implícita, é semelhante ao primeiro, mas não usa um código de autorização. A terceira opção, o tipo de concessão de senha, é um tipo de concessão do lado do servidor que não exige interação com os usuários finais.

• Fluxo de concessão de código de autorização
• Fluxo de concessão implícita
• Tipo de concessão de senha

Fluxo de concessão de código de autorização

Esse fluxo é chamado de fluxo de concessão de código de autorização porque é preciso obter um código de autorização antes de solicitar um token de acesso.

O fluxo não usa atualização de tokens. O token de acesso não expira.

Para implementar o fluxo de concessão de código de autorização, você precisa adicionar as seguintes funcionalidades ao seu aplicativo:

• Etapa 1 - Encaminhar o usuário para a página de autorização do Zendesk
• Etapa 2 - Gerenciar a decisão sobre autorização do usuário
• Etapa 3 - Obter um token de acesso do Zendesk
• Etapa 4 - Usar o token de acesso em chamadas à API

Para aprender a criar um aplicativo da web que implemente um fluxo de autorização OAuth, consulte o artigo sobre Criação de um aplicativo da web OAuth.

Etapa 1 - Encaminhar o usuário para a página de autorização do Zendesk

Em primeiro lugar, seu aplicativo deve encaminhar o usuário para a página de autorização do Zendesk. A página solicita que o usuário autorize seu aplicativo a acessar o Zendesk por ele. Depois que o usuário fizer sua escolha, o Zendesk enviará a opção e algumas outras informações ao seu aplicativo.

Como encaminhar o usuário para a página de autorização do Zendesk

Adicione um link ou um botão em seu aplicativo que encaminhe o usuário para a seguinte URL:

https://{subdomain}.zendesk.com/oauth/authorizations/new

Onde {subdomain} é o seu subdomínio do Zendesk. Você pode usar uma solicitação POST ou GET. Inclua os seguintes parâmetros:

• response_type - obrigatório. O Zendesk retorna um código de autorização em resposta, por isso especifique code como o tipo de resposta. Exemplo: response_type=code.
• redirect_uri - obrigatório. A URL que o Zendesk deve usar para enviar a decisão do usuário para permitir o acesso ao aplicativo. A URL deve ser absoluta e não relativa. Ela também deve ser segura (https), a menos que você esteja usando localhost ou 127.0.0.1.
• client_id - obrigatório. O identificador exclusivo que você obteve quando registrou seu aplicativo no Zendesk. Consulte a seção anterior.
• scope - obrigatório. Uma lista de escopos separados por espaços que controla o acesso aos recursos do Zendesk. Você pode solicitar acesso de leitura, gravação ou representação de todos os recursos ou de recursos específicos. Consulte Configuração do escopo.
• state - cadeia de caracteres arbitrária incluída na resposta do Zendesk depois que o usuário decide se deseja ou não conceder acesso. Você pode usar o parâmetro para se proteger contra ataques de falsificação de solicitações entre sites (CSRF). Em um ataque de CSRF, o usuário final é enganado para clicar em um link que realiza uma ação em um aplicativo web no qual o usuário final ainda está autenticado. Para se proteger contra esse tipo de ataque, adicione um valor ao parâmetro state e valide-o quando ele retornar.

Lembre-se de utilizar codificação URL nos parâmetros.

Exemplo de solicitação GET

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

A página de autorização do Zendesk é aberta no navegador do usuário final. Depois que o usuário tomar uma decisão, o Zendesk enviará a decisão para a URL de redirecionamento especificada na solicitação.

Configuração do escopo

Você precisa especificar um escopo para controlar o acesso do aplicativo aos recursos do Zendesk. O escopo read dá a um aplicativo acesso a pontos de extremidade GET. Ele inclui permissão para transferência local de recursos relacionados. O escopo write dá a um aplicativo acesso a pontos de extremidade POST, PUT e DELETE para criar, atualizar e apagar recursos.

Para obter mais informações sobre o escopo, consulte Tokens de OAuth para tipos de concessão.

O escopo impersonate permite que o administrador do Zendesk faça solicitações em nome de usuários finais. Consulte Solicitações da API em nome de usuários finais.

Por exemplo, o parâmetro a seguir dá a um aplicativo acesso de leitura a todos os recursos:

"scope": "read"

O parâmetro a seguir dá acesso de leitura e gravação a todos os recursos:

"scope": "read write"

Você pode ajustar o escopo aos seguintes recursos:

• tickets
• users
• auditlogs (somente leitura)
• organizations
• hc
• apps
• triggers
• automations
• targets
• webhooks
• zis

A sintaxe é a seguinte:

"scope": "resource:scope"

Por exemplo, o parâmetro a seguir restringe um aplicativo para somente leitura de tickets:

"scope": "tickets:read"

Para dar a um aplicativo acesso de leitura e escrita a um recurso, especifique os dois escopos:

"scope": "users:read users:write"

Para dar a um aplicativo acesso de gravação apenas a um recurso, como organizações, e acesso de leitura a todo o resto:

"scope": "organizations:write read"

Etapa 2 - Gerenciar a decisão sobre autorização do usuário

Seu aplicativo deve gerenciar a resposta do Zendesk que informa a decisão do usuário. A informação é contida em parâmetros de URL na URL de redirecionamento.

Se o usuário decidir autorizar o acesso ao aplicativo, a URL de redirecionamento conterá um código de autorização. Exemplo:

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

O código de autorização é válido apenas por 120 segundos.

Se o usuário decidir não conceder acesso ao aplicativo, a URL de redirecionamento conterá os parâmetros error e error_description que informam ao aplicativo que o usuário negou o acesso:

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Use esses valores para controlar o fluxo de seu aplicativo. Se a URL contiver o parâmetro code, obtenha um token de acesso do Zendesk conforme descrito na próxima seção. Esse é o token que será incluído nas chamadas da API ao Zendesk.

Etapa 3 - Obter um token de acesso do Zendesk

Se o seu aplicativo receber um código de autorização do Zendesk como resposta à concessão de acesso pelo usuário, seu aplicativo poderá trocá-lo por um token de acesso. Para obter o token de acesso, faça uma solicitação POST para o seguinte ponto de extremidade:

https://{subdomain}.zendesk.com/oauth/tokens

Observação: não confunda esse ponto de extremidade com o ponto de extremidade Create Token na API de tokens de OAuth. Embora ambos os pontos de extremidade retornem tokens de acesso OAuth válidos, os pontos de extremidade não compartilham o mesmo caminho, formato JSON ou parâmetros de solicitação.

Inclua os seguintes parâmetros obrigatórios na solicitação:

• grant_type - especifique “authorization_code” como valor.
• code - use o código de autorização que você recebeu do Zendesk depois que o usuário concedeu o acesso.
• client_id - use este identificador exclusivo especificado em um cliente de OAuth na interface do administrador do Support (Admin. > Canais > API > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.
• client_secret - use este segredo especificado em um cliente de OAuth na interface do administrador do Support (Admin. > Canais > API > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.
• redirect_uri - a mesma URL de redirecionamento da etapa 1. Apenas para fins de ID.
• scope - consulte Configuração do escopo.

A solicitação deve ser por meio de https e os parâmetros devem ser formatados como JSON.

Usando curl

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

Exemplo de resposta

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

Etapa 4 - Usar o token de acesso em chamadas à API

O aplicativo pode usar o token de acesso para realizar chamadas de API. Inclua o token em um cabeçalho de autorização HTTP com a solicitação conforme a seguinte:

Authorization: Bearer {a_valid_access_token}

Por exemplo, uma solicitação curl para listar os tickets teria a seguinte aparência:

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

Fluxo de concessão implícita

O fluxo de concessão implícita é semelhante ao fluxo de concessão do código de autorização, porém sem a etapa 3. Você solicita um token em vez de um código de autorização. Em outras palavras, você define o valor do parâmetro response_type como "token" em vez de "code". Se o usuário final autorizar o acesso, o token será enviado imediatamente para a URL de redirecionamento. Não existem pontos de extremidade para criar um token ou configurar o seu escopo. O token concede acesso de leitura e gravação para todos os recursos.

Exemplo de solicitação

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=token&client_id={your_unique_identifier}&scope=read%20write   

Exemplo de respostas

Se o usuário autorizar o acesso ao aplicativo, o token será incluído na URL de redirecionamento.

{redirect_url}#access_token=gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo&token_type=bearer

Se o usuário decidir não autorizar o acesso ao aplicativo, a URL conterá os parâmetros error e error_description.

{redirect_url}#error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Tipo de concessão de senha

Use o tipo de concessão de senha para trocar um nome de usuário e uma senha do Zendesk para um token de acesso diretamente. Esse tipo de concessão deve ser usado somente se seu aplicativo puder obter os nomes de usuário e as senhas do Zendesk. Esses geralmente são aplicativos com privilégios altos no Zendesk. O aplicativo nunca deve armazenar os nomes de usuário e as senhas. A maneira como ele obtém essas informações também deve ser extremamente segura.

Exemplo de solicitação

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "password", "client_id": "{your_client_id}", 
    "client_secret": "{your_client_secret}", "scope": "read",
    "username": "{zendesk_username}", "password": "{zendesk_password}"}' \
  -X POST

Um nome de usuário do Zendesk geralmente é um endereço de e-mail, como [e-mail].

Exemplo de resposta

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}