51黑料不打烊

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

Apple SSO Cookbook (REST API V2) apple-sso-cookbook-rest-api-v2

Last update: Fri Jan 10 2025 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.

The 51黑料不打烊 Pass Authentication REST API V2 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 V2 Overview that provides a high-level view and the document that describes how to implement Single sign-on using partner flows.

Apple single sign-on using partner flows cookbook

Prerequisites prerequisites

Before proceeding with the Apple single sign-on using partner flows, ensure the following prerequisites are met:

  • The streaming application must gather all the necessary data required by the X-Device-Info and/or User-Agent headers such that the 51黑料不打烊 Pass Authentication backend can identify the device platform and its capabilities. For more details about X-Device-Info header, refer to the X-Device-Info documentation.

  • 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.

    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.

    The streaming application can request 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.

IMPORTANT
Assumptions
  • The streaming application has completed the onboarding prerequisites that apply to a Programmer and are required to enable the Apple single sign-on user experience.

Workflow workflow

Perform the given steps to implement the Apple single sign-on using partner flows as shown in the following diagram.

Apple single sign-on using partner flows

Apple single sign-on using partner flows

A. Registration Phase

  1. Retrieve client credentials: The streaming application gathers all the necessary data to retrieve client credentials by calling the Client Register endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve client credentials API documentation for details on:
    • All the required parameters, like software_statement
    • All the required headers, like Content-Type, X-Device-Info
    • All the optional parameters and headers

  2. Return client credentials: The Client Register endpoint response contains information about the client credentials associated with the received parameters and headers.

    note important
    IMPORTANT
    Refer to the Retrieve client credentials API documentation for details on the information provided in a client credentials response.
    The Client Register validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    If validation fails, an error response will be generated, providing additional information that adheres to the Retrieve client credentials API documentation.
    note tip
    TIP
    Suggestion: The client credentials must be cached and may be used indefinitely.

  3. Retrieve access token: The streaming application gathers all the necessary data to retrieve access token by calling the Client Token endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve access token API documentation for details on:
    • All the required parameters, like client_id, client_secret, and grant_type
    • All the required headers, like Content-Type, X-Device-Info
    • All the optional parameters and headers

  4. Return access token: The Client Token endpoint response contains information about the access token associated with the received parameters and headers.

    note important
    IMPORTANT
    Refer to the Retrieve access token API documentation for details on the information provided in an access token response.
    The Client Token validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    If validation fails, an error response will be generated, providing additional information that adheres to the Retrieve access token API documentation.
    note tip
    TIP
    Suggestion: The access token must be cached and used only within the specified duration (e.g., 24-hour time-to-live). After it expires, the streaming application must request a new access token.
B. Check Authentication Phase

  1. Retrieve partner framework status: The streaming application calls the developed by Apple, to obtain user permission and provider information.

    note important
    IMPORTANT
    Refer to the documentation for details on:
    • The streaming application must check for the user鈥檚 subscription information and proceed only if the user allowed it.
    • The streaming application must provide a for the VSAccountManager.
    • The streaming application must submit a for subscriber account information.
    • The streaming application must wait and process the information.
    The streaming application must ensure it specifies a Boolean value equal to false for the property in the VSAccountMetadataRequest object, to indicate that the user cannot be interrupted at this phase.

  2. Return partner framework status information: The streaming application validates the response data to ensure that basic conditions are met:

    • The user permission access status is granted.
    • The user provider mapping identifier is present and valid.
    • The user provider profile鈥檚 expiration date (if available) is valid.

  3. Retrieve profiles: The streaming application gathers all the necessary data to retrieve all profiles information by sending a request to the Profiles endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve profiles API documentation for details on:
    • All the required parameters, like serviceProvider
    • All the required headers, like Authorization, AP-Device-Identifier, and AP-Partner-Framework-Status
    • All the optional parameters and headers
    The streaming application must ensure it includes a valid value for the partner framework status such that the retrieved response may include an 鈥渁ppleSSO鈥 type profile.
    For more details about AP-Partner-Framework-Status header, refer to the AP-Partner-Framework-Status documentation.

  4. Return information about found profiles: The Profiles endpoint response contains information about the found profiles associated with the received parameters and headers.

  5. Choose a profile and proceed with decisions flows: If the Profiles endpoint response contains profiles, the streaming application uses its internal logic (eventually by interacting with the end user) to choose one of the available profiles to continue with subsequent decisions flows.

  6. Proceed with partner authentication flow: If the Profiles endpoint response does not contain a profile, the streaming application continues with partner authentication flow.

