Manuale Apple SSO (REST API V1) apple-sso-cookbook-rest-api-v1

IMPORTANT
Il contenuto di questa pagina viene fornito solo a scopo informativo. L’utilizzo di questa API richiede una licenza corrente da Adobe. Non è consentito alcun uso non autorizzato.

L’API REST per l’autenticazione di Adobe Pass V1 supporta il Single Sign-On (SSO) dei partner per gli utenti finali delle applicazioni client in esecuzione su iOS, iPadOS o tvOS.

Questo documento funge da estensione della documentazione API REST V1 esistente, disponibile qui.

Manuale apple-sso-cookbook-rest-api-v1-cookbook

Per beneficiare dell'esperienza utente SSO di Apple, l'applicazione deve integrare il Video Subscriber Account Framework sviluppato da Apple, mentre per la comunicazione REST API V1 di autenticazione Adobe Pass, deve seguire la sequenza di passaggi descritta di seguito.

Autorizzazione apple-sso-cookbook-rest-api-v1-permission

TIP
Suggerimento pro: L'applicazione di streaming deve richiedere l'accesso alle informazioni di abbonamento dell'utente salvate a livello di dispositivo, per le quali l'utente deve concedere all'applicazione l'autorizzazione per continuare, in modo analogo a fornire l'accesso alla fotocamera o al microfono del dispositivo. Questa autorizzazione deve essere richiesta per applicazione utilizzando il framework dell'account dell'utente con sottoscrizione video di Apple e il dispositivo salverà la selezione dell'utente.
TIP
Suggerimento pro: si consiglia di incentivare gli utenti che rifiutano di concedere l'autorizzazione per accedere alle informazioni sull'abbonamento illustrando i vantaggi dell'esperienza utente Single Sign-On di Apple, ma è bene tenere presente che l'utente può modificare la propria decisione accedendo alle impostazioni dell'applicazione (autorizzazione del provider TV) o a Settings -> TV Provider su iOS e iPadOS o Settings -> Accounts -> TV Provider su tvOS.
TIP
Suggerimento pro: è consigliabile richiedere l'autorizzazione dell'utente quando l'applicazione entra in primo piano, in quanto l'applicazione può verificare la presenza di autorizzazioni per accedere alle informazioni di sottoscrizione dell'utente in qualsiasi momento prima di richiedere l'autenticazione dell'utente.

Autenticazione apple-sso-cookbook-rest-api-v1-authentication

Passaggio: "Esiste un token di autenticazione Adobe valido?" step1

TIP
Suggerimento: implementalo tramite il servizio API Controlla token di autenticazione di Adobe Pass Authentication.

Passaggio: "L’utente ha effettuato l’accesso tramite SSO partner?" step2

TIP
Suggerimento: implementare questa impostazione tramite Video Subscriber Account Framework.
  • L'applicazione dovrebbe verificare la presenza di autorizzazioni per accedere alle informazioni di sottoscrizione dell'utente e procedere solo se l'utente lo consente.
  • L'applicazione dovrebbe inviare una richiesta per le informazioni sull'account del sottoscrittore.
  • L'applicazione dovrebbe attendere ed elaborare le informazioni metadati.
TIP
Suggerimento pro: Segui lo snippet di codice e presta particolare attenzione ai commenti.
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();

videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
            switch (accessStatus) {
            // The user allows the application to access subscription information.
            case VSAccountAccessStatus.granted:
                    // Construct the request for subscriber account information.
                    let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();

                    // This is actually the SAML Issuer not the channel ID.
                    vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";

                    // This is the subscription account information needed at this step.
                    vsaMetadataRequest.includeAccountProviderIdentifier = true;

                    // This is the subscription account information needed at this step.
                    vsaMetadataRequest.includeAuthenticationExpirationDate = true;

                    // This is going to make the Video Subscriber Account Framework to refrain from prompting the user with the providers picker at this step.
                    vsaMetadataRequest.isInterruptionAllowed = false;

                    // Submit the request for subscriber account information - accountProviderIdentifier.
                    videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
                        if (vsaMetadata != nil && vsaMetadata!.accountProviderIdentifier != nil) {
                            // The vsaMetadata!.authenticationExpirationDate will contain the expiration date for current authentication session.
                            // The vsaMetadata!.authenticationExpirationDate should be compared against current date.
                            ...
                            // The vsaMetadata!.accountProviderIdentifier will contain the provider identifier as it is known for the platform configuration.
                            // The vsaMetadata!.accountProviderIdentifier represents the platformMappingId in terms of Adobe Pass Authentication configuration.
                            ...
                            // The application must determine the MVPD id property value based on the platformMappingId property value obtained above.
                            // The application must use the MVPD id further in its communication with Adobe Pass Authentication services.
                            ...
                            // Continue with the "Obtain a profile request from Adobe for the selected MVPD" step.
                            ...
                            // Continue with the "Forward the Adobe request to Partner SSO to obtain the profile" step.
                            ...
                        } else {
                            // The user is not authenticated at platform level, continue with the "Fetch Adobe configuration" step.
                            ...
                        }
                    }

            // The user has not yet made a choice or does not allow the application to access subscription information.
            default:
                // Continue with the "Initiate regular authentication workflow" step.
                ...
            }
}
...

