This post is part of the Power of PushAuth™ blog series. The first post of the series was a comprehensive guide to push authentication. The next three posts of the series comprise an end-to-end sample implementation of PushAuth in a simple user login flow. The tutorial breakdown is as follows:

1. Web Server tutorial
2. iOS Mobile App tutorial (this post)
3. Android Mobile App tutorial

The tutorial in this post builds on the web server from the first tutorial. With your web server set up and running, you now need a mobile app to receive and respond to push notifications. This post will help you build the iOS mobile app to do so; then you will be able to leverage the power of PushAuth for login requests!

Setup

To follow this tutorial, you will need:

• An iPhone running iOS 12 or higher
• A macOS machine with Xcode 11 installed
• An active Apple Developer account

Step 1: Cloning the Project

The pushauth-sample-app-ios GitHub repository contains the sample iOS mobile app code for this project. Clone the repository to your local machine and open the PushAuthSample.xcworkspace file in Xcode.

$ git clone https://github.com/UnifyID/pushauth-sample-app-ios.git

Step 2: Setting Up and Running the Project

1. In the top left section of your Xcode window, set the active scheme to PushAuthSample.
2. Plug your phone into your computer. Your phone’s name will appear as the chosen device next to the active scheme.
3. Navigate to the “Signing & Capabilities” section of the Xcode project settings.
4. Check the boxes next to “Automatically manage signing” in the “Signing (Debug)” and “Signing (Release)” sections. This will simplify setup and merge the two into a single “Signing” section.
5. Choose the “Team” value to match your Apple Developer account.
6. Set the “Bundle Identifier” to something unique; this value will be used in the next step of the tutorial when you create the Identifier through the Apple Developer site.

After following these six steps, your settings should closely resemble the screenshot above from Xcode. Once everything is set up properly and with your phone still connected to your computer, run the project (Product > Run or Command-R). This screen will show up on your phone:

Step 3: Create an Apple Bundle Identifier

This step requires you to an Apple Developer Program Role with adequate permissions. The role-permissions are listed here.

Navigate to the Identifiers tab on the Certificates, Identifiers & Profiles page of the Apple Developer site. You’ll need to add a new identifier that matches the Bundle Identifier value you set in Xcode in step 6 above. Click the plus symbol next to the title at the top of the page; if you don’t see this symbol, you likely don’t have adequate permissions. Follow these instructions for the subsequent pages:

1. Register a new identifier page: Keep the default selection (App IDs) and click “Continue”.
2. Select a type page: Keep the default selection (App) and click “Continue”.
3. Register an App ID page:
   • Description: enter an appropriate description for this project, e.g. “PushAuth Project”. This value will be displayed as the “Name” on the Identifiers page.
   • Bundle ID: Keep the selection on “Explicit” and enter the exact same value you put as the Bundle Identifier in the Xcode Signing & Capabilities page earlier.
   • Enable Push Notification capability by scrolling down on the page and selecting the checkbox next to “Push Notifications”.
   • Click “Continue”, verify everything was entered correctly, and click “Register”.

Now that you have created an identifier for this project, you can create a push notification certificate associated with this identifier.

Step 4: Create a Push Notification Certificate

UnifyID requires the APNs certificate in *.p12 format to send PushAuth requests to the app. This can be done from the same Identifiers page of the Apple Developer site that you were on in Step 3.

1. Click on the name of the identifier you just created, e.g. “PushAuth Project”.
2. Scroll down to the “Push Notifications” row and click on the “Configure” box. Next to this box you should see “Certificates (0)” since you haven’t yet created a certificate associated with this identifier.

3. In the Apple Push Notification service SSL Certificates pop-up window, click on the “Create Certificate” box under “Production SSL Certificate” then click “Done”.

4. At this point, you need to create a Certificate Signing Request (CSR) file from your Mac. Click “Learn More” and follow those instructions for doing so. Then upload that file and continue.

5. Now that you have created a certificate, you must download it locally to export it to *.p12. Click “Download”.

6. This will prompt you to add the certificate to Keychain Access. Choose a Keychain, e.g. “login”, to add the certificate to and click “Add”.

7. Then find that certificate in Keychain Access. It may be useful to select the “Certificates” category and utilize the search bar to find the certificate you just added.

8. Once you have located your certificate, right-click on it and click the option to export the certificate:

9. Specify a name for the *.p12 file and a location to save it. Make sure the file format is set to “Personal Information Exchange (.p12)” then click “Save”.

10. You will be prompted to password-protect the exported *.p12 file. Choose to export it without a password; simply click “OK”.

Now you have successfully created a APNs certificate in *.p12 format! This will be used by UnifyID and needs to be uploaded to your project settings through the dashboard.

Step 5: Providing Push Credentials to UnifyID

Now you have an Apple Bundle Identifier and an APNs push certificate. It’s time to provide your push credentials to UnifyID so that PushAuth can send push notifications to the sample app on your phone. Check out the Developer Portal docs here, or follow along the instructions below.

1. Navigate to the “Push Credentials” section of your project on the Developer Dashboard.
2. Click on “Choose File” and select the *.p12 file you generated in Step 4 of this tutorial.
3. Choose the “Development/Sandbox APNs server” option for now since we are sending push notifications to an app that runs directly from Xcode. Later on, choose “Production APNs server” when you need to send PushAuth requests to apps distributed through the App Store or through ad-hoc means.
4. Click “Add” to complete the upload.

Once the push credentials are successfully uploaded to your project settings, you will see the push credential information displayed:

If you find yourself needing to change the push credentials used for the project, simply click “Edit” and go through the same upload steps with the new credentials.

Step 6: Mobile App Settings

You now have all the values necessary for configuration! Open the sample app on your phone and tap the gear icon in the top right of the Configuration screen. For SDK key, enter your UnifyID project’s SDK key value from the Dashboard. The User string should be the same value that you used when creating a user in the web server tutorial, e.g. “Morgan”. If these values do not match, you will not be able to successfully respond to push notifications in the login flow.

• 

• 

Once you set those two values, you must allow push notifications for the app, then the app is ready to receive your PushAuth login requests!

• 

• 

Now you can go through the full login flow by entering your username and password on the login page, respond to the push notification received by this app on your phone, and be successfully logged in to the website.

That’s it! You now have a simple login flow that integrates PushAuth. The next post provides a tutorial for building the Android sample PushAuth mobile app. Stay tuned for the rests of the posts in the series and, as always, please share this post and reach out to us with questions, comments or suggestions.