Guía de Apple SSO (API de REST) apple-sso-cookbook-rest-api
Introducción Introduction
La API de REST de autenticación de Adobe Pass puede admitir la autenticación de inicio de sesión único (SSO) de la plataforma para los usuarios finales de aplicaciones cliente que se ejecutan en iOS, iPadOS o tvOS a través de lo que llamamos flujo de trabajo de SSO de Apple.
Tenga en cuenta que este documento actúa como una extensión de la documentación de la API de REST existente, que se puede encontrar aquí.
Libros Cookbooks
Para beneficiarse de la experiencia del usuario de SSO de Apple, una aplicación necesitaría integrar la plataforma de cuenta de suscriptor de vídeo desarrollada por Apple, mientras que en cuanto a la comunicación de la API de REST de autenticación de Adobe Pass, tendría que seguir la secuencia de sugerencias presentadas a continuación.
Autenticación Authentication
- ¿Hay un token de autenticación de Adobe válido?
- ¿El usuario ha iniciado sesión mediante el SSO de Platform?
- Recuperar configuración de Adobe
- Inicio del flujo de trabajo de Platform SSO con configuración de Adobe
- ¿El usuario ha iniciado sesión correctamente?
- Obtener una solicitud de perfil del Adobe para la MVPD seleccionada
- Reenviar la solicitud de Adobe a Platform SSO para obtener el perfil
- Intercambio del perfil SSO de Platform por un token de autenticación de Adobe
- ¿Se ha generado correctamente el token de Adobe?
- Iniciar flujo de trabajo de autenticación de segunda pantalla
- Continuar con flujos de autorización
Paso: "¿Hay un token de autenticación de Adobe válido?" Is_there_a_valid_Adobe_authentication_token
Paso: "¿El usuario ha iniciado sesión mediante el SSO de Platform?" Is_the_user_logged_in_via_Platform_SSO
- La aplicación tendría que comprobar si tiene permiso para acceder a la información de suscripción del usuario y continuar solo si el usuario lo permite.
- La aplicación tendría que enviar una solicitud para obtener información de la cuenta del suscriptor.
- La aplicación tendría que esperar y procesar la información de metadata.
...
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 Platform 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:
// Fallback to regular authentication workflow.
...
}
}
...
Paso: "Recuperar configuración de Adobe" Fetch_Adobe_configuration
enablePlatformServices
, boardingStatus
, displayInPlatformPicker
, platformMappingId
, requiredMetadataFields
y preste especial atención a los comentarios presentados en fragmentos de código de otros pasos.Paso "Inicio del flujo de trabajo de SSO de Platform con la configuración de Adobe" Initiate_Platform_SSO_workflow_with_Adobe_config
- La aplicación tendría que comprobar si tiene permiso para acceder a la información de suscripción del usuario y continuar solo si el usuario lo permite.
- La aplicación tendría que proporcionar un delegado para VSAccountManager.
- La aplicación tendría que enviar una solicitud para obtener información de la cuenta del suscriptor.
- La aplicación tendría que esperar y procesar la información de metadata.
...
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/restapi/rest-api-reference/provide-mvpd-list.html?lang=es) 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/restapi/rest-api-reference/provide-mvpd-list.html?lang=es) 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 Platform 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 second screen authentcation 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 second screen authentcation workflow" step.
...
}
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
Paso: "¿El inicio de sesión del usuario se ha realizado correctamente?" Is_user_login_successful
vsaMetadata!.accountProviderIdentifier
contenga un valor válido y la fecha actual no haya pasado el valor vsaMetadata!.authenticationExpirationDate
.Paso "Obtener una solicitud de perfil del Adobe para la MVPD seleccionada" Obtain_a_profile_request_from_Adobe_for_the_selected_MVPD
platformMappingId
en términos de la configuración de autenticación de Adobe Pass. Por lo tanto, la aplicación debe determinar el valor de la propiedad MVPD id, usando el valor platformMappingId
, a través del medio del servicio Autenticación de Adobe Pass Proporcionar lista MVPD.Paso: "Reenviar la solicitud de Adobe a Platform SSO para obtener el perfil" Forward_the_Adobe_request_to_Platform_SSO_to_obtain_the_profile
- La aplicación tendría que comprobar si tiene permiso para acceder a la información de suscripción del usuario y continuar solo si el usuario lo permite.
- La aplicación tendría que enviar una solicitud para obtener información de la cuenta del suscriptor.
- La aplicación tendría que esperar y procesar la información de metadata.
...
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/restapi/rest-api-reference/provide-mvpd-list.html?lang=es) 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/restapi/rest-api-reference/retrieve-profilerequest.html?lang=es) 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 Platform SSO profile for an Adobe authentication token" step.
...
} else {
// Fallback to regular authentication workflow.
...
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
Paso: "Intercambio del perfil SSO de Platform por un token de autenticación de Adobe" Exchange_the_Platform_SSO_profile_for_an_Adobe_authentication_token
vsaMetadata!.samlAttributeQueryResponse!
representa el(la) SAMLResponse
, que necesita pasarse en Intercambio de tokens y requiere manipulación de cadenas y codificación (Codificado(a) Base64 y codificado(a) URL posteriormente) antes de realizar la llamada.Paso: "¿El token de Adobe se ha generado correctamente?" Is_Adobe_token_generated_successfully
204 No Content
, lo que indica que el token se creó correctamente y está listo para utilizarse en los flujos de autorización.Paso: "Iniciar flujo de trabajo de autenticación de segunda pantalla" Initiate_second_screen_authentication_workflow
Importante: La terminología "Flujo de trabajo de autenticación de segunda pantalla" es apropiada para AppleTV, mientras que la terminología "Flujo de trabajo de autenticación de primera pantalla" / "Flujo de trabajo de autenticación regular" sería más apropiada para iPhone y iPads.
Solicitud de código de registro, Iniciar autenticación y API REST Recuperar token de autenticación o Comprobar servicios de token de autenticación.
- La aplicación tendría que obtener un código de registro y presentarlo al usuario final en el primer dispositivo (pantalla).
- La aplicación tendría que iniciar sondeo para confirmar el estado de autenticación en el primer dispositivo (pantalla) después de obtener el código de registro.
- Otra aplicación tendría que iniciar autenticación en un segundo dispositivo (pantalla) cuando se use el código de registro.
- La aplicación tendría que detener el sondeo en el primer dispositivo (pantalla) cuando se genere el token de autenticación.
- La aplicación tendría que obtener un código de registro que no debería presentarse al usuario final en el primer dispositivo (pantalla).
- La aplicación tendría que iniciar la autenticación en el primer dispositivo (pantalla) usando el código de registro y un componente WKWebView o SFSafariViewController.
- La aplicación tendría que iniciar sondeo para conocer el estado de autenticación en el primer dispositivo (pantalla) después de que se cierre WKWebView o el componente SFSafariViewController.
- La aplicación tendría que detener el sondeo en el primer dispositivo (pantalla) cuando se genere el token de autenticación.
Paso: "Continuar con los flujos de autorización" Proceed_with_authorization_flows
Cerrar sesión Logout
El marco de trabajo de la cuenta de suscriptor de vídeo Video Subscriber Account no proporciona una API para cerrar la sesión mediante programación de las personas que han iniciado sesión en su cuenta de proveedor de TV en el nivel del sistema del dispositivo. Por lo tanto, para que el cierre de sesión surta efecto, el usuario final tendría que cerrar sesión explícitamente desde Settings -> TV Provider
en iOS/iPadOS o Settings -> Accounts -> TV Provider
en tvOS. La otra opción que tendría el usuario es retirar el permiso para acceder a la información de suscripción del usuario desde la sección de configuración específica de la aplicación (acceso al proveedor de TV).
- La aplicación tendría que determinar si la autenticación se ha producido como resultado de un inicio de sesión a través del SSO de la plataforma o no, utilizando los "tokenSource" metadatos de usuario del servicio de autenticación de Adobe Pass.
- La aplicación tendría que indicar o pedir al usuario que cierre sesión explícitamente desde
Settings -> Accounts -> TV Provider
en tvOS solo en caso de que el valor "tokenSource" sea igual a "Apple". - La aplicación tendría que iniciar el cierre de sesión desde el servicio de autenticación de Adobe Pass usando una llamada HTTP directa. Esto no facilitaría la limpieza de la sesión en el lado de MVPD.
- La aplicación tendría que determinar si la autenticación se ha producido como resultado de un inicio de sesión a través del SSO de la plataforma o no, utilizando los "tokenSource" metadatos de usuario del servicio de autenticación de Adobe Pass.
- La aplicación tendría que indicar o pedir al usuario que cierre sesión explícitamente desde
Settings -> TV Provider
en iOS/iPadOS solo en caso de que el valor "tokenSource" sea igual a "Apple". - La aplicación tendría que iniciar el cierre de sesión desde el servicio de autenticación de Adobe Pass usando un WKWebView o un componente SFSafariViewController. Esto facilitaría la limpieza de la sesión en el lado de MVPD.