C. Partner Authentication Phase

  1. Retrieve configuration: The streaming application gathers all the necessary data to retrieve the list of MVPDs having an active integration by sending a request to the Configuration endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve configuration for specific service provider API documentation for details on:
    • All the required parameters, like serviceProvider
    • All the required headers, like Authorization, AP-Device-Identifier, and X-Device-Info
    • All the optional parameters and headers

  2. Return configuration: The Configuration endpoint response contains information about the MVPDs having an active integration with the service provider.

    note important
    IMPORTANT
    Refer to the Retrieve configuration for specific service provider API documentation for details on the information provided in a configuration response.
    The Configuration endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.
    note important
    IMPORTANT
    The streaming application must ensure it processes the following details provided for each MVPD when proceeding further:
    • enablePlatformServices: Indicates whether the MVPD currently supports the Apple single sign-on.
    • displayInPlatformPicker: Indicates whether the MVPD can be displayed in the Apple picker.
    • boardingStatus: Indicates whether the MVPD is onboarded in the Apple single sign-on.

  3. Retrieve partner framework status: The streaming application calls the developed by Apple, to obtain user permission and provider information.

    note important
    IMPORTANT
    Refer to the documentation for details on:
    • The streaming application must check for the user鈥檚 subscription information and proceed only if the user allowed it.
    • The streaming application must provide a for the VSAccountManager.
    • The streaming application must submit a for subscriber account information.
    • The streaming application must wait and process the information.
    The streaming application must ensure it specifies a Boolean value equal to true for the property in the VSAccountMetadataRequest object, to indicate that the user can be interrupted to select TV provider at this phase.

  4. Return partner framework status information: The streaming application validates the response data to ensure that basic conditions are met:

    • The user permission access status is granted.
    • The user provider mapping identifier is present and valid.
    • The user provider profile鈥檚 expiration date (if available) is valid.

  5. Retrieve partner authentication request: The streaming application gathers all the necessary data to initiate an authentication session by calling the Sessions Partner endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve partner authentication request API documentation for details on:
    • All the required parameters, like serviceProvider and partner
    • All the required headers like Authorization, AP-Device-Identifier, Content-Type, X-Device-Info, and AP-Partner-Framework-Status
    • All the optional headers and parameters
    The streaming application must ensure it includes a valid value for the partner framework status such that the retrieved response may include a partner authentication request (SAML request).
    For more details about AP-Partner-Framework-Status header, refer to the AP-Partner-Framework-Status documentation.

  6. Indicate the next action: The Sessions Partner endpoint response contains the necessary data to guide the streaming application regarding the next action.

    note important
    IMPORTANT
    Refer to the Retrieve partner authentication request API documentation for details on the information provided in a session response.
    The Sessions Partner endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If basic validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.
    The Sessions Partner endpoint validates the request data to ensure that partner single sign-on conditions are met:
    • The partner single sign-on configuration in the 51黑料不打烊 Pass server must be valid and enabled.
    • The partner framework status payload received via the AP-Partner-Framework-Status header must be valid.
    If partner single sign-on validation fails, the response will default to the basic authentication flow.

  7. Proceed with decisions flows: The Sessions Partner endpoint response contains the following data:

    • The actionName attribute is set to 鈥渁uthorize鈥.
    • The actionType attribute is set to 鈥渄irect鈥.

    If the 51黑料不打烊 Pass backend identifies a valid profile, the streaming application does not need to re-authenticate with the selected MVPD, as there is already a profile that can be used for subsequent decisions flows.

  8. Proceed with basic authentication flow: The Sessions Partner endpoint response contains the following data:

    • The actionName attribute is set to either 鈥渁uthenticate鈥 or 鈥渞esume鈥.
    • The actionType attribute is set to either 鈥渋nteractive鈥 or 鈥渄irect鈥.

    If the 51黑料不打烊 Pass backend does not identify a valid profile and the partner single sign-on validation fails, the 51黑料不打烊 Pass server falls back to the basic authentication flow.

    For more details about the basic authentication flow, refer to the following documents:

  9. Proceed with retrieve profile using partner authentication response flow: The Sessions Partner endpoint response contains the following data:

    • The actionName attribute is set to 鈥減artner_profile鈥.
    • The actionType attribute is set to 鈥渄irect鈥.
    • The authenticationRequest - type attribute includes the security protocol used by the partner framework for MVPD login (currently set to SAML only).
    • The authenticationRequest - request attribute includes the SAML request that is passed to the partner framework.
    • The authenticationRequest - attributesNames attribute includes the SAML attributes that are passed to the partner framework.

    If the 51黑料不打烊 Pass backend does not identify a valid profile and the partner single sign-on validation passes, the streaming application receives a response with actions and data to pass to the partner framework for starting the authentication flow with the MVPD.

  10. Complete MVPD authentication with partner framework: Forward the partner authentication request (SAML request) obtained in previous step to the . If the authentication flow is successful, the interaction with the MVPD produces a partner authentication response (SAML response) that is returned along with the partner framework status information.

    note important
    IMPORTANT
    Refer to the documentation for details on:
    • The streaming application must check for the user鈥檚 subscription information and proceed only if the user allowed it.
    • The streaming application must provide a for the VSAccountManager.
    • The streaming application must submit a for subscriber account information and must include the partner authentication request (SAML request) obtained in previous step.
    • The streaming application must wait and process the information.
    The streaming application must ensure it specifies a Boolean value equal to true for the property in the VSAccountMetadataRequest object, to indicate that the user can be interrupted to authenticate with the selected TV provider at this phase.

  11. Return partner authentication response: The streaming application validates the response data to ensure that basic conditions are met:

    • The user permission access status is granted.
    • The user provider mapping identifier is present and valid.
    • The user provider profile鈥檚 expiration date (if available) is valid.
    • The partner authentication response (SAML response) is present and valid.

  12. Retrieve profile using partner authentication response: The streaming application gathers all the necessary data to create and retrieve a profile by calling the Profiles Partner endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve profile using partner authentication response API documentation for details on:
    • All the required parameters, like serviceProvider, partner, and SAMLResponse
    • All the required headers, like Authorization, AP-Device-Identifier, Content-Type, X-Device-Info, and AP-Partner-Framework-Status
    • All the optional headers and parameters
    The streaming application must ensure it includes valid values for the partner framework status and the partner authentication response (SAML response) such that the retrieved response may include an 鈥渁ppleSSO鈥 type profile.
    For more details about AP-Partner-Framework-Status header, refer to the AP-Partner-Framework-Status documentation.

  13. Return information about partner profile: The Profiles endpoint response contains information about the partner profile, including the attribute type set to 鈥渁ppleSSO鈥.

    note important
    IMPORTANT
    Refer to the Retrieve profile using partner authentication response API documentation for details on the information provided in a profile response.
    The Profiles Partner endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.
    The Profiles Partner endpoint validates the request data to ensure that partner single sign-on conditions are met:
    • The partner single sign-on configuration in the 51黑料不打烊 Pass server must be valid and enabled.
    • The partner framework status payload received via the AP-Partner-Framework-Status header must be valid.
    If partner single sign-on validation fails, the response will default to the basic profile retrieval flow.

  14. Proceed with decisions flows: The streaming application can continue with subsequent decisions flows.

