Serviç os da Web de distribuição digital (DDWS) Guia de autenticação de API

Transcrição

1 Serviç os da Web de distribuição digital (DDWS) Guia de autenticação de API

2 ÍNDICE Histórico de revisão Autenticação de API com o Autodesk Visão geral Assinatura digital do DDWS e geração de token de acesso Exemplos Chamada ao OAuth para gerar o token de acesso Chamada à API usando o token de acesso Códigos de erro Conectar via Postman Instalação do Postman Como acessar APIs do DDWS com o Postman Geração de um token de acesso Testando o acesso aos serviços de API Gerar cabeçalhos para chamadas ao OAuth e à API do serviço... 16

3 Histórico de revisão Versão Data Autor Comentários /10/2015 AR Seção atualizada URL da solicitação /12/2015 AR Extremidade modificada na seção e de para /03/2016 MG Seção 1.1 atualizada Foi adicionado o formato de assinatura de token Seção 1.2 atualizada Foram adicionados os formatos de assinatura de API e de token Seção atualizada Foram adicionadas as informações de assinatura para obter licença /04/2016 MG Formatação Numeração corrigida de para /04/2016 PL Editado e revisou toda a Seção 2

4 1 Autenticação de API com o Autodesk 1.1 Visão geral A API de autenticação que estamos exibindo serve para proteger os Serviços da Web de distribuição, DDWS, contra acesso indesejável e não autorizado aos nossos serviços de API da Autodesk. Ele verificará a autenticidade de chamada por meio de assinaturas digitais, bem como ajudará a gerenciar o escopo dos recursos da API que cada Parceiro pode chamar por meio do OAuth 2.0 de duas ramificações O serviço de API do DDWS foi projetado para ser autenticado com o mecanismo OAuth 2.0. Todas as solicitações de API devem incluir uma assinatura digital para autenticidade. Um parceiro deve gerar assinaturas por solicitação e incorporadas ao cabeçalho quando usa APIs do DDWS. Com a camada de proxy, a geração de token de acesso envolve a validação dos seguintes parâmetros do Parceiro: 1. Credenciais codificadas de base Registro de data e hora (não anterior a 5 minutos) 3. Assinatura gerada No cabeçalho de Autorização da solicitação de OAuth, estamos esperando o valor codificado de base 64 de uma sequência de caracteres que seja o ID do cliente e o segredo do cliente, separados por dois pontos. O valor da sequência de caracteres codificada será calculada como - client_id client_secret Valor codificado 3PWSS4SfsSTLr2fb1taaQ6JlwMoMabgo mhc90tsif2me2fmf client_id:client_secret 3PWSS4SfsSTLr2fb1taaQ6JlwMoMabgo:mhc90tsIf2me2fMF A sequência de caracteres codificada de base 64 pode ser construída no seguinte formato: Authorization Header = Concatenate( Basic, Base64Encode(Concatenate (client_id, :, client_secret)) O que, por sua vez, deve resultar em um valor codificado de base 64 igual a: M1BXU1M0U2ZzU1RMcjJmYjF0YWFRNkpsd01vTWFiZ286bWhjOTB0c0lmMm1lMmZNRg ==

5 Ao chamar os serviços da API, espera-se que o token de acesso recebido do token de OAuth inicial esteja no cabeçalho de Autorização de cada solicitação como o token de portador. Nota: o token só é válido por 15 minutos. Não será fornecido um token de "atualização"; deve ser feita uma nova chamada para gerar um novo token. 1.2 Assinatura digital do DDWS e geração de token de acesso Começaremos fornecendo as descrições para o seguinte: retorno de chamada: a URL de retorno de chamada enviada ao registrar o aplicativo no portal do desenvolvedor. ID do cliente: obtido do portal do desenvolvedor depois que você registra com sucesso o aplicativo. Sinônimo com chave de cliente. registro de data e hora: precisão de tempo de segundo quando a assinatura é gerada timestamp = current Epoch Time (10 Digits) token de acesso: obtido da resposta da chamada de OAuth para gerar o token A geração de uma assinatura envolve a criptografia HMACSHA256 padrão de base 64 da message_string. Se você estiver chamando o ponto de extremidade do OAuth para gerar um token de acesso, a message_string em questão será uma concatenação dos seguintes valores, na ordem em que eles são apresentados: retorno de chamada + ID do cliente + registro de data e hora signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, client_id, timestamp)) Se você estiver chamando qualquer outro ponto de extremidade do serviço da API como / orders/fulfillment ou /partner/test, a message_string será uma concatenação dos seguintes valores, na ordem em que eles são apresentados: retorno de chamada + token de acesso + registro de data e hora signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, Access_Token from the service(no bearer string here), timestamp))