Passaggio: "Recupera la configurazione di Adobe" step3

TIP
Suggerimento: implementarlo tramite l'autenticazione Adobe Pass Fornire il servizio API Elenco MVPD.
TIP
Suggerimento pro: Tieni presente le proprietà MVPD: enablePlatformServices, boardingStatus, displayInPlatformPicker, platformMappingId, requiredMetadataFields e presta particolare attenzione ai commenti presentati nei frammenti di codice di altri passaggi.

Passaggio "Avviare il flusso di lavoro SSO del partner con Adobe config" step4

TIP
Suggerimento: implementare questa impostazione tramite Video Subscriber Account Framework.
  • L'applicazione dovrebbe verificare la presenza di autorizzazioni per accedere alle informazioni di sottoscrizione dell'utente e procedere solo se l'utente lo consente.
  • L'applicazione deve fornire un delegato per VSAccountManager.
  • L'applicazione dovrebbe inviare una richiesta per le informazioni sull'account del sottoscrittore.
  • L'applicazione dovrebbe attendere ed elaborare le informazioni metadati.
TIP
Suggerimento pro: Segui lo snippet di codice e presta particolare attenzione ai commenti.
    ...
    let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();

    // This must be a class implementing the VSAccountManagerDelegate protocol.
    let videoSubscriberAccountManagerDelegate: VideoSubscriberAccountManagerDelegate = VideoSubscriberAccountManagerDelegate();

    videoSubscriberAccountManager.delegate = videoSubscriberAccountManagerDelegate;

    videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
                switch (accessStatus) {
                // The user allows the application to access subscription information.
                case VSAccountAccessStatus.granted:
                        // Construct the request for subscriber account information.
                        let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();

                        // This is actually the SAML Issuer not the channel ID.
                        vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";

                        // This is the subscription account information needed at this step.
                        vsaMetadataRequest.includeAccountProviderIdentifier = true;

                        // This is the subscription account information needed at this step.
                        vsaMetadataRequest.includeAuthenticationExpirationDate = true;

                        // This is going to make the Video Subscriber Account Framework to prompt the user with the providers picker at this step.
                        vsaMetadataRequest.isInterruptionAllowed = true;

                        // This can be computed from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/rest-api-v1/rest-api-reference/provide-mvpd-list.html?lang=it) service response in order to filter the TV providers from the Apple picker.
                        vsaMetadataRequest.supportedAccountProviderIdentifiers = supportedAccountProviderIdentifiers;

                        // This can be computed from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/rest-api-v1/rest-api-reference/provide-mvpd-list.html?lang=it) service response in order to sort the TV providers from the Apple picker.
                        if #available(iOS 11.0, tvOS 11, *) {
                            vsaMetadataRequest.featuredAccountProviderIdentifiers = featuredAccountProviderIdentifiers;
                        }

                        // Submit the request for subscriber account information - accountProviderIdentifier.
                        videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
                            // This represents the checks for the "Is user login successful?" step.
                            if (vsaMetadata != nil && vsaMetadata!.accountProviderIdentifier != nil) {
                                // The vsaMetadata!.authenticationExpirationDate will contain the expiration date for current authentication session.
                                // The vsaMetadata!.authenticationExpirationDate should be compared against current date.
                                ...
                                // The vsaMetadata!.accountProviderIdentifier will contain the provider identifier as it is known for the platform configuration.
                                // The vsaMetadata!.accountProviderIdentifier represents the platformMappingId in terms of Adobe Pass Authentication configuration.
                                ...
                                // The application must determine the MVPD id property value based on the platformMappingId property value obtained above.
                                // The application must use the MVPD id further in its communication with Adobe Pass Authentication services.
                                ...
                                // Continue with the "Obtain a profile request from Adobe for the selected MVPD" step.
                                ...
                                // Continue with the "Forward the Adobe request to Partner SSO to obtain the profile" step.
                                ...
                            } else {
                                // The user is not authenticated at platform level.
                                if (vsaError != nil) {
                                    // The application can check to see if the user selected a provider which is present in Apple picker, but the provider is not onboarded in platform SSO.
                                    if let error: NSError = (vsaError! as NSError), error.code == 1, let appleMsoId = error.userInfo["VSErrorInfoKeyUnsupportedProviderIdentifier"] as! String? {
                                        var mvpd: Mvpd? = nil;

                                        // The requestor.mvpds must be computed during the "Fetch Adobe configuration" step.
                                        for provider in requestor.mvpds {
                                            if provider.platformMappingId == appleMsoId {
                                                mvpd = provider;
                                                break;
                                            }
                                        }

                                        if mvpd != nil {
                                            // Continue with the "Initiate regular authentication workflow" step, but you can skip prompting the user with your MVPD picker and use the mvpd selection, therefore creating a better UX.
                                            ...
                                        } else {
                                            // Continue with the "Initiate regular authentication workflow" step.
                                            ...
                                        }
                                    } else {
                                        // Continue with the "Initiate regular authentication workflow" step.
                                        ...
                                    }
                                } else {
                                    // Continue with the "Initiate regular authentication workflow" step.
                                    ...
                                }
                            }
                        }

                // The user has not yet made a choice or does not allow the application to access subscription information.
                default:
                    // Continue with the "Initiate regular authentication workflow" step.
                    ...
                }
    }
    ...

