(Legacy) Manuale REST API (server-to-server) rest-api-cookbook-server-to-server
Panoramica overview
Lo scopo di questo documento di manuale è quello di descrivere nel dettaglio le best practice per l’implementazione dell’autenticazione Adobe Pass utilizzando le architetture server-to-server. Fornisce requisiti di base, implementazione di flusso dettagliata e considerazioni generali sugli ambienti di produzione e sul funzionamento.
Meccanismo di limitazione
L'API REST per l'autenticazione di Adobe Pass è gestita da un meccanismo di limitazione.
Componenti components
In una soluzione server-to-server funzionante sono coinvolti i seguenti componenti:
Flussi flows
Registrazione Dynamic Client (DCR)
Adobe Pass utilizza il DCR per proteggere le comunicazioni client tra un’applicazione o un server di programmazione e i servizi Adobe Pass. Il flusso DCR è separato e descritto nella documentazione Panoramica registrazione client dinamica.
Autenticazione (authN)
Il flusso di autenticazione consente a un utente di identificarsi
al proprio MVPD per determinare se l’utente dispone di un account valido.
- L’utente avvia l’app Streaming Device e tenta di accedere o visualizzare contenuti protetti.
- L’app Streaming Device richiede al servizio Programmatori di determinare se il dispositivo è già autenticato.
- Il servizio Programmatore registra l’app utilizzando DCR.
- Il servizio Programmatore controlla lo stato di autenticazione del dispositivo di streaming chiamando l'API checkauthn del servizio Adobe Pass.
- Nel caso in cui la chiamata checkauthn restituisca lo stato di autenticazione del dispositivo utente, l'app può procedere al flusso di autorizzazione.
- Nel caso in cui la chiamata checkauthn restituisca lo stato che indica che il dispositivo utente NON è autenticato, l'app deve attendere la richiesta di accesso di un utente.
- Quando l’utente richiede di accedere direttamente (ad esempio, seleziona il pulsante di accesso) o indirettamente (ad esempio, seleziona contenuti protetti quando non è già autenticato), l’app Streaming Device invia una richiesta al servizio Programmatore per avviare l’autenticazione dell’utente. Il servizio programmatore richiede e riceve un codice di registrazione univoco (regcode) chiamando l'API regcode del servizio Adobe Pass.
- Il servizio programmatore recupera inoltre l'elenco degli MVPD e degli attributi correnti chiamando l'API config del servizio Adobe Pass. Nota: questa API può anche essere chiamata in una fase precedente del flusso e memorizzata nella cache.
- Il servizio Programmatore restituisce il codice regcode all'app Streaming Device e all'elenco MVPD elaborato richiesto nel passaggio #7. Nota: il formato di elenco MVPD elaborato è specificato dal programmatore e può essere filtrato per consentire o bloccare in modo esplicito MVPD specifici (ovvero elenchi consentiti o bloccati).
- Se è diverso dal dispositivo AuthN (ovvero "seconda schermata"), per scelta o necessità (ovvero il dispositivo di streaming non supporta un agente utente), il dispositivo di streaming deve visualizzare il codice regcode e un URI affinché l’utente possa accedere all’applicazione AuthN. L'utente digita l'URI nell'agente utente sul dispositivo AuthN per avviare l'applicazione AuthN, quindi digita il codice regcode in tale applicazione. Se il dispositivo di streaming è lo stesso del dispositivo AuthN, il codice regcode può essere passato in modo programmatico al modulo AuthN.
- Il modulo AuthN avvia l’autenticazione utente con MVPD visualizzando un selettore MVPD. Dopo che l'utente ha selezionato MVPD, il modulo AuthN chiama authenticate con il codice regcode, che reindirizza l'agente utente all'IdP di MVPD. Quando l’utente si autentica correttamente con MVPD, l’agente utente viene reindirizzato indietro tramite il servizio Adobe Pass, dove l’autenticazione corretta viene registrata con il codice regcode e quindi reindirizzato al modulo AuthN.
- Se il dispositivo di streaming è diverso dal dispositivo AuthN, quest’ultimo deve visualizzare un messaggio di autenticazione all’utente e i passaggi per continuare (esempio: "Operazione riuscita! Ora puoi tornare alla console di gioco per continuare […]"). Se il dispositivo di streaming è lo stesso del dispositivo di autenticazione, il dispositivo di streaming può rilevare a livello di programmazione il completamento dell'autenticazione.
Il diagramma seguente illustra il flusso di autenticazione:
Autorizzazione (authZ)
Il flusso di autorizzazione viene utilizzato per determinare se un utente ha il diritto di accedere al contenuto richiesto.
- Ogni volta che l’utente tenta di visualizzare contenuto protetto nell’app Streaming Device, l’app Streaming Device chiama il servizio Programmatore per identificare il contenuto e richiedere le autorizzazioni e le informazioni necessarie per avviare il flusso.
- Il servizio Programmer chiama l'API Adobe Pass authorize trasmettendo l'ID risorsa insieme ad altri parametri richiesti. Il servizio Adobe chiama il servizio MVPD AuthZ con l’ID risorsa e riceve la decisione di autorizzazione che viene quindi passata al servizio programmatore. Questa decisione di autorizzazione verrà memorizzata nella cache dal servizio Adobe Pass per un periodo configurabile. Nelle successive chiamate authorize dal servizio Programmer al servizio Adobe Pass, il valore memorizzato in cache verrà restituito purché sia valido.
- Se l'autorizzazione viene concessa, il servizio Programmer deve chiamare l'API Adobe Pass /tokens/media, che restituirà un token multimediale firmato. Il servizio Programmatore deve convalidare il token multimediale utilizzando la libreria Media Token Verifier (JAR). Se valido, il servizio Programmatore deve restituire l'autorizzazione e il necessario per avviare il flusso (ad esempio, l'URL del flusso) richiesto nel passaggio #1.
- Se l'autorizzazione viene negata, la chiamata authorize restituirà un codice di errore e una descrizione al servizio Programmer. Il servizio Programmatore deve restituire il codice di errore e la descrizione (o un messaggio modificato dal programmatore) alla richiesta nel passaggio #1.
Il diagramma seguente illustra il flusso di autorizzazione:
Disconnetti
Il flusso di disconnessione consente a un utente di rimuovere l'identità
associato all’applicazione.
- Quando l’utente richiede la disconnessione (ovvero la rimozione dal dispositivo dell’account MVPD corrente associato all’applicazione), l’app Streaming Device chiama il servizio Programmatore per informarlo della disconnessione del dispositivo.
- Il servizio Programmatore deve chiamare l'API Adobe Pass logout.
Il diagramma seguente illustra il flusso di logout:
[Facoltativo] Preautorizzazione (ovvero Pre-volo)
La pre-autorizzazione può essere utilizzata per determinare rapidamente da un set di risorse quelle a cui un utente potrebbe avere accesso. Il risultato di questa chiamata viene in genere utilizzato per personalizzare l’interfaccia utente di un singolo utente.
-
Una volta autenticato l'utente, il dispositivo di streaming può chiamare il servizio programmatore per richiedere il contenuto a cui l'utente ha diritto di streaming.
-
Il servizio Programmatore deve chiamare l'API Adobe Pass preauthorize con un elenco di ID di risorse, che sono una stringa semplice che in genere rappresenta un canale che un utente potrebbe avere diritto a inviare in streaming. Nota: attualmente, la chiamata preauthorize è configurata per limitare l'elenco a cinque (5) ID risorsa. Quando sono necessarie più di cinque risorse, è possibile effettuare più preauthorize chiamate oppure configurare la chiamata per accettare più di cinque risorse con un accordo degli MVPD. Gli implementatori devono tenere presente il costo di una preauthorize chiamata alle risorse MVPD, nonché il tempo di risposta al programmatore e strutturare il loro utilizzo della chiamata in modo giudizioso.
-
La chiamata preauthorize risponderà al servizio Programmer con un oggetto JSON contenente un valore TRUE o FALSE per ogni ID risorsa nella richiesta che indica se l'utente ha diritto o meno al canale associato. Nota: se un MVPD non fornisce una risposta per un determinato ID risorsa (ad esempio a causa di errori di rete o timeout), il valore predefinito sarà FALSE.
-
Il Servizio programmatore deve utilizzare la risposta alla chiamata preauthorize per creare una risposta personalizzata definita dal programmatore al dispositivo di streaming, in genere per personalizzare la presentazione per l'utente in base ai diritti.
Il diagramma seguente illustra il flusso di preautorizzazione:
[Facoltativo] Metadati
I metadati possono essere utilizzati per recuperare le informazioni utente condivise da MVPD.
Alcuni esempi includono ID utente, codice postale, ecc.
-
Una volta autenticato l'utente, il servizio Programmer può chiamare l'API Adobe Pass usermetadata per richiedere informazioni sull'utente autenticato.
-
La risposta includerà tutti i metadati disponibili per l’utente specificato. I campi specifici vengono configurati separatamente per ogni integrazione Programmatore/MVPD.
Il diagramma seguente illustra il flusso di preautorizzazione:
Ambienti e requisiti funzionali environments
Un programmatore deve creare almeno due ambienti: uno per la produzione e uno o più per la gestione temporanea.
Produzione
L’ambiente di produzione deve essere altamente disponibile e scalabile in modo appropriato per picchi di grandi dimensioni o imprevisti (ad esempio sport live, rottura
notizie).
Il servizio Adobe Pass viene eseguito su più data center geograficamente distribuiti negli Stati Uniti. Per ottenere il tempo di risposta migliore (ovvero la latenza più bassa) dal servizio Adobe Pass, il programmatore deve anche creare un servizio simile distribuito geograficamente
infrastrutture.
Il servizio Programmer deve limitare la cache DNS a un massimo di 30 secondi nel caso in cui Adobe debba reindirizzare il traffico. Ciò può verificarsi se un centro dati non è più disponibile.
Il programmatore deve fornire l’intervallo IP pubblico dell’ambiente di produzione. Questi verranno inseriti in un elenco di IP consentiti nell’infrastruttura Adobe Pass per l’accesso e gestiti dai criteri di utilizzo delle API equi di Adobe.
Staging
L’ambiente di staging può essere minimo, ma deve includere tutti i componenti di sistema e la logica di business. Dovrebbe funzionare in modo simile alla produzione e consentire di testare le versioni al di fuori della produzione. Idealmente, l’ambiente di staging può essere connesso agli ambienti di test di Adobe Pass Adobe per l’utilizzo da parte del programmatore e, se necessario, per assistenza nella fase di test e risoluzione dei problemi.
Requisiti funzionali
Il servizio Programmatore deve trasmettere informazioni accurate sull’identificazione del dispositivo per il quale sta eseguendo i flussi. Inoltre, il servizio Programmer deve trasmettere l’IP del dispositivo per il quale sta eseguendo i flussi (in un’intestazione x-forwarded-for) insieme alla porta di origine della connessione (nel campo device info (informazioni sul dispositivo)):
**X-Forwarded-For: \<client\_ip\>**
dove \<client\_ip\> è l'indirizzo IP pubblico del client
L'intestazione deve essere aggiunta nelle chiamate **regcode** e **authorize**
Esempi:
POST /reggie/v1/{req\_id}/regcode HTTP/1.1
X-Forwarded-For:203.45.101.20
GET/api/v1/authorize HTTP/1.1
X-Forwarded-For:203.45.101.20
Il servizio Programmer deve inviare i dati e la formattazione richiesti dai singoli MVPD o dalle app integrate (ad esempio, IP dispositivo, porta di origine, informazioni dispositivo, MRSS, dati opzionali come ECID). .
Il servizio Programmer deve rispettare i TTL authN e authZ durante il caching e annullare la validità delle sessioni authN o authZ quando riceve la notifica.
Il programmatore deve mantenere i certificati condivisi con Adobe.