6 A seguir está um exemplo de script Python para gerar a assinatura para ser usada na chamada a OAuth. Nota: os valores utilizados aqui são fictícios. Você precisará fornecer seu próprio ID de cliente, segredo de cliente, etc. para gerar sua própria assinatura. import re import time import calendar from base64 import b64encode from datetime import timedelta, datetime from hmac import HMAC import sys, os, base64, hashlib, hmac base_path = " timestamp = calendar.timegm(time.gmtime()) client_id = "2LDR5j0yG0PhW23PranLQ6JlwMoMabgo" client_secret = "op30uee2kdei2fmf" signed_signature = base64.b64encode(hmac.new(client_secret, base_path +client_id+ str(timestamp), hashlib.sha256).digest()) print("signed_signature-- >"+signed_signature) print("timestamp-- >"+str(timestamp)) Para as assinaturas necessárias para chamar nossos serviços de API, consulte o script acima e alterne o valor de client_id com o token de acesso recebido da chamada a OAuth.

7 1.3 Exemplos Chamada ao OAuth para gerar o token de acesso Uma solicitação POST é executada para nosso ponto de extremidade, /v2/oauth/ generateaccesstoken com a assinatura, as credenciais codificadas de base 64, e o valor de registro de data e hora localizado no cabeçalho da solicitação. Especifique na consulta que o tipo de concessão serão as credenciais do cliente. Na resposta do JSON, o token de acesso em questão será localizado no campo access_token. Solicitação POST autodesk.com/v2/oauth/generateaccesstoken?grant_type=client_credential s HTTP/1.1 Authorization: Basic MkxEUjVqMHlHMFBoVzIzUHJhbkxRNkpsd01vTWFiZ286b3AzMHVlZTJL== signature: pbfumincypcpqrxenehq6skc+84= timestamp: Resposta HTTP/ OK Content-Type: application/json Content-Length: 523 Connection: keep-alive { "access_token" : "Q0K4S7iVJnuCVYP9ydARATNBJLyn", "expires_in" : 899, "token_type" : "BearerToken" }

8 1.3.2 Chamada à API usando o token de acesso A seguir utilizamos um ponto de extremidade, /v1/partner/test, que os Parceiros podem utilizar para simular uma chamada à API que requer o token de acesso. Chame o ponto de extremidade com o cabeçalho de Autorização, que conterá as informações do token. Também inclua no cabeçalho o número específico do cliente (CSN) recebido na integração, a nova assinatura gerada para chamadas de API e o registro de data e hora utilizado para a assinatura. Uma resposta de status OK será retornada para indicar que o cliente acessou os sistemas da Autodesk. Solicitação GET HTTP/1.1 Authorization: Bearer sdfh89rd4idj29ie9dfjed29d3dj CSN: signature: yfm0ddyhqnq2emfwicxdxpdpgef3y+ogofggjfticjo= timestamp: Resposta HTTP/ OK Content-Type: application/json Connection: keep-alive { status : ok } Especificamente apenas em getlicense, deve haver mais dois parâmetros no cabeçalho 1. REQUESTINGAPPLICATIONNAME: sempre deve ser igual a partner. 2. EFFECTIVEUSERID: deve ser igual a sysid_xxxxx gerado para o parceiro. A equipe da Autodesk gera este valor. Entre em contato com partner.integration.team@autodesk.com para enviar uma solicitação.