Passaggio: "L’accesso dell’utente è riuscito?" step5

TIP
Suggerimento pro: Tieni presente lo snippet di codice del passaggio "Avvia SSO partner con Adobe config". L'accesso utente ha esito positivo nel caso in cui vsaMetadata!.accountProviderIdentifier contenga un valore valido e la data corrente non abbia superato il valore vsaMetadata!.authenticationExpirationDate.

Passaggio "Ottenere una richiesta di profilo da Adobe per l’MVPD selezionato" step6

TIP
Suggerimento: implementalo tramite il servizio API Richiesta profilo di autenticazione Adobe Pass.
TIP
Suggerimento pro: l'identificatore del provider ottenuto dal framework dell'account del sottoscrittore video rappresenta platformMappingId in termini di configurazione dell'autenticazione Adobe Pass. Pertanto, l'applicazione deve determinare il valore della proprietà ID MVPD, utilizzando il valore platformMappingId, tramite il servizio API Autenticazione Adobe Pass Fornisci elenco MVPD.

Passaggio: "Inoltra la richiesta Adobe all’SSO partner per ottenere il profilo" step7

TIP
Suggerimento: implementare questa impostazione tramite Video Subscriber Account Framework.
  • L'applicazione dovrebbe verificare la presenza di autorizzazioni per accedere alle informazioni di sottoscrizione dell'utente e procedere solo se l'utente lo consente.
  • L'applicazione dovrebbe inviare una richiesta per le informazioni sull'account del sottoscrittore.
  • L'applicazione dovrebbe attendere ed elaborare le informazioni metadati.
TIP
Suggerimento pro: Segui lo snippet di codice e presta particolare attenzione ai commenti.
    ...
    let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();

    videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
                switch (accessStatus) {
                // The user allows the application to access subscription information.
                case VSAccountAccessStatus.granted:
                        // Construct the request for subscriber account information.
                        let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();

                        // This is actually the SAML Issuer not the channel ID.
                        vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";

                        // This is going to include subscription account information which should match the provider determined in a previous step.
                        vsaMetadataRequest.includeAccountProviderIdentifier = true;

                        // This is going to include subscription account information which should match the provider determined in a previous step.
                        vsaMetadataRequest.includeAuthenticationExpirationDate = true;

                        // This is going to make the Video Subscriber Account Framework to refrain from prompting the user with the providers picker at this step.
                        vsaMetadataRequest.isInterruptionAllowed = false;

                        // This are the user metadata fields expected to be available on a successful login and are determined from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/rest-api-v1/rest-api-reference/provide-mvpd-list.html?lang=it) service. Look for the requiredMetadataFields associated with the provider determined in a previous step.
                        vsaMetadataRequest.attributeNames = requiredMetadataFields;

                        // This is the payload from [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/rest-api-v1/rest-api-reference/retrieve-profilerequest.html?lang=it) service.
                        vsaMetadataRequest.verificationToken = profileRequestPayload;

                        // Submit the request for subscriber account information.
                        videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
                            if (vsaMetadata != nil && vsaMetadata!.samlAttributeQueryResponse != nil) {
                                var samlResponse: String? = vsaMetadata!.samlAttributeQueryResponse!;

                                // Remove new lines, new tabs and spaces.
                                samlResponse = samlResponse?.replacingOccurrences(of: "[ \\t]+", with: " ", options: String.CompareOptions.regularExpression);
                                samlResponse = samlResponse?.components(separatedBy: CharacterSet.newlines).joined(separator: "");
                                samlResponse = samlResponse?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines);

                                // Base64 encode.
                                samlResponse = samlResponse?.data(using: .utf8)?.base64EncodedString(options: []);

                                // URL encode. Please be aware not to double URL encode it further.
                                samlResponse = samlResponse?.addingPercentEncoding(withAllowedCharacters: CharacterSet.init(charactersIn: "!*'();:@&=+$,/?%#[]").inverted);

                                // Continue with the "Exchange the Partner SSO profile for an Adobe authentication token" step.
                                ...
                            } else {
                                // Continue with the "Initiate regular authentication workflow" step.
                                ...
                            }
                        }

                // The user has not yet made a choice or does not allow the application to access subscription information.
                default:
                    // Continue with the "Initiate regular authentication workflow" step.
                    ...
                }
    }
    ...

