Digital Distribution Web Services (DDWS) Guida all'autenticazione API

Transcript

1 Digital Distribution Web Services (DDWS) Guida all'autenticazione API

2 INDICE Cronologia revisioni Autenticazione API con Autodesk Panoramica Generazione di firma digitale e token di accesso di DDWS Esempi Richiesta OAuth per generare token di accesso Richiesta API tramite token di accesso Codici di errore Connessione tramite Postman Installazione di Postman Accesso alle API di DDWS con Postman Generazione di un token di accesso Verifica dell'accesso ai servizi API Generare intestazioni per le richieste OAuth e API del servizio... 16

3 Cronologia revisioni Versione Data Autore Commenti /22/2015 AR Aggiornata sezione URL richiesta /03/2015 AR Modifica dell'endpoint nelle sezioni e da a /04/2016 MG Aggiornata sezione 1.1 Aggiunta del formato firma token Aggiornata sezione 1.2 Aggiunta dei formati firma token e API Aggiornata sezione Aggiunta delle informazioni sulla firma per ottenere una licenza /04/2016 MG Formattazione Correzione della numerazione da a /19/2016 PL Modifica e revisione dell'intera Sezione 2

4 1 Autenticazione API con Autodesk 1.1 Panoramica L'API di autenticazione presentata consente di proteggere Digital Distribution Web Services, DDWS, dagli accessi non autorizzati e indesiderati ai servizi API di Autodesk. Consente di verificare l'autenticità della chiamata attraverso le firme digitali, nonché gestire l'ambito di risorse API che ciascun partner può chiamare tramite OAuth 2.0 in 2 fasi Il servizio API DDWS è progettato per l'autenticazione con il meccanismo OAuth 2.0. Per poter essere autenticate, tutte le richieste API devono includere una firma digitale. Un partner deve generare firme per ogni richiesta e incorporarle nell'intestazione durante l'utilizzo delle API DDWS. All'interno del livello proxy, la generazione di token di accesso implica la convalida dei seguenti parametri dei partner: 1. Credenziali con codifica Base64 2. Timestamp (non oltre 5 minuti) 3. Firma generata Nell'intestazione dell'autorizzazione della richiesta OAuth, il valore con codifica Base64 di una stringa che rappresenta l'id client e il Client Secret devono essere separati da due punti. Il valore codificato della stringa verrà calcolato come: client_id client_secret Valore codificato 3PWSS4SfsSTLr2fb1taaQ6JlwMoMabgo mhc90tsif2me2fmf client_id:client_secret 3PWSS4SfsSTLr2fb1taaQ6JlwMoMabgo:mhc90tsIf2me2fMF La stringa con codifica Base64 può essere costruita con il seguente formato: Authorization Header = Concatenate( Basic, Base64Encode(Concatenate (client_id, :, client_secret)) Che, a sua volta, deve risultare un valore con codifica Base64 di: M1BXU1M0U2ZzU1R cjjmyjf0ywfrnkpsd01vtwfiz286bwhjotb0c0lmmm1lmmznrg ==

5 Durante la richiesta di servizi API, il token di accesso risultante dalla prima richiesta di generazione di token con OAuth deve trovarsi nell'intestazione dell'autorizzazione di ciascuna richiesta come bearer token. Nota: il token è valido solo per 15 minuti. Non verrà fornito alcun token di aggiornamento. Per generare un nuovo token, sarà necessario effettuare una nuova chiamata. 1.2 Generazione di firma digitale e token di accesso di DDWS Per iniziare, verranno fornite le descrizioni dei seguenti elementi: callback: URL di callback inviato quando si registra l'applicazione sul portale per gli sviluppatori. ID client: ottenuto dal portale per gli sviluppatori dopo aver effettuato la registrazione dell'applicazione. Sinonimo di Chiave cliente. timestamp: momento esatto della generazione della firma timestamp = current Epoch Time (10 Digits) token di accesso: ottenuto dalla risposta alla richiesta OAuth per la generazione del token La generazione di una firma implica la codifica HMACSHA256 Base64 standard della stringa message_string. Se si contatta l'endpoint OAuth per la generazione di un token di accesso, la stringa message_string in questione risulta una concatenazione dei valori seguenti, nell'ordine in cui sono presentati: callback + client_id + timestamp signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, client_id, timestamp)) Se si contatta qualsiasi altro endpoint di servizio API come /orders/fulfillment o /partner/test, message_string risulta una concatenazione dei valori seguenti, nell'ordine in cui sono presentati: callback + token di accesso + timestamp signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, Access_Token from the service(no bearer string here), timestamp))

6 Quello seguente è un esempio di script Python per la generazione della firma da utilizzare nella chiamata OAuth. Nota: i valori utilizzati non sono reali. È necessario fornire il proprio ID client, il Client Secret e cosìvia per generare la propria 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)) Per le firme necessarie per richiedere i servizi API, fare riferimento allo script menzionato in precedenza e sostituire il valore client_id con il token di accesso ricevuto dalla richiesta OAuth.

