how tos

Using Your Own SNS Messaging With ForgeRock Authenticator

Introduction

In this article, we’ll show you how to create your own SNS messaging service and connect it to Apple Push Notification Service (APNS) and Google Cloud Messaging (GCM). You will: 

  • Set up AWS SNS
  • Create a keypair
  • Create a project for GCM services
  • Create an SNS messaging service
  • Debug the new SNS messaging service

Push messages are a (relatively) easy way to communicate with users via a mobile phone. While similar to SMS messages, they are considered more secure, and are recommended by NIST over classical SMS.

ForgeRock Access Manager (OpenAM) provides push authentication as a secure authentication mechanism to use the fingerprint recognition feature (Touch ID) on mobile phones (iOS and Android). ForgeRock also provides an mobile app which can:

  • Register a smartphone for use with push authentication
  • Receive push messages and authenticate the user using Touch ID

This app is available on both Apple App store and Google Play. ForgeRock provides a push notification service via Amazon SNS. ForgeRock customers can easily subscribe to this service, which sends push messages from both cloud-based and on-premise AM installations.

Customizing SNS messaging services

The technology of push messages requires that the messaging service know exactly which mobile app the message should be sent to. In iOS, a mobile app is identified by a bundle identifier (bundle ID). It cannot be changed after the developer signs the app and submits it to an app store. As a result, the configuration of the message service must be changed whenever the app is modified and vice versa. This prevents people who do not own or publish the app (such as, the developing company) from sending push messages to a certain app. As an example, think about a potentially hostile entity sending messages to your WhatsApp or LinkedIn app.

Thus,

If you want to modify the app, you have to use your own AWS SNS service.

and

If you want to use your own AWS SNS service, you have to modify/recompile app with new bundle ID.

Set up AWS SNS

To setup AWS SNS for ForgeRock Push Authentication, you need:

  • A valid AWS account
  • An Apple Developer account
  • A Google Firebase account

Create a keypair

First, you need to create a public/private keypair that will be uploaded as a .p12 file to AWS. AWS uses this keypair to authenticate against APNS. To generate the keypair, you can use the Keychain app on Mac OS X.

Start at developer.apple.com and log in with your iOS developer account. Select Certificates, IDs, & Profiles.

Step 1a:Create an XCode project, enable push notifications, and choose a new bundle ID. Alternatively, you can check out ForgeRock Authenticator and amend the bundle ID:

Change/create Bundle ID in XCode

The bundle ID should appear in Apple developer console under iOS App IDs.

Step 1b: Create the keypair that AWS will use to access APNS. Add a dev or prod certificate for push notifications, then add certificate for APNS:

Create an app-specific certificate (request) for use by SNS messaging.

Select the app to receive the push notifications. Since an app is identified by the App ID (which matches the bundle ID), we need to select io.push.demo:

Selecting the AppID to use

The Apple wizard will guide you through the steps to use Keychain to generate a certificate signing request (CSR), submit it to Apple CA via a developer console, then download it and import into Keychain.

In the Apple developer certificates section, the new certificate appears with type Apple Push Services:

From Keychain, you can create a PKCS12 version which has public and private part in one file. This file will be uploaded to your AWS SNS messaging service later:

This completes the preparation for iOS. 

Create a project for GCM services

Since Google moved the creation of a GCM service to Firebase console, you need a Google cloud account to access console.firebase.google.com.

Create a new project:

Create a project for GCM service and open Project settings:

Retrieve the API key for GCM. SNS messaging needs this to send messages via GCM from Settings.

The page that follows includes the project ID and an API key. You’ll need the API key in the next step to access GCM from the AWS SNS service.

Create an SNS messaging service

Step 2a: Subscribe to SNS. Using the  AWS console (aws.amazon.com/console), go to AWS service and select Simple Notification Service (SNS):

Enable SNS for your AWS account

Step 2b: Select Create platform application. You’ll now need to provide the data to access APNS and GCM services. For APNS, select Apple development:

Tell SNS how to reach APNS

Step 2c: Select Choose P12 file. Provide a password to protect this file (remember that this file contains both your private and public keys) and select Load credentials from file. The field containing certificates and the private key should now be auto-populated.

Step 2d: Configure access to GCM accordingly. GCM uses an API key rather than a P12, but this is basically the same approach:

Tell SNS messaging service how to reach GCM

On success, your AWS SNS application appears under Applications with their endpoint.

These endpoints look like arn:aws:sns:eu-west-1:0123456787:app/APNS_SANDBOX/FRDemo and need to be entered on OpenAM’s Push Service configuration.

These endpoints are protected with a client ID/client secret pair to prevent someone from accessing the endpoints in AWS for APNS or GCM. To generate such a pair you need to create a user via AWS console using the IAM service. Make sure you tick the box for programmatic access.

Step 2e Select the Attach existing policies directly area:

Select the AmazonSNSFullAccess policy.

Step 2f:You’re almost done. In the IAM console, select the user and retrieve the Access Key ID and Secret Access Key. You can download those values as a CSV file:

That’s it. We can now configure AM’s push service to use those values and give it a try.

Debugging the new SNS messaging service

If something goes wrong when you register the new app with the new SNS messaging service, verify the app is able to receive push messages, which are not OpenAM-related issues. To do this, test push messages using Amazon’s AWS SDK.

Step 3a. Download ForgeRock Authenticator’s source code. Replace the bundle ID as described earlier. Attach your iOS device to your Mac and run the app while the mobile phone is connected to XCode. Right after you allow it to receive push notifications, you’ll see something like the following in Xcode console's output:

2017–07–20 08:46:29.111970+0200 ForgeRock[7354:2548462] Registered for remote notifications. deviceToken=<8e0729bb 565fbddc bde0bd42 e06ecf2 4464f063 7932a580 73add12c ee6e3af7> '

The deviceToken is a sort of phone number that SNS must know in order to send a message to this specific device. This is exactly what happens during the the QR registration step. After a successful registration, OpenAM’s profile of a push user now includes the pushDevice Profiles attribute, which contains the deviceToken (among other data).

Step 3b. Try to send a push message to your device using the AWS console or a NodeJS program like https://gist.github.com/tmarshall/6149ed2475f964cda3f5. To use NodeJS code, simply set the following parameters to match with your environment:

  • SNS Endpoints of the application
  • ID/Secret to access AWS
  • deviceToken
  • region (eg eu-west-1) where you created your service

Alternatively, you can use AWS console:

service

Go to SNS and select your application. Select the correct ARN (for example, iOS for Apple devices). Now select Create Endpoint (this will add a device specific endpoint):

Create a device specific endpoint using the device token

Enter deviceToken without spaces (you can leave User Data text area empty) and publish a message (we used Long live Rock'n'Roll). You should now receive this message on your phone:

Congratulations! You have successfully created your own SNS messaging service, and connected it to APNS and GCM.