Manuale Apple SSO (REST API V1) apple-sso-cookbook-rest-api-v1
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
Settings -> TV Provider
su iOS e iPadOS o Settings -> Accounts -> TV Provider
su tvOS.Autenticazione apple-sso-cookbook-rest-api-v1-authentication
- Esiste un token di autenticazione Adobe valido?
- L’utente ha effettuato l’accesso tramite Partner SSO?
- Recupera configurazione Adobe
- Avvia flusso di lavoro SSO partner con Adobe config
- L’accesso dell’utente è riuscito?
- Ottieni una richiesta di profilo da Adobe per l’MVPD selezionato
- Inoltra la richiesta Adobe all’SSO partner per ottenere il profilo
- Scambia il profilo SSO Partner con un token di autenticazione Adobe
- Il token Adobe è stato generato correttamente?
- Avvia flusso di lavoro di autenticazione regolare
- Procedi con i flussi di autorizzazione
Passaggio: "Esiste un token di autenticazione Adobe valido?" step1
Passaggio: "L’utente ha effettuato l’accesso tramite SSO partner?" step2
- 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.
...
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
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
- 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.
...
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
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
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
- 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.
...
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
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
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
- L'applicazione dovrebbe ottenere un codice di registrazione e presentarlo all'utente finale sul primo dispositivo (schermo).
- L'applicazione deve avviare il polling per riconoscere lo stato di autenticazione sul primo dispositivo (schermo) dopo l'ottenimento del codice di registrazione.
- Un'altra applicazione dovrebbe avviare l'autenticazione su un secondo dispositivo (schermo) quando viene utilizzato il codice di registrazione.
- L'applicazione dovrebbe interrompere il polling sul primo dispositivo (schermo) quando viene generato il token di autenticazione.
- L'applicazione deve ottenere un codice di registrazione che non deve essere presentato all'utente finale sul primo dispositivo (schermo).
- L'applicazione deve avviare l'autenticazione sul primo dispositivo (schermo) utilizzando il codice di registrazione e un componente WKWebView o SFSafariViewController.
- L'applicazione dovrebbe avviare il polling per conoscere lo stato di autenticazione sul primo dispositivo (schermo) dopo la chiusura del componente WKWebView o SFSafariViewController.
- L'applicazione dovrebbe interrompere il polling sul primo dispositivo (schermo) quando viene generato il token di autenticazione.
Passaggio: "Procedi con i flussi di autorizzazione" step11
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).
- 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.
- 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.