REST API Cookbook (Server-to-Server) rest-api-cookbook-server-to-server
Ökning overview
Syftet med detta kokboksdokument är att beskriva bästa praxis för implementering av Adobe Pass-autentisering med Server-till-Server-arkitekturer. Den innehåller grundläggande krav, stegvis implementering av flöde och allmänna överväganden för produktionsmiljöer och drift.
Begränsningsmekanism
REST-API:t för Adobe Pass-autentisering styrs av en begränsningsmekanism.
Komponenter components
I en fungerande Server-till-Server-lösning ingår följande komponenter:
Ytterligare termer som används i flödet definieras i
Ordlista.
Flöden flows
Dynamic Client Registration (DCR)
Adobe Pass använder DCR för att säkra klientkommunikationen mellan ett programmeringsprogram eller en server och Adobe Pass tjänster. DCR-flödet är separat, beroende och nödvändigt och finns i Dynamisk klientregistrering.
Autentisering (authN)
Autentiseringsflödet används för att tillåta en användare att identifiera sig
till deras MVPD för att avgöra om användaren har ett giltigt konto.
- Användaren startar appen Streaming Device och försöker logga in eller visa skyddat innehåll.
- Strömningsenhetens app begär att programmeringstjänsten ska avgöra om enheten redan är autentiserad.
- Programmerartjänsten registrerar programmet med DCR.
- Programmerartjänsten kontrollerar direktuppspelningsenhetens authN-status genom att anropa Adobe Pass-tjänstens checkauthn-API.
- Om checkauthn-anropet returnerar statusen som användarenheten är autentiserad kan programmet fortsätta till auktoriseringsflödet.
- Om checkauthn-anropet returnerar statusen att användarenheten INTE är autentiserad bör programmet vänta på att en användarbegäran ska logga in.
- När användaren begär direkt inloggning (t.ex. väljer inloggningsknapp) eller indirekt inloggning (t.ex. väljer skyddat innehåll när det inte redan är autentiserat), skickar strömningsenhetens app en begäran till programmeringstjänsten om att initiera användarautentisering. Programmerartjänsten begär och tar emot en unik registreringskod (regcode) genom att anropa Adobe Pass-tjänstens regcode-API.
- Programmeringstjänsten hämtar även listan över aktuella MVPD-filer och attribut genom att anropa Adobe Pass Service config API. Obs! Detta API kan också anropas tidigare i flödet och cachelagras.
- Programmerartjänsten returnerar regcode till Streaming Device-appen och den bearbetade MVPD-listan som begärdes i steg #7. Obs! Det bearbetade formatet för MVPD-listan anges av Programmer och kan filtreras så att specifika MVPD-filer tillåts eller blockeras (dvs. allow- eller block-lists).
- Om enheten skiljer sig från AuthN-enheten (d.v.s."andra skärmen"), antingen efter val eller behov (d.v.s. direktuppspelningsenheten saknar stöd för en användaragent), ska direktuppspelningsenheten visa regcode och en URI som användaren kan använda för att komma åt AuthN-programmet. Användaren skriver URI:n i användaragenten på AuthN-enheten för att starta AuthN-programmet och skriver sedan in koden i det programmet. Om direktuppspelningsenheten är samma som AuthN-enheten kan regcode skickas programmatiskt till AuthN-modulen.
- AuthN-modulen initierar användarautentiseringen med MVPD genom att visa en MVPD-väljare. När användaren har valt MVPD anropar AuthN-modulen authenticate med regcode, vilket dirigerar om användaragenten till MVPD IdP. När användaren autentiserar med MVPD omdirigeras användaragenten tillbaka via Adobe Pass-tjänsten, där den lyckade autentiseringen registreras med regcode och sedan omdirigeras tillbaka till AuthN-modulen.
- Om direktuppspelningsenheten inte är samma som AuthN-enheten ska AuthN-enheten visa ett meddelande om lyckad autentisering för användaren och steg för att fortsätta (t.ex. "Success! Du kan nu gå tillbaka till spelkonsolen och fortsätta med […]"). Om direktuppspelningsenheten är densamma som AuthN-enheten kan direktuppspelningsenheten programmässigt upptäcka att autentiseringen har slutförts.
I följande diagram visas autentiseringsflödet:
Behörighet (authZ)
Auktoriseringsflödet används för att avgöra om en användare har behörighet till begärt innehåll.
- Varje gång användaren försöker visa skyddat innehåll i appen för direktuppspelningsenheten anropar appen för direktuppspelningsenheten programmeringstjänsten som identifierar innehållet och begär tillstånd och information som behövs för att starta strömmen.
- Programmerartjänsten anropar Adobe Pass Authze-API:t som skickar resurs-ID tillsammans med andra obligatoriska parametrar. Adobe-tjänsten anropar MVPD AuthZ-tjänsten med resurs-ID:t och tar emot ett auktoriseringsbeslut som sedan skickas tillbaka till programmeringstjänsten. Detta auktoriseringsbeslut cachas av Adobe Pass-tjänsten under en konfigurerbar period. Efterföljande auktorisera-anrop från Programmer-tjänsten till Adobe Pass-tjänsten returneras det cachelagrade värdet så länge det är giltigt.
- Om auktoriseringen beviljas bör programmeringstjänsten anropa API:t för Adobe Pass /tokens/media som returnerar en signerad medietoken. Programmerartjänsten bör validera medietoken med hjälp av medietokentverifieringsbiblioteket (JAR). Om det är giltigt bör programmeringstjänsten returnera behörighet och den som behövs för att starta strömmen (t.ex. strömmens URL) som begärdes i steg #1.
- Om auktoriseringen nekas returnerar anropet authenticze en felkod och beskrivning till programmeringstjänsten. Programmerartjänsten ska returnera felkoden och beskrivningen (eller ett meddelande som ändrats av programmeraren) till begäran i steg #1.
I följande diagram visas auktoriseringsflödet:
Utloggning
Med utloggningsflödet kan användaren ta bort identiteten
som är associerad med programmet.
- När användaren begär utloggning (d.v.s. tar bort det aktuella MVPD-kontot som är kopplat till programmet från enheten), anropar direktuppspelningsenhetens app programmeringstjänsten som talar om att enheten ska loggas ut.
- Programmerartjänsten ska anropa Adobe Pass logOut API.
I följande diagram visas utloggningsflödet:
[Valfritt] Förhandsauktorisering (alias Preflight)
Förhandsauktorisering kan användas för att snabbt utifrån en uppsättning resurser avgöra vilka som en användare har åtkomst till. Resultatet av det här anropet används vanligtvis för att anpassa användargränssnittet för en enskild användare.
-
När användaren har autentiserats kan styrenheten anropa programmeringstjänsten för att begära det innehåll som användaren har rätt att strömma till.
-
Programmerartjänsten ska anropa Adobe Pass preauthorized-API:t med en lista över resurs-ID:n, som är en enkel sträng som vanligtvis representerar en kanal som en användare kan ha rätt att strömma. Obs! Anropet preauthorized har konfigurerats för att begränsa listan till fem (5) resurs-ID:n. När fler än fem resurser behövs kan flera förauktorisera samtal utföras, eller så kan anropet konfigureras att acceptera fler än fem resurser med ett avtal från de olika distributörerna. Implementerare bör tänka på kostnaden för ett förauktorisera anrop både till MVPD-resurser och svarstiden för programmeraren och strukturera deras användning av anropet med omdöme.
-
Anropet preauthorized svarar på programmeringstjänsten med ett JSON-objekt som innehåller värdet TRUE eller FALSE för varje resurs-ID i begäran som anger om användaren är berättigad till den associerade kanalen eller inte. Obs! Om en MVPD inte ger ett svar för ett givet resurs-ID (t.ex. på grund av nätverksfel eller timeout), används standardvärdet FALSE.
-
Programmeringstjänsten bör använda anropssvaret preauthorized för att skapa ett programmeringsdefinierat anpassat svar på direktuppspelningsenheten, vanligtvis för att anpassa presentationen för användaren utifrån deras rättigheter.
I följande diagram visas förauktoriseringsflödet:
[Valfritt]-metadata
Metadata kan användas för att hämta användarinformation som delas av MVPD.
Exempel på detta kan vara användar-ID, postnummer osv.
-
När användaren har autentiserats kan programmeringstjänsten anropa Adobe Pass usermetadata -API:t för att begära information om den autentiserade användaren.
-
Svaret innehåller alla metadata som är tillgängliga för den angivna användaren. De specifika fälten konfigureras separat för varje programmerare/MVPD-integrering.
I följande diagram visas förauktoriseringsflödet:
Miljö och funktionskrav environments
En programmerare bör skapa minst två miljöer: en för produktion och en eller flera för mellanlagring.
Produktion
Produktionsmiljön bör vara mycket tillgänglig och skalad på lämpligt sätt för stora eller oväntade toppar (t.ex. live-sporter, krossa
nyheter).
Adobe Pass-tjänsten körs på flera datacenter som är geografiskt spridda i hela USA. För att få bästa svarstid (dvs. lägsta svarstid) från Adobe Pass-tjänsten bör Programmeraren även skapa en liknande geografiskt spridd tjänst
infrastruktur.
Programmerartjänsten bör begränsa DNS-cachen till högst 30 sekunder om Adobe behöver dirigera om trafiken. Detta kan inträffa om ett datacenter blir otillgängligt.
Programmeraren ska tillhandahålla produktionsmiljöns offentliga IP-intervall. Dessa kommer att ingå i en tillåten lista över IP-adresser i Adobe Pass-infrastruktur för åtkomst och hanteras av Adobe användningspolicyer för rättvisa API.
Mellanlagring
Mellanlagringsmiljön kan vara minimal, men bör innehålla alla systemkomponenter och affärslogik. Den bör fungera på liknande sätt som produktionen och göra det möjligt att testa releaser utanför produktionen. I idealfallet kan mellanlagringsmiljön anslutas till Adobe Pass testmiljöer som kan användas av Programmer och av Adobe vid behov så att vi kan hjälpa till med testning och felsökning.
Funktionskrav
Programmerartjänsten måste skicka korrekt enhetsidentifieringsinformation för den enhet som de kör flödena för. Programmerartjänsten måste dessutom skicka IP-adressen för den enhet som de kör flödena för (i ett x-vidarebefordrat-for-huvud) tillsammans med anslutningskällporten (i enhetsinformationsfältet):
**X-Forwarded-For: \<client\_ip\>*
där \<client\_ip\> är den offentliga IP-adressen för klienten
Rubriken måste läggas till på **regcode** och **auktorisera* anrop
Exempel:
POST /reggie/v1/{req\_id}/regcode HTTP/1.1 5}x-Forwarded-For:203.45.101.20
GET /api/v1/authorized HTTP/1.1
X-Forwarded-For:203.45.101.20
Programmerartjänsten ska skicka data och formatering som krävs av enskilda MVPD-program eller integrerade program (t.ex. enhets-IP, källport, enhetsinformation, MRSS, valfria data som ECID). .
Programmeringstjänsten måste respektera åtkomstkontrollistan authN och authZ vid cachelagring och ogiltigförklara authN- eller authZ-sessionerna när de meddelas.
Programmeraren måste behålla certifikat som delas med Adobe.