9 1.4 Códigos de erro HTTP Status Code Autodesk Error Code Internal Message 200 OK 201 Created 304 Not Modified 400 Bad Request Error: 4000 Incorrect or malformed request Unauthorized Error: 4100 No CSN was passed in the request Unauthorized Error: 4101 No HMAC Signature passed in the request 401 Unauthorized Error: 4102 No HMAC Client ID passed in the request 401 Unauthorized Error: 4103 No HMAC Timestamp passed in the request 401 Unauthorized Error: 4104 No Authorization passed in the request 401 Unauthorized Error: 4105 Invalid token 401 Unauthorized Error: 4106 Something went wrong generating the token 403 Forbidden Error: 4301 HMAC signature was passed, but not a correct one 403 Forbidden Error: 4302 HMAC timestamp was passed, but not a correct one 403 Forbidden Error: 4300 CSN was passed, but not a correct one

10 2 Conectar via Postman Você pode se conectar e testar as interações com o serviço de API da Autodesk usando o aplicativo do Chrome, Postman. As seções abaixo detalham como instalar e usar o Postman para autenticar e interagir com as APIs da Autodesk 2.1 Instalação do Postman Siga as etapas abaixo para instalar a versão de aplicativo empacotado do Postman. i. Abra o navegador Chrome e acesse ii. iii. Faça o download da plataforma certa para o seu computador. Ele abrirá uma Loja da Web do Chrome. Agora, clique no botão ADICIONAR AO CHROME.

11 iv. Durante a instalação, você será avisado de que o Postman terá acesso ao seu computador local e outros sites. Clique no botão Adicionar. v. Após a instalação, o Postman estará disponível como aplicativo do Chrome.

12 2.2 Como acessar APIs do DDWS com o Postman Como parte do processo de acesso aos serviços, os Parceiros têm que seguir as seguintes etapas: Gerar assinaturas e outros detalhes de cabeçalho para chamadas específicas de OAuth Chame o ponto de extremidade de OAuth para gerar um Token de acesso Gerar a assinatura para chamadas específicas de API Acessar a API do DDWS com os cabeçalhos necessários: assinatura, token de acesso etc. Para obter informações mais detalhadas, consulte a Documentação da API de autenticação e o Manual de referência do serviço relevante Geração de um token de acesso Para acessar as APIs do DDWS, um token de acesso deve ser fornecido na solicitação. O processo de geração de Token de acesso envolve a validação das credenciais válidas do cliente, da assinatura e do registro de data e hora. As credenciais do cliente devem ser credenciais válidas que foram geradas durante o processamento de apresentação. Etapas para gerar o token de acesso: i. Abra o Postman por meio do Chrome App Launcher ou do navegador Chrome a. Selecione o ícone do Postman para iniciar o aplicativo.

13 b. Abra o navegador Chrome e acesse chrome://apps/ 1. A Loja Web do Chrome será aberta. Clique no ícone do Postman para iniciar o aplicativo. ii. iii. Na página REST Builder do Postman, insira a URL da OAuth client_credentials no campo Inserir URL da solicitação aqui. Selecione o Método como POST para a API. iv. Forneça os parâmetros de Cabeçalho a seguir e clique no botão Enviar. Para gerar esses valores de cabeçalho, siga as instruções na seção Nome do cabeçalho: Autorização, Valor: "Básica <codificação Base64 de credenciais do cliente>" Nome do cabeçalho : assinatura, Valor: <assinatura> Nome do cabeçalho: registro de data e hora, Valor: <registro de data e hora>

14 v. Você obterá uma resposta, que conterá o Token de acesso. Salve o valor do token de acesso. Ele será usado para autenticar e autorizar o acesso às APIs. O token é de acesso só é válido para uma duração de 15 minutos. Depois que o token expirar, será preciso gerar um novo Testando o acesso aos serviços de API Abaixo é exibido um ponto de extremidade genérico que os Parceiros podem chamar para testar o sincronismo. O recebimento de Parceiros de uma resposta "Status OK" indicará que a comunicação deles com o back-end foi bem-sucedida. O exemplo a seguir mostra como estamos esperando que os cabeçalhos necessários para autenticação e autorização sejam formatados para uma comunicação bem-sucedida com o ponto de extremidade. Consulte o Manual de referência do serviço correspondente para saber como chamar cada Serviço de API em particular. i. Insira a URL da API no campo Inserir URL da solicitação aqui. ii. Selecione o Método como GET para a API.

