Servicios web de distribución digital (DDWS) Guía de autenticación de API

Transcripción

1 Servicios web de distribución digital (DDWS) Guía de autenticación de API

2 CONTENIDO Historial de revisiones Autenticación de API con Autodesk Descripción general Firma digital de DDWS y generación de token de acceso Ejemplos Llamada a OAuth para generar token de acceso Llamada a la API mediante el token de acceso Códigos de error Conectar mediante Postman Instalación de Postman Acceso a las API de DDWS con Postman Generación de un token de acceso Pruebas del acceso a los servicios de la API Generación de encabezados para llamadas de OAuth y de API del servicio... 16

3 Historial de revisiones Versión Fecha Autor Comentarios /10/2015 AR Se ha actualizado la sección 1.3.1: URL de solicitud /12/2015 AR Se han modificado los puntos finales de las secciones y de a /03/2016 MG Se ha actualizado la sección 1.1. Se ha añadido el formato de firma de token. Se ha actualizado la sección 1.2. Se han añadido los formatos de firma de token y API. Se ha actualizado la sección Se ha añadido la información de la firma para GetLicense /04/2016 MG Formato. Numeración corregida de a /04/2016 PL Se ha editado y revisado toda la sección 2.

4 1 Autenticación de API con Autodesk 1.1 Descripción general La API de autenticación que se expone sirve para proteger los servicios web de distribución digital, DDWS, frente al acceso no deseado y no autorizado a nuestros servicios de API de Autodesk. Verificará la autenticidad de la llamada a través de firmas digitales y, además, ayudará a gestionar el ámbito de los recursos de la API a la que cada distribuidor puede llamar a través de OAuth de 2 partes 2.0 El servicio de la API de DDWS está diseñado para autenticarse con el mecanismo de OAuth 2.0. Todas las solicitudes API tendrán que incluir una firma digital para probar su autenticidad. Un distribuidor debe generar firmas por solicitud e incrustarlas en el encabezado al utilizar las API de DDWS. Con nuestra capa de proxy, la generación de tokens de acceso implica la validación de los siguientes parámetros de distribuidor: 1. Credenciales codificadas en base Marca de tiempo (no anteriores a 5 minutos) 3. Firma generada En el encabezado de la autorización de la solicitud de OAuth, se esperaba el valor codificado de base 64 de una cadena que corresponde al ID de cliente y al secreto del cliente separados por dos puntos. El valor codificado de la cadena se calculará como: client_id client_secret Valor codificado 3PPWWSSSS4SSffssSSTTLLrr2ffbb1ttaaaaQQ6JJllwwMMooMMaabbggoo mmhcc90ttssiiff2mmee2ffmmff client_id:client_secret 3PPWWSSSS4SSffssSSTTLLrr2ffbb1ttaaaaQQ6JJllwwMMooMMaabbggoo:mmhcc90ttssIIff2mmee2ffMMFF La cadena codificada en base 64 se puede construir utilizando el siguiente formato: Authorization Header = Concatenate( Basic, Base64Encode(Concatenate (client_id, :, client_secret)) Esto, a su vez, debería dar como resultado un valor con codificación base 64: MM1BBXXUU1MM0UU2ZZzzUU1RRMMccjjJJmmYYjjFF0YYWWFFRRNNkkppssdd01vvTTWWFFiiZZ286bbWWhjjOOTTBB0cc0llmmMMmm1llMMmmZZNNRRgg ==

5 Al llamar a los servicios de la API, se espera que el token de acceso recibido correspondiente a la llamada de generación de token OAuth inicial esté en el encabezado de cada solicitud como un token portador. Nota: El token solo es válido durante 15 minutos. No se proporcionará un token "actualizado", por lo que se debe realizar una nueva llamada para generar un nuevo token. 1.2 Firma digital de DDWS y generación de token de acceso Comenzamos proporcionando descripciones para lo siguiente: Devolución de llamada: la dirección URL de devolución de llamada enviada al registrar su aplicación en el portal de desarrolladores. ID de cliente: se obtiene del portal de desarrolladores después de registrar su aplicación correctamente. Sinónimo de clave de cliente. Marca de tiempo: segundo exacto en el que se ha generado la firma timestamp = current Epoch Time (10 Digits) Token de acceso: se obtiene a partir de la respuesta de la llamada de OAuth para generar el token La generación de una firma implica el uso del cifrado HMACSHA256 de base 16 estándar de message_string. Si está llamando al punto final de OAuth para generar un token de acceso, el valor de message_string en cuestión es una concatenación de los valores siguientes, en el orden en que se presentan: devolución de llamada + ID de cliente + marca de tiempo signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, client_id, timestamp)) Si está llamando a cualquier otro punto final de servicio de API, como /orders/fulfillment o /partner/test, message_string es entonces una concatenación de los valores siguientes, en el orden en que se presentan: devolución de llamada + token de acceso + marca de tiempo signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, Access_Token from the service(no bearer string here), timestamp))

