Merge pull request #110652 from mikeparker104/patch-2

(AzureCXP) Include steps for token-based auth

Author: shawnmariejones

includes/notification-hubs-enable-apple-push-notifications.md

@@ -68,11 +68,21 @@ To send push notifications to an iOS app, register your application with Apple,
 
 4. In the **Certificates, Identifiers & Profiles** page, under **Identifiers**, locate the App ID line item that you just created, and select its row to display the **Edit your App ID Configuration** screen.
 
-5. Scroll down to the checked **Push Notifications** option, and then select **Configure** to create the certificate.
+## Creating a Certificate for Notification Hubs
+A certificate is required to enable the notification hub to work with **APNS**. This can be done in one of two ways:
+
+1. Create a **.p12** that can be uploaded directly to Notification Hub.  
+2. Create a **.p8** that can be used for [token-based authentication](https://docs.microsoft.com/azure/notification-hubs/notification-hubs-push-notification-http2-token-authentification) (*the newer approach*).
+
+The newer approach has a number of benefits (compared to using certificates) as documented in [Token-based (HTTP/2) authentication for APNS](https://docs.microsoft.com/azure/notification-hubs/notification-hubs-push-notification-http2-token-authentification). However, steps have been provided for both approaches. 
+
+### OPTION 1: Creating a .p12 push certificate that can be uploaded directly to Notification Hub
+
+1. Scroll down to the checked **Push Notifications** option, and then select **Configure** to create the certificate.
 
     ![Edit App ID page](./media/notification-hubs-enable-apple-push-notifications/notification-hubs-edit-appid.png)
 
-6. The **Apple Push Notification service SSL Certificates** window appears. Select the **Create Certificate** button under the **Development SSL Certificate** section.
+2. The **Apple Push Notification service SSL Certificates** window appears. Select the **Create Certificate** button under the **Development SSL Certificate** section.
 
     ![Create certificate for App ID button](./media/notification-hubs-enable-apple-push-notifications/notification-hubs-appid-create-cert.png)
 
@@ -81,9 +91,9 @@ To send push notifications to an iOS app, register your application with Apple,
     > [!NOTE]
     > This tutorial uses a development certificate. The same process is used when registering a production certificate. Just make sure that you use the same certificate type when sending notifications.
 
-1. Select **Choose File**, browse to the location where you saved the CSR file from the first task, and then double-click the certificate name to load it. Then select **Continue**.
+3. Select **Choose File**, browse to the location where you saved the CSR file from the first task, and then double-click the certificate name to load it. Then select **Continue**.
 
-1. After the portal creates the certificate, select the **Download** button. Save the certificate, and remember the location to which it's saved.
+4. After the portal creates the certificate, select the **Download** button. Save the certificate, and remember the location to which it's saved.
 
     ![Generated certificate download page](./media/notification-hubs-enable-apple-push-notifications/notification-hubs-appid-download-cert.png)
 
@@ -94,14 +104,14 @@ To send push notifications to an iOS app, register your application with Apple,
     > [!NOTE]
     > By default, the downloaded development certificate is named **aps_development.cer**.
 
-1. Double-click the downloaded push certificate **aps_development.cer**. This action installs the new certificate in the Keychain, as shown in the following image:
+5. Double-click the downloaded push certificate **aps_development.cer**. This action installs the new certificate in the Keychain, as shown in the following image:
 
     ![Keychain access certificates list showing new certificate](./media/notification-hubs-enable-apple-push-notifications/notification-hubs-cert-in-keychain.png)
 
     > [!NOTE]
     > Although the name in your certificate might be different, the name will be prefixed with **Apple Development iOS Push Services**.
 
-1. In Keychain Access, right-click the new push certificate that you created in the **Certificates** category. Select **Export**, name the file, select the **.p12** format, and then select **Save**.
+6. In Keychain Access, right-click the new push certificate that you created in the **Certificates** category. Select **Export**, name the file, select the **.p12** format, and then select **Save**.
 
     ![Export certificate as p12 format](./media/notification-hubs-enable-apple-push-notifications/notification-hubs-export-cert-p12.png)
 
@@ -110,6 +120,45 @@ To send push notifications to an iOS app, register your application with Apple,
     > [!NOTE]
     > Your .p12 file name and location might be different than what is pictured in this tutorial.
 
+### OPTION 2: Creating a .p8 certificate that can be used for token-based authentication
+
+1. Make note of the following details:
+
+    - **App ID Prefix** (this is a **Team ID**)
+    - **Bundle ID**
+    
+2. Back in **Certificates, Identifiers & Profiles**, click **Keys**.
+
+   > [!NOTE]
+   > If you already have a key configured for **APNS**, you can re-use the .p8 certificate that you downloaded right after it was created. If so, you can ignore steps **3** through **5**.
+
+3. Click the **+** button (or the **Create a key** button) to create a new key.
+4. Provide a suitable **Key Name** value, then check the **Apple Push Notifications service (APNs)** option, and then click **Continue**, followed by **Register** on the next screen.
+5. Click **Download** and then move the **.p8** file (prefixed with *AuthKey_*) to a secure local directory, then click **Done**.
+
+   > [!NOTE] 
+   > Be sure to keep your .p8 file in a secure place (and save a backup). After downloading your key, it cannot be re-downloaded as the server copy is removed.
+  
+6. On **Keys**, click on the key that you just created (or an existing key if you have chosen to use that instead).
+7. Make note of the **Key ID** value.
+8. Open your .p8 certificate in a suitable application of your choice such as [**Visual Studio Code**](https://code.visualstudio.com) then make note of the key value. This is the value between **-----BEGIN PRIVATE KEY-----** and **-----END PRIVATE KEY-----** .
+
+    ```
+    -----BEGIN PRIVATE KEY-----
+    <key_value>
+    -----END PRIVATE KEY-----
+    ```
+
+    > [!NOTE]
+    > This is the **token value** that will be used later to configure **Notification Hub**. 
+
+At the end of these steps you should have the following information for use later in [Configure your notification hub with APNs information](#configure-your-notification-hub-with-apns-information):
+
+- **Team ID** (see step 1)
+- **Bundle ID** (see step 1)
+- **Key ID** (see step 7)
+- **Token value** i.e. the .p8 key value (see step 8)
+
 ## Create a provisioning profile for the app
 
 1. Return to the [iOS Provisioning Portal](https://go.microsoft.com/fwlink/p/?LinkId=272456), select **Certificates, Identifiers & Profiles**, select **Profiles** from the left menu, and then select **+** to create a new profile. The **Register a New Provisioning Profile** screen appears.
@@ -147,13 +196,18 @@ To send push notifications to an iOS app, register your application with Apple,
 
 ## Create a notification hub
 
-In this section, you create a notification hub and configure authentication with APNs by using the .p12 push certificate that you previously created. If you want to use a notification hub that you've already created, you can skip to step 5.
+In this section, you create a notification hub and configure authentication with APNs by using either the .p12 push certificate or token-based authentication. If you want to use a notification hub that you've already created, you can skip to step 5.
 
 [!INCLUDE [notification-hubs-portal-create-new-hub](notification-hubs-portal-create-new-hub.md)]
 
 ## Configure your notification hub with APNs information
 
-1. Under **Notification Services**, select **Apple (APNS)**.
+Under **Notification Services**, select **Apple (APNS)** then follow the appropriate steps based on the approach you chose previously in the [Creating a Certificate for Notification Hubs](#creating-a-certificate-for-notification-hubs) section.  
+
+> [!NOTE]
+> Use the **Production** for **Application Mode** only if you want to send push notifications to users who purchased your app from the store.
+
+### OPTION 1: Using a .p12 push certificate
 
 1. Select **Certificate**.
 
@@ -163,10 +217,23 @@ In this section, you create a notification hub and configure authentication with
 
 1. If required, specify the correct password.
 
-1. Select **Sandbox** mode. Use the **Production** mode only if you want to send push notifications to users who purchased your app from the store.
+1. Select **Sandbox** mode.
 
     ![Configure APNs certification in Azure portal](./media/notification-hubs-enable-apple-push-notifications/notification-hubs-apple-config-cert.png)
 
 1. Select **Save**.
 
+### OPTION 2: Using token-based authentication
+
+1. Select **Token**.
+1. Enter the following values that you acquired earlier:
+
+    - **Key ID**
+    - **Bundle ID**
+    - **Team ID**
+    - **Token** 
+
+1. Choose **Sandbox**
+1. Select **Save**. 
+
 You've now configured your notification hub with APNs. You also have the connection strings to register your app and send push notifications.