7 1.3 Esempi Richiesta OAuth per generare token di accesso Viene eseguita una richiesta POST all'endpoint, /v2/oauth/generateaccesstoken con firma, credenziali con codifica Base64 e il valore timestamp collocati nell'intestazione della richiesta. Nella query specificare che il tipo di assegnazione sarà rappresentato dalle credenziali client. Nella risposta JSON, il token di accesso in questione si troverà nel campo access_token. Richiesta POST autodesk.com/v2/oauth/generateaccesstoken?grant_type=client_credential s HTTP/1.1 Authorization: Basic MkxEUjVqMHlHMFBoVzIzUHJhbkxRNkpsd01vTWFiZ286b3AzMHVlZTJL== signature: pbfumincypcpqrxenehq6skc+84= timestamp: Risposta 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 Richiesta API tramite token di accesso Di seguito viene utilizzato un endpoint, / v1/partner/test che i partner possono usare per simulare una richiesta API che richiede il token di accesso. Chiamare l'endpoint con l'intestazione dell'autorizzazione, che conterrà le informazioni del token. Includere nell'intestazione anche il numero CSN ricevuto durante la formazione, la nuova firma generata per le richieste API e il timestamp utilizzato per la firma. Verrà restituito un messaggio di risposta "OK" per indicare che la richiesta ha raggiunto i sistemi Autodesk. Richiesta GET HTTP/1.1 Authorization: Bearer sdfh89rd4idj29ie9dfjed29d3dj CSN: signature: yfm0ddyhqnq2emfwicxdxpdpgef3y+ogofggjfticjo= timestamp: Risposta HTTP/ OK Content-Type: application/json Connection: keep-alive { status : ok } In particolare solo per getlicense, nell'intestazione devono essere presenti altri due parametri 1. REQUESTINGAPPLICATIONNAME: deve essere sempre uguale a "partner". 2. EFFECTIVEUSERID: deve essere uguale al valore "sysid_xxxxx" generato per il partner (è il team Autodesk che genera questo valore. Per inviare una richiesta, contattare Autodesk all'indirizzo partner.integration.team@autodesk.com).

9 1.4 Codici di errore Codice di stato HTTP Codice di errore Autodesk Messaggio interno 200 OK 201 Creato 304 Non modificato 400 Richiesta non valida Errore: 4000 Richiesta errata o non corretta Non autorizzato Errore: 4100 Nessun CSN passato nella richiesta Non autorizzato Errore: 4101 Nessuna firma HMAC passata nella richiesta Non autorizzato Errore: 4102 Nessun ID client HMAC passato nella richiesta Non autorizzato Errore: 4103 Nessun timestamp HMAC passato nella richiesta Non autorizzato Errore: 4104 Nessuna autorizzazione passata nella richiesta Non autorizzato Errore: 4105 Token non valido Non autorizzato Errore: 4106 Si è verificato un errore durante la generazione del token Non consentito Errore: 4301 La firma HMAC è stata passata ma non è corretta Non consentito Errore: 4302 Il timestamp HMAC è stato passato ma non è corretto Non consentito Errore: 4300 Il CSN è stato passato ma non è corretto

10 2 Connessione tramite Postman È possibile connettere e verificare le interazioni con il servizio API di Autodesk utilizzando l'applicazione Postman di Chrome. Nelle seguenti sezioni viene descritto come installare e utilizzare Postman per l'autenticazione e l'interazione con le API di Autodesk. 2.1 Installazione di Postman Oer installare Postman in versione app, eseguire i passaggi descritti di seguito. i. Aprire il browser Chrome e passare a ii. iii. Scaricare la piattaforma corretta per il proprio sistema. Verrà aperto Chrome Web Store. Fare clic sul pulsante AGGIUNGI A CHROME.

11 iv. Durante l'installazione, verrà visualizzato un avviso per segnalare che Postman accederà al computer locale e ad altri siti Web. Fare clic sul pulsante Aggiungi. v. Dopo l'installazione, Postman sarà disponibile come applicazione di Chrome.

12 2.2 Accesso alle API di DDWS con Postman Come parte della procedura di accesso ai servizi, i partner devono eseguire i passaggi seguenti: Generare le firme e altri dettagli dell'intestazione per richieste specifiche OAuth Contattare l'endpoint OAuth per generare un token di accesso Generare la firma per richieste specifiche API Accedere all'api DDWS con le intestazioni richieste, ovvero firma, token di accesso e cosìvia. Per informazioni più dettagliate, consultare la documentazione API di autenticazione e il relativo Manuale di riferimento del servizio Generazione di un token di accesso Per accedere alle API di DDWS, è necessario fornire un token di accesso nella richiesta. La procedura di generazione del token di accesso implica la convalida di credenziali client, nonché la firma e il timestamp validi. Le credenziali client devono essere credenziali valide generate durante il processo di formazione. Passaggi per la generazione di token di accesso: i. Aprire Postman tramite Chrome App Launcher o il browser Chrome a. Selezionare l'icona Postman per avviare l'app.

