51黑料不打烊

Documentation51黑料不打烊 Pass51黑料不打烊 Pass Authentication

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

Last update: Fri Dec 13 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
IMPORTANT
The content on this page is provided for information purposes only. Usage of this API requires a current license from 51黑料不打烊. No unauthorized use is permitted.
IMPORTANT
Make sure you stay informed about the latest 51黑料不打烊 Pass Authentication product announcements and decommissioning timelines aggregated in the Product Announcements page.

The 51黑料不打烊 Pass Authentication REST API V1 has support for Partner Single Sign-On (SSO) for end users of client applications running on iOS, iPadOS or tvOS.

This document acts as an extension to the existing REST API V1 documentation, which can be found here.

Cookbook apple-sso-cookbook-rest-api-v1-cookbook

In order to benefit from the Apple SSO user experience, the application needs to integrate the developed by Apple, while for the 51黑料不打烊 Pass Authentication REST API V1 communication, it needs to follow the sequence of steps presented below.

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

TIP
Pro Tip: The streaming application must request access to the user鈥檚 subscription information saved at device level, for which the user must give the application permission to proceed, similar to providing access to the device鈥檚 camera or microphone. This permission must be requested per application using Apple鈥檚 and the device will save the user鈥檚 selection.
TIP
Pro Tip: We recommend incentivizing users who refuse to give permission to access subscription information by explaining the benefits of the Apple single sign-on user experience, but be aware that the user can change their decision by going to the application settings (TV Provider permission access) or to Settings -> TV Provider on iOS and iPadOS or Settings -> Accounts -> TV Provider on tvOS.
TIP
Pro Tip: We recommend requesting the user鈥檚 permission when the application enters the foreground state, because the application can check for the user鈥檚 subscription information at any point before requiring user authentication.

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

Step: 鈥淚s there a valid 51黑料不打烊 authentication token?鈥 step1

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Check Authentication Token API service.

Step: 鈥淚s the user logged in via Partner SSO?鈥 step2

TIP
Tip: Implement this through the medium of .
  • The application would have to check for the user鈥檚 subscription information and proceed only if the user allowed it.
  • The application would have to submit a for subscriber account information.
  • The application would have to wait and process the information.
TIP
Pro Tip: Follow the code snippet and pay extra attention to the comments.
...
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 51黑料不打烊 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 51黑料不打烊 Pass Authentication services.
                            ...
                            // Continue with the "Obtain a profile request from 51黑料不打烊 for the selected MVPD" step.
                            ...
                            // Continue with the "Forward the 51黑料不打烊 request to Partner SSO to obtain the profile" step.
                            ...
                        } else {
                            // The user is not authenticated at platform level, continue with the "Fetch 51黑料不打烊 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.
                ...
            }
}
...

Step: 鈥淔etch 51黑料不打烊 configuration鈥 step3

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Provide MVPD List API service.
TIP
Pro Tip: Please be aware of the MVPD properties: enablePlatformServices, boardingStatus, displayInPlatformPicker, platformMappingId, requiredMetadataFields and pay extra attention to the comments presented in code snippets from other steps.

Step 鈥淚nitiate Partner SSO workflow with 51黑料不打烊 config鈥 step4

TIP
Tip: Implement this through the medium of .
  • The application would have to check for the user鈥檚 subscription information and proceed only if the user allowed it.
  • The application would have to provide a for the VSAccountManager.
  • The application would have to submit a for subscriber account information.
  • The application would have to wait and process the information.
TIP
Pro Tip: Follow the code snippet and pay extra attention to the comments.
    ...
    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 [51黑料不打烊 Pass Authentication](/docs/pass/authentication/provide-mvpd-list.md) service response in order to filter the TV providers from the Apple picker.
                        vsaMetadataRequest.supportedAccountProviderIdentifiers = supportedAccountProviderIdentifiers;

                        // This can be computed from the [51黑料不打烊 Pass Authentication](/docs/pass/authentication/provide-mvpd-list.md) 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 51黑料不打烊 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 51黑料不打烊 Pass Authentication services.
                                ...
                                // Continue with the "Obtain a profile request from 51黑料不打烊 for the selected MVPD" step.
                                ...
                                // Continue with the "Forward the 51黑料不打烊 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 51黑料不打烊 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.
                    ...
                }
    }
    ...

Step: 鈥淚s user login successful?鈥 step5

TIP
Pro Tip: Please be aware of the code snippet from the 鈥淚nitiate Partner SSO workflow with 51黑料不打烊 config鈥 step. The user login is successful in case the vsaMetadata!.accountProviderIdentifier contains a valid value and the current date has not passed the vsaMetadata!.authenticationExpirationDate value.