6 El siguiente es un ejemplo de secuencia de comandos de Python para generar la firma que se va a usar para la llamada de OAuth. Nota: Los valores utilizados aquí son valores ficticios. Deberá proporcionar su propio ID de cliente, secreto de cliente, etc., para generar su propia firma. 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)) Con respecto a las firmas necesarias para llamar a nuestros servicios API, consulte la secuencia anterior y cambie el valor de client_id por el token de acceso recibido de la llamada a OAuth.

7 1.3 Ejemplos Llamada a OAuth para generar token de acceso Una solicitud POST se lleva a cabo en nuestro punto final, /v2/oauth/generateaccesstoken con la firma, las credenciales codificadas en base 64 y el valor del sello horario situado en el encabezado de la solicitud. En la consulta, especifique que el tipo de concesión corresponderá a las credenciales del cliente. En la respuesta de JSON, el token de acceso en cuestión estará ubicado en el campo access_token. Solicitud POST autodesk.com/v2/oauth/generateaccesstoken?grant_type=client_credential s HTTP/1.1 Authorization: Basic MkxEUjVqMHlHMFBoVzIzUHJhbkxRNkpsd01vTWFiZ286b3AzMHVlZTJL== signature: pbfumincypcpqrxenehq6skc+84= timestamp: Respuesta 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 Llamada a la API mediante el token de acceso A continuación utilizamos un punto final, /v1/partner/test, que los distribuidores pueden utilizar para simular una llamada a la API que requiere el token de acceso. Llame al punto final con el encabezado de autorización que contendrá la información del token. En el encabezado, también se incluyen el número específico de cliente (CSN) recibido en la incorporación, la nueva firma generada para las llamadas a la API y la marca de tiempo utilizada para la firma. Se devolverá una respuesta de estado correcto para indicar que la llamada ha alcanzado los sistemas de Autodesk. Solicitud GET HTTP/1.1 Authorization: Bearer sdfh89rd4idj29ie9dfjed29d3dj CSN: signature: yfm0ddyhqnq2emfwicxdxpdpgef3y+ogofggjfticjo= timestamp: Respuesta HTTP/ OK Content-Type: application/json Connection: keep-alive { status : ok } Específicamente para getlicense, el encabezado debe incluir dos parámetros más: 1. REQUESTINGAPPLICATIONNAME: siempre debe ser igual que "distribuidor". 2. EFFECTIVEUSERID: debe ser el valor "sysid_xxxxx" generado por el distribuidor (el equipo de Autodesk genera este valor; póngase en contacto con partner.integration.team@autodesk.com para realizar una solicitud).

