针对 APNS 进行基于令牌的 (HTTP/2) 身份验证Token-based (HTTP/2) authentication for APNS

概述Overview

本文介绍如何将新的 APNS HTTP/2 协议与基于令牌的身份验证配合使用。This article explains how to use the new APNS HTTP/2 protocol with token-based authentication.

使用新协议的主要好处包括:The key benefits of using the new protocol include:

  • 与生成证书相比,生成令牌相对较为简单Token generation is relatively simple (compared to certificates)
  • 不再有过期日期 – 用户可以控制身份验证令牌及其吊销No more expiry dates – you are in control of your authentication tokens and their revocation
  • 有效负载现在最大可以达到 4 KBPayloads can now be up to 4 KB
  • 同步反馈Synchronous feedback
  • 采用的是 Apple 的最新协议 - 证书仍然使用二进制协议(已标记为弃用)You are on Apple's latest protocol – certificates still use the binary protocol, which is marked for deprecation

可通过两个步骤来使用此新机制:Using this new mechanism can be performed in two steps:

  • 从 Apple 开发人员帐户门户获取所需的信息。Obtain the necessary information from the Apple Developer account portal.
  • 使用新信息配置通知中心。Configure your notification hub with the new information.

通知中心现已设置为对 APNS 使用新的身份验证系统。Notification Hubs is now set to use the new authentication system with APNS.

请注意,如果已进行迁移而不再使用 APNS 的证书凭据,则令牌属性将覆盖系统中的证书,但应用程序仍可顺利地接收通知。Note that if you migrated from using certificate credentials for APNS, the token properties overwrite your certificate in our system, but your application continues to receive notifications seamlessly.

从 Apple 获取身份验证信息Obtaining authentication information from Apple

若要启用基于令牌的身份验证,需要获取 Apple 开发人员帐户中的以下属性:To enable token-based authentication, you need the following properties from your Apple Developer account:

密钥标识符Key identifier

可以从 Apple 开发人员帐户中“密钥”页的“证书、标识符和配置文件”下获取密钥标识符: The key identifier can be obtained from the Keys page under Certificates, Identifiers & Profiles, in your Apple Developer account:

证书

标识符

应用程序标识符和应用程序名称Application identifier and application name

开发人员帐户中的“证书、标识符和配置文件”页还提供了应用程序名称和标识符:The application name and identifier are also available in the Certificates, Identifiers & Profiles page in the developer account:

证书和 ID

通过 .NET SDK 或 Azure 门户进行配置Configure via the .NET SDK or the Azure portal

可以使用最新的客户端 SDK 或者在 Azure 门户中,将中心配置为使用基于令牌的身份验证。You can configure your hub to use token-based authentication using our latest client SDK, or in the Azure portal. 若要在门户中启用基于令牌的身份验证,请登录到 Azure 门户并转到通知中心的“设置”>“Apple (APNS)”面板。To enable token-based authentication in the portal, sign in to the Azure portal and go to your notification hub's Settings > Apple (APNS) panel. 从“身份验证模式”属性中选择“令牌”,以使用所有相关令牌属性更新中心。 Select Token from the Authentication Mode property to update your hub with all the relevant token properties.

配置令牌

  • 输入从 Apple 开发人员帐户检索的属性。Enter the properties you retrieved from your Apple Developer account.
  • 选择应用程序模式(“生产”或“沙盒”)。 Choose the application mode (Production or Sandbox).
  • 单击“保存”按钮以更新 APNS 凭据。Click the Save button to update your APNS credentials.

基于令牌的凭据由以下字段组成:Token-based credentials are composed of the following fields:

  • 密钥 ID:在 Apple 开发人员门户中生成的私钥的标识符;例如 2USFGKSKLTKey ID: Identifier of the private key generated in the Apple Developer portal; for example, 2USFGKSKLT.
  • 团队 ID:也称为“前缀”或“应用前缀”。Team ID: Also called the "Prefix" or "App Prefix." 这是 Apple 开发人员门户中的组织标识符;例如 S4V3D7CHJRThis is the identifier for the organization in the Apple Developer portal; for example, S4V3D7CHJR.
  • 捆绑 ID:也称为“应用 ID”。Bundle ID: Also called the "App ID." 这是应用程序的捆绑标识符;例如 com.example.myappThis is the bundle identifier for the application; for example, com.example.myapp. 请注意,可对多个应用使用一个密钥。Note that you can use one key for many apps. 此值在发送通知时将映射到 apns-topic HTTP 标头,并用于将特定应用程序指定为目标。This value maps to the apns-topic HTTP header when sending a notification, and is used to target the specific application. 请注意,不能显式设置 apns-topic 的值。Note that you cannot set the value of apns-topic explicitly.
  • 令牌:也称为“密钥”或“私钥”。Token: Also called the "Key" or "Private Key." 此值是从 Apple 开发人员门户上生成的 .p8 文件中获取的。This is obtained from the .p8 file generated on the Apple Developer portal. 必须为密钥启用 APNS(生成密钥时在 Apple 开发人员门户上选择 APNS)。The key must have APNS enabled (which is selected on the Apple Developer portal when generating the key). 在 NH 门户/API 中提供此值时,必须去除其中的 PEM 头部/尾部。The value must have the PEM header/footer stripped from it when you supply it to the NH Portal/API.
  • 终结点:这是通知中心门户边栏选项卡中的一个切换开关,且是 API 中的一个字符串字段。Endpoint: This is a toggle in the Notification Hubs portal blade, and a string field in the API. 有效值为 https://api.development.push.apple.com:443/3/device or https://api.sandbox.push.apple.com:443/3/device进行求值的基于 SQL 语言的筛选器表达式。Valid values are https://api.development.push.apple.com:443/3/device or https://api.sandbox.push.apple.com:443/3/device. 通知中心在生产或沙盒环境使用此值来发送通知。Notification Hubs uses this value for either the production or sandbox environment, for sending notifications. 此值必须与应用中的 aps-environment 权利相匹配,否则,生成的 APNS 设备令牌将与环境不匹配,并且无法发送通知。This must match the aps-environment entitlement in the app, otherwise the APNS device tokens generated don't match the environment, and the notifications fail to send.

下面是演示了正确用法的代码示例:Here's a code sample illustrating the correct usage:

NamespaceManager nm = NamespaceManager.CreateFromConnectionString(_endpoint);
string token = "YOUR PRIVATE KEY HERE";
string keyId = "YOUR KEY ID HERE";
string appName = "YOUR APP NAME HERE";
string appId = "YOUR APP ID HERE";
NotificationHubDescription desc = new NotificationHubDescription("PATH TO YOUR HUB");
desc.ApnsCredential = new ApnsCredential(token, keyId, appId, appName);
desc.ApnsCredential.Endpoint = @"https://api.development.push.apple.com:443/3/device";
nm.UpdateNotificationHubAsync(desc);

后续步骤Next steps