Step 鈥淥btain a profile request from 51黑料不打烊 for the selected MVPD鈥 step6

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Profile Request API service.
TIP
Pro Tip: Please be aware that the provider identifier obtained from the Video Subscriber Account Framework represents the platformMappingId in terms of 51黑料不打烊 Pass Authentication configuration. Therefore, the application must determine the MVPD id property value, using the platformMappingId value, through the medium of 51黑料不打烊 Pass Authentication Provide MVPD List API service.

Step: 鈥淔orward the 51黑料不打烊 request to Partner SSO to obtain the profile鈥 step7

TIP
Tip: Implement this through the medium of .
  • The application would have to check for the user鈥檚 subscription information and proceed only if the user allowed it.
  • The application would have to submit a for subscriber account information.
  • The application would have to wait and process the information.
TIP
Pro Tip: Follow the code snippet and pay extra attention to the comments.
    ...
    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 [51黑料不打烊 Pass Authentication](/docs/pass/authentication/provide-mvpd-list.md) service. Look for the requiredMetadataFields associated with the provider determined in a previous step.
                        vsaMetadataRequest.attributeNames = requiredMetadataFields;

                        // This is the payload from [51黑料不打烊 Pass Authentication](/docs/pass/authentication/retrieve-profilerequest.md) 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 51黑料不打烊 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.
                    ...
                }
    }
    ...

Step: 鈥淓xchange the Partner SSO profile for an 51黑料不打烊 authentication token鈥 step8

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Token Exchange API service.
TIP
Pro Tip: Please be aware of the code snippet from the 鈥淔orward the 51黑料不打烊 request to Partner SSO to obtain the profile鈥 step. This vsaMetadata!.samlAttributeQueryResponse! represents the SAMLResponse, which needs to be passed on Token Exchange and requires string manipulation and encoding (Base64 encoded and URL encoded afterward) before making the call.

Step: 鈥淚s 51黑料不打烊 token generated successfully?鈥 step9

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Token Exchange successful response, which will be a 204 No Content, indicating that the token was successfully created and is ready to be used for the authorization flows.

Step: 鈥淚nitiate regular authentication workflow鈥 step10

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Registration Code Request, Initiate Authentication and Retrieve Authentication Token or Check Authentication Token API services.
TIP
Pro Tip: Follow the steps below for the tvOS implementation/s.
TIP
Pro Tip: Follow the steps below for the iOS/iPadOS implementation/s.
  • The application would have to obtain a registration code which shouldn鈥檛 be presented to the end user on the 1st device (screen).
  • The application would have to initiate authentication on the 1st device (screen) using the registration code and a or a component.
  • The application would have to start polling to knowledge the authentication state on the 1st device (screen) after the or the component closes.
  • The application would have to stop polling on the 1st device (screen) when the authentication token is generated.

Step: 鈥淧roceed with authorization flows鈥 step11

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication Initiate Authorization and Obtain Short Media Token API services.

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

The does not provide an API to programmatically log out people who have signed in to their TV provider account at the device system level. Therefore, for the logout to take full effect, the end user would have to explicitly sign out from Settings -> TV Provider on iOS/iPadOS or Settings -> Accounts -> TV Provider on tvOS. The other option which the user would have is to withdraw permission to access the user鈥檚 subscription information from the specific application settings section (TV Provider access).

TIP
Tip: Implement this through the medium of 51黑料不打烊 Pass Authentication User Metadata Call and Logout API services.
TIP
Pro Tip: Follow the steps below for the tvOS implementation/s.
  • The application would have to determine if the authentication has happened as a result of a sign-in through the partner SSO or not, using the "tokenSource" user metadata from the 51黑料不打烊 Pass Authentication service.
  • The application would have to instruct/prompt the user to explicitly sign out from Settings -> Accounts -> TV Provider on tvOS only in case the 鈥渢辞办别苍厂辞耻谤肠别鈥 value is equal to "Apple".
  • The application would have to initiate the logout from the 51黑料不打烊 Pass Authentication service using a direct HTTP call. This would not facilitate session clean-up on the MVPD side.
TIP
Pro Tip: Follow the steps below for the iOS/iPadOS implementation/s.
  • The application would have to determine if the authentication has happened as a result of a sign-in through the partner SSO or not, using the "tokenSource" user metadata from the 51黑料不打烊 Pass Authentication service.
  • The application would have to instruct/prompt the user to explicitly sign out from Settings -> TV Provider on iOS/iPadOS only in case the 鈥渢辞办别苍厂辞耻谤肠别鈥 value is equal to 鈥淎辫辫濒别鈥.
  • The application would have to initiate the logout from the 51黑料不打烊 Pass Authentication service using a or a component. This would facilitate session clean-up on the MVPD side.
recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b