D. Decisions Phase

  1. Retrieve partner framework status: The streaming application calls the developed by Apple, to obtain user permission and provider information.

    note important
    IMPORTANT
    Refer to the documentation for details on:
    • The streaming application must check for the user鈥檚 subscription information and proceed only if the user allowed it.
    • The streaming application must provide a for the VSAccountManager.
    • The streaming application must submit a for subscriber account information.
    • The streaming application must wait and process the information.
    The streaming application must ensure it specifies a Boolean value equal to false for the property in the VSAccountMetadataRequest object, to indicate that the user cannot be interrupted at this phase.
    note tip
    TIP
    Suggestion: The streaming application can use a cached value for the partner framework status information, that we recommend refreshing when the application transitions from background to foreground state.

  2. Return partner framework status information: The streaming application validates the response data to ensure that basic conditions are met:

    • The user permission access status is granted.
    • The user provider mapping identifier is present and valid.
    • The user provider profile鈥檚 expiration date (if available) is valid.

  3. Retrieve preauthorization decisions: The streaming application gathers all the necessary data to obtain preauthorization decisions for a list of resources by calling the Decisions Preauthorize endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve preauthorization decisions using specific mvpd API documentation for details on:
    • All the required parameters, like serviceProvider, mvpd, and resources
    • All the required headers, like Authorization and AP-Device-Identifier
    • All the optional parameters and headers
    The streaming application must ensure it includes a valid value for the partner framework status before making a request further, when the chosen profile is an 鈥渁ppleSSO鈥 type profile.
    For more details about AP-Partner-Framework-Status header, refer to the AP-Partner-Framework-Status documentation.

  4. Return preauthorization decisions: The Decisions Preauthorize endpoint response contains a Permit or Deny decision for each resource:

    • A Permit decision means the resource is playable. The response does not include a media token, as the preauthorization flow must not be used to play resources.
    • A Deny decision means the resource is not playable. The response includes an error payload which adheres to the Enhanced Error Codes documentation.
    note important
    IMPORTANT
    Refer to the Retrieve preauthorization decisions using specific mvpd API documentation for details on the information provided in a decision response.
    The Decisions Preauthorize endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.

  5. Retrieve partner framework status: The streaming application calls the developed by Apple, to obtain user permission and provider information.

    note important
    IMPORTANT
    Refer to the documentation for details on:
    • The streaming application must check for the user鈥檚 subscription information and proceed only if the user allowed it.
    • The streaming application must provide a for the VSAccountManager.
    • The streaming application must submit a for subscriber account information.
    • The streaming application must wait and process the information.
    The streaming application must ensure it specifies a Boolean value equal to false for the property in the VSAccountMetadataRequest object, to indicate that the user cannot be interrupted at this phase.
    note tip
    TIP
    Suggestion: The streaming application can use a cached value for the partner framework status information, that we recommend refreshing when the application transitions from background to foreground state.

  6. Return partner framework status information: The streaming application validates the response data to ensure that basic conditions are met:

    • The user permission access status is granted.
    • The user provider mapping identifier is present and valid.
    • The user provider profile鈥檚 expiration date (if available) is valid.

  7. Retrieve authorization decision: The streaming application gathers all the necessary data to obtain an authorization decision for a specific resource by calling the Decisions Authorize endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve authorization decisions using specific mvpd API documentation for details on:
    • All the required parameters, like serviceProvider, mvpd, and resources
    • All the required headers, like Authorization and AP-Device-Identifier
    • All the optional parameters and headers
    The streaming application must ensure it includes a valid value for the partner framework status before making a request further, when the chosen profile is an 鈥渁ppleSSO鈥 type profile.
    For more details about AP-Partner-Framework-Status header, refer to the AP-Partner-Framework-Status documentation.

  8. Return authorization decision: The Decisions Authorize endpoint response contains a Permit or Deny decision for the specific resource:

    • A Permit decision means the resource is playable. The response includes a media token.
    • A Deny decision means the resource is not playable. The response includes an error payload which adheres to the Enhanced Error Codes documentation.
    note important
    IMPORTANT
    Refer to the Retrieve authorization decisions using specific mvpd API documentation for details on the information provided in a decision response.
    The Decisions Authorize endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.
D. Logout Phase

  1. Initiate 51黑料不打烊 Pass logout: The streaming application gathers all the necessary data to initiate the logout flow by calling the 51黑料不打烊 Pass Logout endpoint.

    note important
    IMPORTANT
    Refer to the Initiate logout for specific mvpd API documentation for details on:
    • All the required parameters, like serviceProvider, mvpd, and redirectUrl
    • All the required headers, like Authorization, AP-Device-Identifier
    • All the optional parameters and headers

  2. Indicate the next action: The 51黑料不打烊 Pass Logout endpoint response contains the necessary data to guide the streaming application regarding the next action:

    • The url attribute is missing since the user needs to interact with the partner (system) level to complete the logout flow.
    • The actionName attribute is set to 鈥減artner_logout鈥.
    • The actionType attribute is set to 鈥減artner_interactive鈥.
    note important
    IMPORTANT
    Refer to the Initiate logout for specific mvpd API documentation for details on the information provided in a logout response.
    The 51黑料不打烊 Pass Logout endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.
    note important
    IMPORTANT
    The streaming application must ensure it indicates the user to continue to log out from partner level further.
recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b