9 1.4 Códigos de error Código de estado de HTTP Código de error de Autodesk Mensaje interno 200 OK 201 Created 304 No modificado 400 Solicitud errónea Error: 4000 Solicitud incorrecta o mal formada No autorizado Error: 4100 No se ha especificado un CSN en la solicitud Unauthorized Error: 4101 No se ha pasado una firma HMAC en la solicitud. 401 No autorizado Error: 4102 No se ha pasado un ID de cliente HMAC en la solicitud. 401 No autorizado Error: 4103 No se ha pasado una marca de tiempo HMAC en la solicitud. 401 No autorizado Error: 4104 No se ha pasado ninguna autorización en la solicitud. 401 Unauthorized Error: 4105 Token no válid.o 401 Unauthorized Error: 4106 Se ha producido un problema al generar el token. 403 Prohibido Error: 4301 Se ha pasado una firma HMAC, pero no una correcta. 403 Forbidden Error: 4302 Se ha pasado un sello horario de HMAC, pero no el correcto. 403 Prohibido Error: 4300 Se ha pasado un CSN, pero no el correcto.

10 2 Conectar mediante Postman Puede conectar y probar interacciones con el servicio de la API de Autodesk mediante Postman, una aplicación de Chrome. Las siguientes secciones detallan cómo instalar y usar Postman para autenticar e interactuar con las API de Autodesk. 2.1 Instalación de Postman Siga los pasos que se indican a continuación para instalar la versión empaquetada de la aplicación Postman. i. Abra el navegador Chrome y vaya a ii. iii. Descargue la plataforma adecuada para su equipo. Se abrirá una página de Chrome Web Store. A Haga clic en el botón AÑADIR A CHROME.

11 iv. Durante la instalación, se le advertirá de que Postman accederá a su equipo local y a otros sitios web. Haga clic en el botón Añadir. v. Una vez instalado, Postman estará disponible como una aplicación de Chrome.

12 2.2 Acceso a las API de DDWS con Postman Como parte del proceso de los servicios de acceso, los distribuidores deben llevar a cabo los siguientes pasos: Generar firmas y otros detalles de encabezado para llamadas OAuth específicas. Llamar al punto final de OAuth para generar un token de acceso. Generar la firma para las llamadas específicas de las API. Acceder a la API de DDWS con los encabezados necesarios: firma, token de acceso, etc. Para obtener información más detallada, consulte la documentación de la API de autenticación y el Manual de referencia del servicio relevante Generación de un token de acceso Para acceder a las API de DDWS, deberá proporcionarse un token de acceso en la solicitud. El proceso de generación de un token de acceso implica la validación de firmas, marca de tiempo y credenciales de cliente válidas. Las credenciales del cliente deben ser credenciales válidas generadas durante el procesamiento de incorporación. Pasos para generar un token de acceso: i. Abrir Postman mediante el menú de aplicaciones de Chrome o el navegador Chrome a. Seleccione el icono de Postman para iniciar la aplicación.

13 b. Abra el navegador Chrome y vaya a chrome://apps/ 1. Se abrirá Chrome Web Store. Haga clic en el icono Postman para iniciar la aplicación. ii. iii. En la página REST Builder de Postman, introduzca la dirección URL de OAuth grant_type=client_credentials en el campo indicado para la URL de solicitud. Seleccione el Método como POST para la API. iv. Proporcione los siguientes parámetros de encabezado y haga clic en el botón Enviar. Para generar estos valores de encabezado, siga las instrucciones de la sección Nombre de encabezado: Authorization (Autorización), valor: Basic <Base64 encoding of client credentials> Nombre de encabezado: signature (firma), Valor: <firma> Nombre de encabezado: timestamp (marca de tiempo), Valor: < marca de tiempo>

14 v. Obtendrá una respuesta que contendrá el token de acceso. Guarde el valor del token de acceso. Se utilizará para autenticar y autorizar el acceso a las API. El token de acceso solo es válido durante 15 minutos. Una vez que haya caducado el token, deberá generarse uno nuevo Pruebas del acceso a los servicios de la API A continuación, se muestra un punto final genérico al que los distribuidores pueden llamar para probar la comunicación. Si los distribuidores reciben una respuesta de "Estado correcto", esto significa que su comunicación con el backend se ha realizado correctamente. El ejemplo siguiente muestra cómo esperamos que los encabezados necesarios para la autenticación y autorización tengan el formato para una comunicación correcta con el punto final. Consulte el Manual de referencia del servicio correspondiente para saber cómo llamar a cada servicio de API en concreto. i. Introduzca la URL de la API en el campo indicado para la URL de solicitud aquí. ii. Seleccione el Método como GET para la API.