15 iii. Forneça os parâmetros de Cabeçalho a seguir e clique no botão Enviar. Para gerar esses valores de cabeçalho, siga as instruções na seção Nome do cabeçalho: CSN, Valor: <CSN do parceiro> Nome do cabeçalho: Autorização, Valor: "Portador<access_token>" Nome do cabeçalho : assinatura, Valor: <assinatura> Nome do cabeçalho: registro de data e hora, Valor: <registro de data e hora> iv. Se a chamada for bem-sucedida, você deverá obter uma mensagem de "Status: OK" do sistema.

16 2.2.3 Gerar cabeçalhos para chamadas ao OAuth e à API do serviço A Autodesk forneceu duas opções para gerar os cabeçalhos, como a marcação de data e hora e a assinatura, para as chamadas de OAuth e as chamadas da API do serviço. Os Parceiros podem usar o utilitário de GUI ou podem executar o script Python on-line. A seguinte seção explica detalhadamente estas duas opções: Opção 1: gere assinaturas usando o utilitário de GUI desenvolvido pela Autodesk Siga as etapas abaixo para gerar uma assinatura usando o utilitário de GUI: i. Salve a pasta DDWS-Client.zip a seguir no seu sistema local. DDWS-Client.zip ii. iii. iv. Extraia o conteúdo do arquivo DDWS-Client.zip no seu sistema. Abra o arquivo DDWS-Client.html usando o navegador Chrome. Na seção Pontos de extremidade de OAuth, forneça o seu ID de cliente, o Segredo do cliente e a URL de retorno de chamada (que foi definida e recebida como parte do processo de apresentação). Clique no botão Gerar. v. Isso gerará os valores válidos de Autorização, Assinatura e Registro de data e hora necessários nos cabeçalhos da solicitação de OAuth. A assinatura só será válida por 5 minutos.

17 Depois que um Token de acesso é gerado, um conjunto de etapas análogas deve ser seguido para gerar uma assinatura necessária para as chamadas à API do serviço: i. Em DDWS-Client.html, na seção Ponto de extremidade da API, forneça o token de acesso recebido da resposta de OAuth (seção v), o Segredo de cliente e a URL de retorno de chamada, e clique no botão Gerar.

18 ii.isso gerará os valores válidos de assinatura e de registro de data e hora necessários no cabeçalho para solicitações da API do serviço. A assinatura somente será válida por 5 minutos. Opção 2: gere a assinatura executando o script Python on-line Siga as etapas abaixo para gerar uma assinatura executando um script Python on-line: i. Acesse A seguinte janela será aberta. ii. Para chamar o ponto de extremidade de OAuth, cuidadosamente faça a alteração a seguir no main.py e substitua client_id, client_secret e callback_url pelos valores definidos e recebidos durante o processo de integração, onde indicado pelos realces amarelos no esquema abaixo (os valores no esquema abaixo são simplesmente valores fictícios). Substituir:

19 # Hello World program in Python print "Hello World!\n" Com: import re import time import calendar from base64 import b64encode from datetime import timedelta, datetime from hmac import HMAC import sys, os, base64, hashlib, hmac callback_url = " timestamp = calendar.timegm(time.gmtime()) client_id = "2LDR5j0yG0PhW23PranLQ6JlwMoMabgo" client_secret = "op30uee2kdei2fmf" signed_signature = base64.b64encode(hmac.new(client_secret, callback_url +client_id+ str(timestamp), hashlib.sha256).digest()) s = client_id + ":" + client_secret b64_string = base64.b64encode(s) print("b64 string--- " + b64_string) print("signed_signature-- >"+signed_signature) print("timestamp-- >"+str(timestamp)) iii. Clique no botão Executar. Ele gerará a assinatura, o registro de data e hora e o cabeçalho de autorização. A assinatura é válida somente por 5 minutos. Esses valores serão utilizados no cabeçalho da solicitação de OAuth iv. Para chamar os pontos de extremidade da API do serviço, troque o valor de client_id do script acima pelo valor do token de acesso recebido da resposta de OAuth (seção 2.2.1v). A assinatura e o registro de data e hora gerados serão válidos para solicitações de API nos próximos cinco minutos.