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.
Como registrar seu aplicativo
- Na Central de administração, clique em
Aplicativos e integrações na barra lateral e selecione APIs > API do Zendesk. - 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.
- 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.
- Tipo de cliente – Público ou Confidencial. Os clientes OAuth públicos são aplicativos executados em ambientes nos quais as credenciais não podem ser armazenadas com segurança, como aplicativos para dispositivos móveis ou web. Esses clientes são obrigados a usar PKCE. Os clientes OAuth confidenciais são executados em servidores seguros, onde as credenciais podem ser mantidas em segurança. Esses clientes podem usar PKCE, segredo do cliente ou ambos. Consulte Tipos de cliente OAuth.
- 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.
- 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.
- 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.
- Clique em Salvar.
Use o identificador exclusivo e o valor do segredo em seu aplicativo como descrito no tópico a seguir.
Tipos de cliente OAuth
Os clientes OAuth do Zendesk incluem uma propriedade kind que é passada durante a criação do cliente OAuth e podem ter um dos seguintes valores:
- Público: Os clientes OAuth públicos são aplicativos executados em ambientes nos quais as credenciais não podem ser armazenadas com segurança, como aplicativos para dispositivos móveis ou web. Esses clientes são obrigados a usar PKCE.
- Confidencial: Os clientes OAuth confidenciais são executados em servidores seguros, onde as credenciais podem ser mantidas em segurança. Esses clientes podem usar PKCE, segredo do cliente ou ambos.
Para obter mais informações, consulte Tipos de cliente.
O tipo de cliente OAuth do Zendesk aplica-se somente ao sistema de tickets do Zendesk Support. Não há suporte no Chat, nas conversas nem no Sell.
No momento, clientes OAuth do Zendesk existentes têm a propriedade kind definida como unknown. Esses clientes permanecem não afetados até que a propriedade kind seja atualizada para public ou confidential. Novos clientes OAuth criados na Central de administração precisam definir a propriedade kind durante a criação.
kind para public, antes precisa implementar o PKCE. Se não fizer isso, o cliente não funcionará, pois o PKCE será exigido imediatamente.É obrigatório definir a propriedade kind para todos os novos clientes OAuth criados na Central de administração. Embora a propriedade kind não seja obrigatória para clientes OAuth criados com o ponto de extremidade api/v2/oauth/clients endpoint, a Zendesk recomenda sua inclusão.
Implementação de um fluxo de autorização OAuth em seu aplicativo
O Zendesk oferece suporte ao fluxo de concessão de código de autorização para obter tokens de acesso. 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. Outros fluxos de concessão foram descontinuados.
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.
O método de concessão do código de autorização tem suporte para Proof Key for Code Exchange (PKCE), que adiciona uma camada a mais de segurança. Para obter mais informações, consulte Using PKCE to make Zendesk OAuth access tokens more secure (Uso do PKCE para tonar os tokens de acesso do Zendesk OAuth mais seguros) na documentação do desenvolvedor.
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/newem que {subdomain} é o seu subdomínio principal do Zendesk, não um subdomínio com mapeamento do host.
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
codecomo 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. 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
statee valide-o quando ele retornar. - code_challenge - obrigatório se estiver usando o PKCE. Uma cadeia de caracteres representando um desafio de código derivado de um verificador de código. Consulte Generating the code_challenge value (Geração do valor de code_challenge) na documentação do desenvolvedor.
- code_challenge_method - obrigatório se estiver usando o PKCE. O método usado para derivar o desafio de código. Especifique "S256" como o valor.
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%20writeA 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=7xqwtlf3rrdj8uyeb1yfO 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+requestUse 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/tokensInclua 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 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 OAuth na interface do administrador do Support (Admin. > Canais > API > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.
Se você usa os parâmetros
code_challengeecode_verifierdo PKCE, oclient_secretnão é obrigatório. Você pode usar essa característica para migrar do fluxo de concessão implícita, que não é mais recomendado devido a questões de segurança. Consulte Using PKCE to migrate from the implicit grant flow (Uso do PKCE para migrar do fluxo de concessão implícita) na documentação do desenvolvedor. - redirect_uri - a mesma URL de redirecionamento da etapa 1. Apenas para fins de ID.
- scope - consulte Configuração do escopo.
-
code_verifier - obrigatório se estiver usando o PKCE. A cadeia de caracteres usada para gerar o valor de
code_challenge. Consulte Generating the code_challenge value (Geração do valor de code_challenge) na documentação do desenvolvedor.
A solicitação deve ser por meio de https e as propriedades devem ser formatados como JSON. Se você usar um aplicativo personalizado de terceiros para fazer a solicitação de API, consulte a documentação para saber o formato adequado dos valores de propriedades.
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 POSTExemplo 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"