Passaggio: "Sostituire il profilo SSO partner con un token di autenticazione Adobe" step8

TIP
Suggerimento: implementalo tramite il servizio API Token Exchange di autenticazione di Adobe Pass.
TIP
Suggerimento pro: Tieni presente il frammento di codice dal passaggio "Inoltra la richiesta Adobe all'SSO partner per ottenere il profilo". vsaMetadata!.samlAttributeQueryResponse! rappresenta SAMLResponse, che deve essere passato a Token Exchange e richiede la manipolazione delle stringhe e la codifica (Base64 codificata e URL codificata successivamente) prima di effettuare la chiamata.

Passaggio: "Il token Adobe è stato generato correttamente?" step9

TIP
Suggerimento: implementalo tramite la risposta corretta di autenticazione di Adobe Pass Scambio token, che sarà un 204 No Content, che indica che il token è stato creato correttamente ed è pronto per essere utilizzato per i flussi di autorizzazione.

Passaggio: "Avvia flusso di lavoro di autenticazione regolare" step10

TIP
Suggerimento: implementare questa impostazione tramite l'autenticazione Adobe Pass Richiesta codice di registrazione, Avvia autenticazione e Recupera token di autenticazione o Controlla i servizi API del token di autenticazione.
TIP
Suggerimento pro: Segui i passaggi seguenti per le implementazioni tvOS.
TIP
Suggerimento pro: Segui i passaggi indicati di seguito per l'implementazione iOS/iPadOS.

Passaggio: "Procedi con i flussi di autorizzazione" step11

TIP
Suggerimento: implementalo tramite l'autenticazione Adobe Pass Avvia autorizzazione e Ottieni token di file multimediali brevi servizi API.

Disconnetti apple-sso-cookbook-rest-api-v1-logout

Il framework dell'account del sottoscrittore video 1} non fornisce un'API per disconnettere a livello di programmazione gli utenti che hanno effettuato l'accesso al proprio account del provider TV a livello di sistema del dispositivo.Pertanto, affinché la disconnessione diventi effettiva, l'utente finale dovrà disconnettersi esplicitamente da Settings -> TV Provider su iOS/iPadOS o da Settings -> Accounts -> TV Provider su tvOS. L'altra opzione che l'utente avrebbe è quella di revocare l'autorizzazione per accedere alle informazioni sull'abbonamento dell'utente dalla sezione delle impostazioni specifiche dell'applicazione (accesso al provider TV).

TIP
Suggerimento: implementare questa impostazione tramite la chiamata metadati utente e i servizi API Logout per l'autenticazione di Adobe Pass.
TIP
Suggerimento pro: Segui i passaggi seguenti per le implementazioni tvOS.
  • L'applicazione dovrebbe determinare se l'autenticazione è avvenuta a seguito di un accesso tramite l'SSO partner o meno, utilizzando "tokenSource" metadati utente dal servizio di autenticazione di Adobe Pass.
  • L'applicazione dovrebbe indicare/richiedere all'utente di disconnettersi esplicitamente da Settings -> Accounts -> TV Provider in tvOS only se il valore "tokenSource" è uguale a "Apple".
  • L'applicazione dovrebbe avviare la disconnessione dal servizio di autenticazione di Adobe Pass utilizzando una chiamata HTTP diretta. Ciò non faciliterebbe la pulizia delle sessioni da parte di MVPD.
TIP
Suggerimento pro: Segui i passaggi indicati di seguito per l'implementazione iOS/iPadOS.
  • L'applicazione dovrebbe determinare se l'autenticazione è avvenuta a seguito di un accesso tramite l'SSO partner o meno, utilizzando "tokenSource" metadati utente dal servizio di autenticazione di Adobe Pass.
  • L'applicazione dovrebbe indicare/richiedere all'utente di disconnettersi esplicitamente da Settings -> TV Provider su iOS/iPadOS only nel caso in cui il valore "tokenSource" sia uguale a "Apple".
  • L'applicazione deve avviare la disconnessione dal servizio di autenticazione di Adobe Pass utilizzando un componente WKWebView o SFSafariViewController. Questo faciliterebbe la pulizia delle sessioni da parte di MVPD.
recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b