13 b. Aprire il browser Chrome e passare a chrome://apps/ 1. Verrà aperto Chrome Web Store. Fare clic sull'icona Postman per avviare l'app. ii. iii. Nella pagina REST Builder di Postman, immettere l'url OAuth als nel campo Enter request URL here. Selezionare il metodo POST per l'api. iv. Specificare i seguenti parametri di intestazione e fare clic sul pulsante Invia. Per generare questi valori di intestazione, seguire le istruzioni della sezione Nome dell'intestazione: Authorization, valore: "Basic <Codifica Base64 delle credenziali client>" Nome dell'intestazione: signature, Valore: <firma> Nome dell'intestazione: timestamp, Valore: < timestamp>

14 v. Si riceverà una risposta contenente il token di accesso. Salvare il valore del token di accesso. Verrà utilizzato per eseguire l'autenticazione e autorizzare l'accesso alle API. Il token di accesso è valido solo per 15 minuti. Quando il token scade, sarà necessario generarne uno nuovo Verifica dell'accesso ai servizi API Di seguito viene illustrato un endpoint generico che il partner può richiedere per provare l'handshaking. Se il partner riceve la risposta "Status OK", significa che la comunicazione con il backend è riuscita. Nell'esempio seguente viene illustrato in che modo le intestazioni necessarie per l'autenticazione e l'autorizzazione devono essere formattate per una comunicazione efficace con l'endpoint. Per informazioni su come contattare ciascun servizio API, consultare il Manuale di riferimento del servizio corrispondente. i. Immettere l'url dell'api nel campo Enter request URL here. ii. Selezionare il metodo GET per l'api.

15 iii. Specificare i seguenti parametri di intestazione e fare clic sul pulsante Send. Per generare questi valori di intestazione, seguire le istruzioni della sezione Nome dell'intestazione: CSN, Valore: <csn partner> Nome dell'intestazione: Authorization Valore: "Bearer <token_accesso>" Nome dell'intestazione: signature, Valore: <firma> Nome dell'intestazione: timestampvalore: <timestamp> iv. Se la richiesta viene eseguita correttamente, verrà visualizzato un messaggio "Status OK".

16 2.2.3 Generare intestazioni per le richieste OAuth e API del servizio Autodesk fornisce due opzioni per la generazione di intestazioni, ovvero il timestamp e la firma, sia per le richieste OAuth sia per le richieste API del servizio. I partner possono utilizzare l'utilità GUI oppure eseguire lo script Python online. Nella seguente sezione vengono descritte in modo dettagliato entrambe le opzioni: Opzione 1: Generazione di firme tramite l'utilità GUI sviluppata da Autodesk Eseguire i passaggi seguenti per generare una firma mediante l'utilità GUI: i. Salvare la cartella DDWS-Client.zip seguente nel sistema locale. DDWS-Client.zip ii. iii. iv. Estrarre il contenuto del file DDWS-Client.zip nel sistema. Aprire il file DDWS-Client.html utilizzando il browser Chrome. Nella sezione "Endpoint OAuth", inserire ID client, Client Secret e URL di callback (impostato e ricevuto durante la formazione). Fare clic sul pulsante Genera. v. Verranno generati i valori Au torizzazione, Firma e Timestamp validi necessari nelle intestazioni della richiesta OAuth. La firma è valida solo per 5 minuti.

17 Una volta generato il token di accesso, è necessario ripetere la procedura per generare una firma necessaria per le richieste API del servizio: i. Nella sezione "Endpoint API" di DDWS-Client.html specificare il token di accesso ricevuto dalla risposta OAuth (Sezione v), il Client Secret e l'url di callback, quindi fare clic sul pulsante Genera.

18 ii. Verranno generati i valori di firma e timestamp validi necessari nell'intestazione per le richieste di API di servizio. La firma è valida solo per 5 minuti. Opzione 2: Generazione della firma mediante l'esecuzione di uno script Python online Eseguire i passaggi seguenti per generare una firma tramite l'esecuzione di uno script Python online: i. Visitare il sito Verrà aperta la finestra seguente. ii. Per richiedere l'endpoint OAuth, apportare le seguenti modifiche a main.py e sostituire client_id, client_secret e callback_url con i valori impostati e ricevuti durante la formazione nel punto indicato in giallo nello schema sottostante (i valori nello schema non sono reali). Sostituire:

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. iv. Fare clic sul pulsante Esegui. Verranno generati firma, timestamp e intestazione dell'autorizzazione. La firma è valida solo per 5 minuti. Questi valori verranno utilizzati nell'intestazione della richiesta OAuth Per richiedere gli endpoint dell'api del servizio, sostituire il valore client_id dello script precedente con il valore del token di accesso ricevuto dalla risposta OAuth (Sezione v). La firma e il timestamp generati rimarranno validi per le richieste API per i successivi 5 minuti.