15 iii. Proporcione los siguientes parámetros de encabezado y haga clic en el botón Enviar. Para generar estos valores de encabezado, siga las instrucciones de la sección Nombre de encabezado: CSN, valor: <partner csn> Nombre de encabezado: autorización, valor: Portador <access_token> Nombre de encabezado: firma, Valor: <firma> Nombre de encabezado: marca de tiempo, Valor: <marca de tiempo> iv. Si la llamada es correcta, deberá obtener un mensaje de estado correcto del sistema.

16 2.2.3 Generación de encabezados para llamadas de OAuth y de API del servicio Autodesk ofrece dos opciones para generar los encabezados, como la marca de tiempo y la firma, tanto para las llamadas de OAuth como para las llamadas a la API del servicio. Los distribuidores pueden utilizar la utilidad de la GUI o pueden ejecutar la secuencia de comandos de Python en línea dada. La siguiente sección explica ambas opciones en detalle: Opción 1: Generar firmas mediante la utilidad de la GUI desarrollada por Autodesk Siga los pasos que se indican a continuación para generar una firma mediante la utilidad de la GUI: i. Guarde la siguiente carpeta DDWS-Client.zip en el sistema local. DDWS-Client.zip ii. iii. iv. Extraiga el contenido del archivo DDWS-Client.zip en el sistema. Abra el archivo DDWS-Client.html con el navegador Chrome. En la sección Puntos finales de OAuth, introduzca su ID de cliente, secreto de cliente y URL de devolución de llamada (que se ha establecido y recibido como parte de su proceso de incorporación). Haga clic en el botón Generar. v. De este modo, se generarán los valores de Autorización, Firma y Marca de tiempo válidos necesarios en los encabezados de la solicitud de OAuth. La firma solo será válida durante 5 minutos.

17 Una vez que se haya generado un token de acceso, se debe seguir un conjunto de pasos similares para generar una firma necesaria para las llamadas a la API del servicio: i. En DDWS-Client.html, en la sección 'Punto final de API', proporcione el token de acceso recibido desde la respuesta de OAuth (sección v), el secreto de cliente y la URL de devolución de llamada, y haga clic en el botón Generar.

18 ii. De este modo, se generarán los valores de firma y marca de tiempo válidos necesarios en el encabezado de las solicitudes API de servicio. La firma solo será válida durante 5 minutos. Opción 2: Generar la firma ejecutando la secuencia de comandos de Python en línea Siga los pasos que se indican a continuación para generar una firma mediante la ejecución en línea de una secuencia de comandos de Python: i. Vaya a Se abrirá la siguiente ventana. ii. Para llamar al punto final de OAuth, realice cuidadosamente el siguiente cambio en main.py y sustituya su client_id, client_secret y callback_url con los valores establecidos y recibidos durante el proceso de incorporación donde se indica con el resaltado amarillo en el esquema siguiente (los valores del siguiente esquema son valores ficticios). Reemplazar:

19 # Hello World program in Python print "Hello World!\n" con: 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. Haga clic en el botón Ejecutar. Se generará el encabezado de firma, la marca de tiempo y la autorización. La firma solo es válida durante 5 minutos. Estos valores se utilizarán en el encabezado de la solicitud de OAuth. iv. Para llamar a los puntos finales de la API de servicio, intercambie el valor client_id con el valor del token de acceso recibido de la respuesta de OAuth (sección v). La firma y la marca de tiempo generadas serán válidas para las solicitudes de API durante los siguientes 5 minutos.