Serviç os da Web de distribuição digital

(DDWS)

Guia de autenticação de API

ÍNDICE Histórico de revisão ............................................................................................................................. 3

1 Autenticação de API com o Autodesk ......................................................................................... 4

1.1 Visão geral ........................................................................................................................... 4

1.2 Assinatura digital do DDWS e geração de token de acesso ............................................... 5

1.3 Exemplos .............................................................................................................................. 7

1.3.1 Chamada ao OAuth para gerar o token de acesso .......................................... 7

1.3.2 Chamada à API usando o token de acesso ..................................................... 8

1.4 Códigos de erro .................................................................................................................... 9

2 Conectar via Postman ............................................................................................................... 10

2.1 Instalação do Postman ....................................................................................................... 10

2.2 Como acessar APIs do DDWS com o Postman ................................................................ 12

2.2.1 Geração de um token de acesso ................................................................... 12

2.2.2 Testando o acesso aos serviços de API ........................................................ 14

2.2.3 Gerar cabeçalhos para chamadas ao OAuth e à API do serviço ................... 16

Histórico de revisão

Versão Data Autor Comentários

1.0 22/10/2015 AR Seção 1.3.1 atualizada — URL da

solicitação

1.1 03/12/2015 AR Extremidade modificada na seção

1.3.2 e 2.2.4 de

https://enterprise-api-

stg.autodesk.com/v1/partner/test

para https://enterprise-api-

stg.autodesk.com/v1/invoices

1.2 04/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 1.3.1 atualizada

Foram adicionadas as

informações de assinatura para

obter licença

1.3 30/04/2016 MG Formatação

Numeração corrigida de 2.2.4

para 2.2.3

1.4 19/04/2016 PL Editado e revisou toda a Seção 2

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 64

2. 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 3𝑃𝑊𝑆𝑆4𝑆𝑓𝑠𝑆𝑇𝐿𝑟2𝑓𝑏1𝑡𝑎𝑎𝑄6𝐽𝑙𝑤𝑀𝑜𝑀𝑎𝑏𝑔𝑜

client_secret 𝑚ℎ𝑐90𝑡𝑠𝐼𝑓2𝑚𝑒2𝑓𝑀𝐹

Valor codificado client_id:client_secret

3𝑃𝑊𝑆𝑆4𝑆𝑓𝑠𝑆𝑇𝐿𝑟2𝑓𝑏1𝑡𝑎𝑎𝑄6𝐽𝑙𝑤𝑀𝑜𝑀𝑎𝑏𝑔𝑜:𝑚ℎ𝑐90𝑡𝑠𝐼𝑓2𝑚𝑒2𝑓𝑀𝐹

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:

𝑀1𝐵𝑋𝑈1𝑀0𝑈2𝑍𝑧𝑈1𝑅𝑀𝑐𝑗𝐽𝑚𝑌𝑗𝐹0𝑌𝑊𝐹𝑅𝑁𝑘𝑝𝑠𝑑01𝑣𝑇𝑊𝐹𝑖𝑍286𝑏𝑊ℎ𝑗𝑂𝑇𝐵0𝑐0𝑙𝑚𝑀𝑚1𝑙𝑀𝑚𝑍𝑁𝑅𝑔 ==

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

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 = "https://www.callbackurl.com" 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.

1.3 Exemplos

1.3.1 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 https://enterprise-api-stg. autodesk.com/v2/oauth/generateaccesstoken?grant_type=client_credential s HTTP/1.1 Authorization: Basic MkxEUjVqMHlHMFBoVzIzUHJhbkxRNkpsd01vTWFiZ286b3AzMHVlZTJL== signature: pBFuMiNCYpcpqRxEnEHq6Skc+84= timestamp: 1467834645

Resposta

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 523 Connection: keep-alive { "access_token" : "Q0K4S7iVJnuCVYP9ydARATNBJLyn", "expires_in" : 899, "token_type" : "BearerToken" }

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 https://enterprise-api-stg.autodesk.com/v1/invoices HTTP/1.1 Authorization: Bearer sdfh89rd4idj29ie9dfjed29d3dj CSN: 123456 signature: yfm0DDYHqNQ2eMfwICXDXpdPgEf3Y+ogofGGjftiCJo= timestamp: 1438463349

Resposta

HTTP/1.1 200 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.

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

401 - Unauthorized Error: 4100 No CSN was passed in the request

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

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 https://www.getpostman.com/.

ii. Faça o download da plataforma certa para o seu computador.

iii. Ele abrirá uma Loja da Web do Chrome. Agora, clique no botão ADICIONAR AO

CHROME.

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.

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.

2.2.1 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.

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. Na página REST Builder do Postman, insira a URL da OAuth https://enterprise-

api-stg.autodesk.com/v2/oauth/generateaccesstoken?grant_type=

client_credentials no campo Inserir URL da solicitação aqui.

iii. 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 2.2.3.

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>

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.

2.2.2 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 https://enterprise-api-stg.autodesk.com/v1/invoices no campo

Inserir URL da solicitação aqui.

ii. Selecione o Método como GET para a API.

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 2.2.3.

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.

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. Extraia o conteúdo do arquivo DDWS-Client.zip no seu sistema.

iii. Abra o arquivo DDWS-Client.html usando o navegador Chrome.

iv. 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.

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 2.2.1.v), o Segredo de cliente e

a URL de retorno de chamada, e clique no botão Gerar.

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 http://www.tutorialspoint.com/execute_python_online.php. 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:

# 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 = "https://www.callbackurl.com" 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.