Uso de autenticação OAuth com seu aplicativo

Qual é o meu plano?

Suite

Team, Growth, Professional, Enterprise ou Enterprise Plus

Support

Team, Professional ou Enterprise

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
• Tipos de cliente OAuth
• Tipo de concessão de credenciais do cliente OAuth
• 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 em 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.
   • 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.
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.

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.

Observação: se você está usando um cliente OAuth do Zendesk existente e planeja alterar a propriedade 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.

Tipo de concessão de credenciais do cliente OAuth

atualmente, os tokens gerados pelo tipo de concessão de credenciais do cliente só podem ser usados ​​para pontos de extremidade que permitem usuários anônimos. Qualquer ponto de extremidade que exija uma função, como administrador ou agente, não funcionará com esses tokens. No futuro, esses tokens poderão ser usados ​​para pontos de extremidade que exigem uma função.

O tipo de concessão de credenciais de cliente OAuth é somente para clientes confidenciais e permite que você crie um token OAuth usando apenas o segredo de um cliente específico. Para usar esse fluxo, informe um parâmetro client_secret válido para o ponto de extremidade /oauth/tokens usando grant_type: client_credentials para gerar um novo token de acesso OAuth. Diferentemente de outros fluxos de autorização, esse tipo de concessão não retorna um token de atualização e não requer autorização do usuário. Por questões de segurança, clientes públicos não estão autorizados a usar esse tipo de concessão. Para obter mais informações, consulte

Tipo de concessão de token de atualização OAuth

Com o tipo de concessão de token de atualização OAuth é possível atualizar um token de acesso que expirou ou está prestes a expirar. Para gerar um novo token de acesso OAuth, passe um parâmetro refresh_token para o ponto de extremidade https://{subdomain}.zendesk.com/oauth/tokens usando grant_type: refresh_token, que retorna um novo token de acesso e um token de atualização, invalidando os anteriores.

Seu cliente OAuth deve implementar um mecanismo de fallback para lidar com tokens de acesso e de atualização expirados. Por exemplo, se o token de acesso expirou ou encontrou um erro, você pode atualizá-lo. No entanto, se o processo de atualização falhar ou não houver um token de atualização vinculado ao token de acesso, você deverá redirecionar o usuário para https://{subdomain}.zendesk.com/oauth/authorizations/new para autorizar novamente seu aplicativo. Para obter mais informações, consulte OAuth Tokens for Grant Types e Creating and using OAuth access tokens with the API.

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.

O fluxo usa tokens de atualização, o que permite gerar novos tokens de acesso sem exigir outra autorização do usuário. O token de acesso pode expirar se a API fornecer um parâmetro expires_in válido, indicando uma vida útil específica para o token. Nesses casos, implemente um mecanismo para atualizar o token de acesso usando o token de atualização fornecido antes que ele expire.

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/new

em 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 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. 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.
• 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%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 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_challenge e code_verifier do PKCE, o client_secret nã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.
• expires_in - opcional. Tempo em segundos de validade do token de acesso. Consulte OAuth Tokens for Grant Types.
• refresh_token_expires_in - opcional. Tempo em segundos de validade do token de atualização. Consulte OAuth Tokens for Grant Types.

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 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"