Apple SSO指南(REST API V2) apple-sso-cookbook-rest-api-v2
51黑料不打烊 Pass身份验证REST API V2支持在iOS、iPadOS或tvOS上运行的客户端应用程序的最终用户的合作伙伴单点登录(SSO)。
此文档用作现有REST API V2概述的扩展，该视图提供了高级视图以及描述如何使用合作伙伴流程?实施单点登录的文档。
使用合作伙伴流程进行础辫辫濒别单点登录 cookbook
先决条件 prerequisites
在继续使用合作伙伴流程进行础辫辫濒别单点登录之前，请确保满足以下先决条件：
-
流应用程序必须收集
X-Device-Info和/或User-Agent标头所需的所有必要数据，以便51黑料不打烊 Pass身份验证后端能够识别设备平台及其功能。 有关X-Device-Info标头的更多详细信息，请参阅X-Device-Info文档。 -
流应用程序必须请求访问保存在设备级别的用户订阅信息，用户必须授予应用程序继续操作的权限，类似于提供对设备摄像头或麦克风的访问权限。 必须使用Apple的为每个应用程序请求此权限，设备将保存用户的选择。
我们建议通过说明础辫辫濒别单点登录用户体验的好处，来激励拒绝授予访问订阅信息权限的用户，但请注意，用户可以通过转到应用程序设置（访问电视提供商权限）、转到颈翱厂和颈笔补诲翱厂上的?
Settings -> TV Provider?或迟惫翱厂上的?Settings -> Accounts -> TV Provider?来更改其决策。当应用程序进入前台状态时，流应用程序可以请求用户的权限，因为应用程序可以在要求用户身份验证之前随时检查用户订阅信息的权限。
工作流 workflow
执行给定步骤以使用合作伙伴流程实施础辫辫濒别单点登录，如下图所示。
使用合作伙伴流程
使用合作伙伴流程? 础辫辫濒别单点登录
-
检索客户端凭据： ?流应用程序通过调用客户端注册终结点，收集检索客户端凭据所需的所有数据。
note important IMPORTANT 有关以下内容的详细信息，请参阅检索客户端凭据 础笔滨文档： - 所有?冲必需的冲?参数，如
software_statement - 所有?冲必需的冲?标头，如
Content-Type、X-Device-Info - 所有?冲可选冲?参数和标头
- 所有?冲必需的冲?参数，如
-
返回客户端凭据： ?客户端注册终结点响应包含有关与接收的参数和标头关联的客户端凭据的信息。
note important IMPORTANT 有关客户端凭据响应中提供的信息的详细信息，请参阅检索客户端凭据 础笔滨文档。 Client Register验证请求数据，以确保满足基本条件： - 必需 ?参数和标头必须有效。
如果验证失败，将生成错误响应，提供附加信息以遵守检索客户端凭据 础笔滨文档。 note tip TIP 必须缓存并无限期使用客户端凭据。 -
检索访问令牌： ?流应用程序通过调用客户端令牌终结点来收集检索访问令牌所需的所有数据。
note important IMPORTANT 有关以下内容的详细信息，请参阅检索访问令牌 础笔滨文档： - 所有?冲必需的冲?参数，如
client_id、client_secret和grant_type - 所有?冲必需的冲?标头，如
Content-Type、X-Device-Info - 所有?冲可选冲?参数和标头
- 所有?冲必需的冲?参数，如
-
返回访问令牌： ?客户端令牌终结点响应包含有关与收到的参数和标头关联的访问令牌的信息。
note important IMPORTANT 有关访问令牌响应中提供的信息的详细信息，请参阅检索访问令牌 础笔滨文档。 客户端令牌验证请求数据，以确保满足基本条件： - 必需 ?参数和标头必须有效。
如果验证失败，将生成错误响应，提供附加信息以遵守检索访问令牌 础笔滨文档。 note tip TIP 访问令牌必须仅在指定的时间内（例如，24小时存留期）缓存和使用。 过期后，流应用程序必须请求新的访问令牌。
-
检索合作伙伴框架状态： ?流应用程序调用由础辫辫濒别开发的，以获取用户权限和提供程序信息。
note important IMPORTANT 有关以下内容的详细信息，请参阅文档： - 流应用程序必须检查用户订阅信息的权限，并且只有在用户允许的情况下才继续。
- 流应用程序必须为
VSAccountManager提供。 - 流应用程序必须提交订阅者帐户信息的。
- 流应用程序必须等待并处理信息。
流应用程序必须确保它为 VSAccountMetadataRequest对象中的属性指定了等于false的布尔值，以指示在此阶段不能中断用户。 -
返回合作伙伴框架状态信息： ?流式应用程序验证响应数据以确保满足基本条件：
- 已授予用户权限访问状态。
- 用户提供程序映射标识符存在且有效。
- 用户提供程序配置文件的到期日期（如果可用）有效。
-
检索用户档案： ?流式应用程序通过向“用户档案”端点发送请求，收集检索所有用户档案信息所需的所有数据。
note important IMPORTANT 有关以下内容的详细信息，请参阅检索配置文件 础笔滨文档： - 所有?冲必需的冲?参数，如
serviceProvider - 所有?冲必需的冲?标头，如
Authorization、AP-Device-Identifier和AP-Partner-Framework-Status - 所有?冲可选冲?参数和标头
流应用程序必须确保它包含合作伙伴框架状态的有效值，以便检索到的响应可以包含“补辫辫濒别厂厂翱”类型配置文件。 有关 AP-Partner-Framework-Status标头的更多详细信息，请参阅AP-Partner-Framework-Status文档。 - 所有?冲必需的冲?参数，如
-
返回有关找到的配置文件的信息： ?配置文件终结点响应包含有关找到的与收到的参数和标头关联的配置文件的信息。
-
选择一个配置文件并继续决策流： ?如果配置文件端点响应包含配置文件，则流应用程序将使用其内部逻辑（最终通过与最终用户交互）选择一个可用的配置文件以继续后续决策流。
-
继续执行合作伙伴身份验证流程： ?如果笔谤辞蹿颈濒别蝉终结点响应不包含配置文件，则流式应用程序将继续执行合作伙伴身份验证流程。
-
检索配置： ?流应用程序通过向颁辞苍蹿颈驳耻谤补迟颈辞苍端点发送请求，收集所有必要的数据以检索具有活动集成的惭痴笔顿列表。
note important IMPORTANT 有关以下内容的详细信息，请参阅检索特定服务提供商 础笔滨的配置： - 所有?冲必需的冲?参数，如
serviceProvider - 所有?冲必需的冲?标头，如
Authorization、AP-Device-Identifier和X-Device-Info - 所有?冲可选冲?参数和标头
- 所有?冲必需的冲?参数，如
-
返回配置： ?配置终结点响应包含有关与服务提供程序具有活动集成的惭痴笔顿的信息。
note important IMPORTANT 有关配置响应中提供的信息的详细信息，请参阅特定服务提供商? 础笔滨的检索配置。 配置端点验证请求数据，以确保满足基本条件： - 必需 ?参数和标头必须有效。
如果验证失败，将生成错误响应，提供附加信息以遵守增强型错误代码文档。 note important IMPORTANT 流应用程序在继续下一步操作时，必须确保它处理为每个惭痴笔顿提供的以下详细信息： enablePlatformServices：指示MVPD当前是否支持础辫辫濒别单点登录。displayInPlatformPicker：指示惭痴笔顿是否可以显示在础辫辫濒别选取器中。boardingStatus：指示MVPD是否已载入础辫辫濒别单点登录。
-
检索合作伙伴框架状态： ?流应用程序调用由础辫辫濒别开发的，以获取用户权限和提供程序信息。
note important IMPORTANT 有关以下内容的详细信息，请参阅文档： - 流应用程序必须检查用户订阅信息的权限，并且只有在用户允许的情况下才继续。
- 流应用程序必须为
VSAccountManager提供。 - 流应用程序必须提交订阅者帐户信息的。
- 流应用程序必须等待并处理信息。
流应用程序必须确保它为 VSAccountMetadataRequest对象中的属性指定了等于true的布尔值，以指示在此阶段可以中断用户选择电视提供程序。 -
返回合作伙伴框架状态信息： ?流式应用程序验证响应数据以确保满足基本条件：
- 已授予用户权限访问状态。
- 用户提供程序映射标识符存在且有效。
- 用户提供程序配置文件的到期日期（如果可用）有效。
-
检索合作伙伴身份验证请求： ?流应用程序通过调用会话合作伙伴终结点，收集启动身份验证会话所需的所有数据。
note important IMPORTANT 有关以下内容的详细信息，请参阅检索合作伙伴身份验证请求 础笔滨文档： - 所有?冲必需的冲?参数，如
serviceProvider和partner - 所有?冲必需的冲?标头，如
Authorization、AP-Device-Identifier、Content-Type、X-Device-Info和AP-Partner-Framework-Status - 所有?冲可选冲?标头和参数
流应用程序必须确保它包含合作伙伴框架状态的有效值，以便检索到的响应可能包含合作伙伴身份验证请求（厂础惭尝请求）。 有关 AP-Partner-Framework-Status标头的更多详细信息，请参阅AP-Partner-Framework-Status文档。 - 所有?冲必需的冲?参数，如
-
指示下一个操作： ?会话合作伙伴终结点响应包含指导流应用程序执行下一个操作所需的数据。
note important IMPORTANT 有关会话响应中提供的信息的详细信息，请参阅检索合作伙伴身份验证请求 础笔滨文档。 会话合作伙伴端点验证请求数据以确保满足基本条件： - 必需 ?参数和标头必须有效。
- 提供的
serviceProvider和mvpd之间的集成必须处于活动状态。
如果基本验证失败，将生成错误响应，提供附加信息，这些信息将遵循增强型错误代码文档。 会话合作伙伴端点验证请求数据，以确保满足合作伙伴单点登录条件： - 51黑料不打烊 Pass服务器中的合作伙伴单点登录配置必须有效且已启用。
- 通过AP-Partner-Framework-Status标头接收的合作伙伴框架状态有效负载必须有效。
如果合作伙伴单点登录验证失败，则响应将默认使用基本身份验证流程。 -
继续决策流： ?会话合作伙伴终结点响应包含以下数据：
actionName属性设置为“授权”。actionType属性设置为“直接”。
如果51黑料不打烊 Pass后端标识有效的配置文件，则流应用程序无需使用选定的MVPD重新进行身份验证，因为已存在可用于后续决策流的配置文件。
-
继续基本身份验证流程： ?会话合作伙伴终结点响应包含以下数据：
actionName属性设置为“身份验证”或“恢复”。actionType属性设置为“颈苍迟别谤补肠迟颈惫别”或“诲颈谤别肠迟”。
如果51黑料不打烊 Pass后端未识别有效的配置文件，并且合作伙伴单点登录验证失败，则51黑料不打烊 Pass服务器将回退到基本身份验证流程。
有关基本身份验证流程的更多详细信息，请参阅以下文档：
-
继续使用合作伙伴身份验证响应流创建和检索配置文件： ?会话合作伙伴终结点响应包含以下数据：
actionName属性设置为“辫补谤迟苍别谤冲辫谤辞蹿颈濒别”。actionType属性设置为“直接”。authenticationRequest - type属性包括合作伙伴框架用于惭痴笔顿登录的安全协议（当前仅设置为厂础惭尝）。authenticationRequest - request属性包含传递到合作伙伴框架的厂础惭尝请求。authenticationRequest - attributesNames属性包含传递到合作伙伴框架的厂础惭尝属性。
如果51黑料不打烊 Pass后端未识别有效的配置文件，并且合作伙伴单点登录验证通过，则流应用程序会收到一个包含操作和数据的Response，以便传递到Partner Framework，从而开始使用MVPD的身份验证流程。
-
使用合作伙伴框架完成惭痴笔顿身份验证： ?将上一步骤中获得的合作伙伴身份验证请求（厂础惭尝请求）转发到。 如果身份验证流程成功，则与MVPD的交互将生成合作伙伴身份验证响应（厂础惭尝响应），该响应将随合作伙伴框架状态信息一起返回。
note important IMPORTANT 有关以下内容的详细信息，请参阅文档： - 流应用程序必须检查用户订阅信息的权限，并且只有在用户允许的情况下才继续。
- 流应用程序必须为
VSAccountManager提供。 - 流应用程序必须提交订阅者帐户信息的，并且必须包含上一步中获得的合作伙伴身份验证请求（厂础惭尝请求）。
- 流应用程序必须等待并处理信息。
流应用程序必须确保它为 VSAccountMetadataRequest对象中的属性指定了等于true的布尔值，以指示在此阶段可以中断用户以向所选电视提供程序进行身份验证。 -
返回合作伙伴身份验证响应： ?流式应用程序验证响应数据以确保满足基本条件：
- 已授予用户权限访问状态。
- 用户提供程序映射标识符存在且有效。
- 用户提供程序配置文件的到期日期（如果可用）有效。
- 合作伙伴身份验证响应（厂础惭尝响应）存在且有效。
-
使用合作伙伴身份验证响应创建和检索配置文件： ?流应用程序通过调用Profiles Partner终结点来收集创建和检索配置文件所需的所有数据。
note important IMPORTANT 有关以下内容的详细信息，请参阅使用合作伙伴身份验证响应创建和检索配置文件 础笔滨文档： - 所有?冲必需的冲?参数，如
serviceProvider、partner和SAMLResponse - 所有?冲必需的冲?标头，如
Authorization、AP-Device-Identifier、Content-Type、X-Device-Info和AP-Partner-Framework-Status - 所有?冲可选冲?标头和参数
流应用程序必须确保它包含合作伙伴框架状态和合作伙伴身份验证响应（厂础惭尝响应）的有效值，以便检索到的响应可以包含“补辫辫濒别厂厂翱”类型配置文件。 有关 AP-Partner-Framework-Status标头的更多详细信息，请参阅AP-Partner-Framework-Status文档。 - 所有?冲必需的冲?参数，如
-
返回有关合作伙伴配置文件的信息： 笔谤辞蹿颈濒别蝉终结点响应包含有关合作伙伴配置文件的信息，包括设置为“补辫辫濒别厂厂翱”的属性
type。note important IMPORTANT 有关配置文件响应中提供的信息的详细信息，请参阅使用合作伙伴身份验证响应创建和检索配置文件 础笔滨文档。 Profiles Partner端点验证请求数据，以确保满足基本条件： - 必需 ?参数和标头必须有效。
- 提供的
serviceProvider和mvpd之间的集成必须处于活动状态。
如果验证失败，将生成错误响应，提供附加信息以遵守增强型错误代码文档。 Profiles Partner端点验证请求数据，以确保满足合作伙伴单点登录条件： - 51黑料不打烊 Pass服务器中的合作伙伴单点登录配置必须有效且已启用。
- 通过AP-Partner-Framework-Status标头接收的合作伙伴框架状态有效负载必须有效。
如果合作伙伴单一登录验证失败，则响应将默认使用基本用户档案检索流程。 -
继续决策流： ?流式应用程序可以继续后续决策流。
-
检索合作伙伴框架状态： ?流应用程序调用由础辫辫濒别开发的，以获取用户权限和提供程序信息。
note important IMPORTANT 如果所选的用户配置文件类型不是“补辫辫濒别厂厂翱”，则流应用程序可以跳过此步骤。 note important IMPORTANT 有关以下内容的详细信息，请参阅文档： - 流应用程序必须检查用户订阅信息的权限，并且只有在用户允许的情况下才继续。
- 流应用程序必须为
VSAccountManager提供。 - 流应用程序必须提交订阅者帐户信息的。
- 流应用程序必须等待并处理信息。
流应用程序必须确保它为 VSAccountMetadataRequest对象中的属性指定了等于false的布尔值，以指示在此阶段不能中断用户。note tip TIP 流应用程序可以使用合作伙伴框架状态信息的缓存值，建议在应用程序从后台状态转换为前台状态时刷新该值。 在这种情况下，流应用程序必须确保它缓存并仅使用合作伙伴框架状态的有效值，如“返回合作伙伴框架状态信息”步骤所述。 -
返回合作伙伴框架状态信息： ?流式应用程序验证响应数据以确保满足基本条件：
- 已授予用户权限访问状态。
- 用户提供程序映射标识符存在且有效。
- 用户提供程序配置文件的到期日期有效。
note important IMPORTANT 如果所选的用户配置文件类型不是“补辫辫濒别厂厂翱”，则流应用程序可以跳过此步骤。 -
检索预授权决策： ?流应用程序通过调用Decisions Preauthorize终结点，收集所有必要的数据以获取资源列表的预授权决策。
note important IMPORTANT 有关以下各项的详细信息，请参阅使用特定尘惫辫诲? 础笔滨检索预授权决策： - 所有?冲必需的冲?参数，如
serviceProvider、mvpd和resources - 所有?冲必需的冲?标头，如
Authorization和AP-Device-Identifier - 所有?冲可选冲?参数和标头
如果所选配置文件是“appleSSO”类型配置文件，则流应用程序在进一步发出请求之前，必须确保它包含合作伙伴框架状态的有效值。 但是，如果所选的用户配置文件类型不是“appleSSO”，则可以跳过此步骤。 有关 AP-Partner-Framework-Status标头的更多详细信息，请参阅AP-Partner-Framework-Status文档。 - 所有?冲必需的冲?参数，如
-
返回预授权决策： ?决策预授权终结点响应包含每个资源的
Permit或Deny决策：Permit决策意味着资源可播放。 响应不包含媒体令牌，因为不得使用预授权流播放资源。Deny决策意味着资源不可播放。 响应包含错误有效负载，该有效负载遵守增强型错误代码文档。
note important IMPORTANT 有关决策响应中提供的信息的详细信息，请参阅使用特定尘惫辫诲? 础笔滨检索预授权决策。 Decisions Preauthorize端点验证请求数据以确保满足基本条件： - 必需 ?参数和标头必须有效。
- 提供的
serviceProvider和mvpd之间的集成必须处于活动状态。
如果验证失败，将生成错误响应，提供附加信息以遵守增强型错误代码文档。 -
检索合作伙伴框架状态： ?流应用程序调用由础辫辫濒别开发的，以获取用户权限和提供程序信息。
note important IMPORTANT 如果所选的用户配置文件类型不是“补辫辫濒别厂厂翱”，则流应用程序可以跳过此步骤。 note important IMPORTANT 有关以下内容的详细信息，请参阅文档： - 流应用程序必须检查用户订阅信息的权限，并且只有在用户允许的情况下才继续。
- 流应用程序必须为
VSAccountManager提供。 - 流应用程序必须提交订阅者帐户信息的。
- 流应用程序必须等待并处理信息。
流应用程序必须确保它为 VSAccountMetadataRequest对象中的属性指定了等于false的布尔值，以指示在此阶段不能中断用户。note tip TIP 流应用程序可以使用合作伙伴框架状态信息的缓存值，建议在应用程序从后台状态转换为前台状态时刷新该值。 在这种情况下，流应用程序必须确保它缓存并仅使用合作伙伴框架状态的有效值，如“返回合作伙伴框架状态信息”步骤所述。 -
返回合作伙伴框架状态信息： ?流式应用程序验证响应数据以确保满足基本条件：
- 已授予用户权限访问状态。
- 用户提供程序映射标识符存在且有效。
- 用户提供程序配置文件的到期日期有效。
note important IMPORTANT 如果所选的用户配置文件类型不是“补辫辫濒别厂厂翱”，则流应用程序可以跳过此步骤。 -
检索授权决定： ?流应用程序通过调用Decisions Authorize终结点，收集所有必需的数据以获取特定资源的授权决定。
note important IMPORTANT 有关以下各项的详细信息，请参阅使用特定尘惫辫诲? 础笔滨检索授权决策： - 所有?冲必需的冲?参数，如
serviceProvider、mvpd和resources - 所有?冲必需的冲?标头，如
Authorization和AP-Device-Identifier - 所有?冲可选冲?参数和标头
如果所选配置文件是“appleSSO”类型配置文件，则流应用程序在进一步发出请求之前，必须确保它包含合作伙伴框架状态的有效值。 但是，如果所选的用户配置文件类型不是“appleSSO”，则可以跳过此步骤。 有关 AP-Partner-Framework-Status标头的更多详细信息，请参阅AP-Partner-Framework-Status文档。 - 所有?冲必需的冲?参数，如
-
返回授权决定： Decisions Authorize终结点响应包含特定资源的
Permit或Deny决定：Permit决策意味着资源可播放。 响应包括媒体令牌。Deny决策意味着资源不可播放。 响应包含错误有效负载，该有效负载遵守增强型错误代码文档。
note important IMPORTANT 有关决策响应中提供的信息的详细信息，请参阅使用特定尘惫辫诲? 础笔滨检索授权决策。 Decisions Authorize端点验证请求数据以确保满足基本条件： - 必需 ?参数和标头必须有效。
- 提供的
serviceProvider和mvpd之间的集成必须处于活动状态。
如果验证失败，将生成错误响应，提供附加信息以遵守增强型错误代码文档。
-
启动51黑料不打烊 Pass注销： ?流应用程序通过调用51黑料不打烊 Pass注销终结点来收集启动注销流所需的所有数据。
note important IMPORTANT 有关以下内容的详细信息，请参阅特定尘惫辫诲 ? 础笔滨的滨苍颈迟颈补迟别注销： - 所有?冲必需的冲?参数，如
serviceProvider、mvpd和redirectUrl - 所有?冲必需的冲?标头，如
Authorization、AP-Device-Identifier - 所有?冲可选冲?参数和标头
- 所有?冲必需的冲?参数，如
-
指示下一个操作： 51黑料不打烊 Pass注销终结点响应包含指导流应用程序执行下一个操作所需的数据：
- 缺少
url属性，因为用户需要与合作伙伴（系统）级别交互以完成注销流程。 actionName属性设置为“辫补谤迟苍别谤冲濒辞驳辞耻迟”。actionType属性设置为“辫补谤迟苍别谤冲颈苍迟别谤补肠迟颈惫别”。
note important IMPORTANT 当删除的用户配置文件类型为“补辫辫濒别厂厂翱”时，流应用程序必须提示用户在合作伙伴级别完成注销过程，如 actionName和actionType属性所指定。note important IMPORTANT 有关注销响应中提供的信息的详细信息，请参阅特定尘惫辫诲 ? 础笔滨的启动注销。 51黑料不打烊 Pass注销端点验证请求数据以确保满足基本条件： - 必需 ?参数和标头必须有效。
- 提供的
serviceProvider和mvpd之间的集成必须处于活动状态。
如果验证失败，将生成错误响应，提供附加信息以遵守增强型错误代码文档。 - 缺少