Using your own SNS messaging with ForgeRock Authenticator
Push Messages are an (relatively) easy way to communicate with a mobile phone. While similar to SMS messages, they are considered to be more secure and NIST eg recommends to favour messages over classical SMS.
ForgeRock Access Manager provides Push Authentication as a secure authentication mechanism which can leverage the TouchID of modern phones (iOS & Android). ForgeRock further provides an mobile app which can
- register a smartphone for use w push authentication
- receiving push messages and authenticating the user using the TouchID fingerprint mechanism
This app is available on both Apple AppStore and Google Playstore. ForgeRock provides a push notification service via Amazon SNS. ForgeRock customers can easily subscribe to this service which send out push messages from both cloud-based and on-premise based ForgeRock Access Manager installations.
THE NEED FOR CUSTOMIZATION
The technology of push messages requires that the messaging service knows exactly which mobile app the message should be send to. In case of iOS, a mobile app is identified by a so-called bundle identifier. This bundle ID cannot be changed after the developer signed the app and submitted 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 is to prevent that persons who do not own or publish the app (i.e. the devleoping company) are able to send push messages to a certain app (suppose a potentially hostile entity could send messages to your WhatApp/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.
In the following we’ll explain how to create your own SNS service and how to connect to Apple Push Notification Service (APNS) as well as Google Cloud Messaging (GCM). In a second article, we’ll explain what happens on the mobile app side and how to perform the app registration process (which is only touched briefly here).
SETTING UP 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
In a first step, you need to create a pub/priv keypair that will be uploaded as .p12 file to AWS. AWS uses this keypair to authenticate against APNS. To generate the keypair, you can eg use the Keychain app on Mac OS X. Start at developer.apple.com and login 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 checkout ForgeRock Authenticator and amend the bundle ID.

The bundle ID should now show up in Apple developer console under “iOS App IDs”.
Step 1b. We now create the keypair that AWS uses to access APNS. Add a dev or prod certificate for Push Notifications.
Now add a certificate for APNS.

Now, we have to select which application should receive the push notifications. Since an app is identified by the App ID (which matches the Bundle ID) we need eg to select “io.push.demo” in the screen that follows:

The Apple wizzard will now guide you through the steps using Keychain tool to generate a CSR (Certificate Signing Request), submit it to Apple CA via developer console and the 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 later.

This completes the preparation for iOS. Sure if you’re an experienced iOS developer there are a couple of shortcuts which we didn’t mention here.
Create a Google Cloud Messaging Service
Recently Google moved the creation of a GCM service to Firebase console. You need a Google cloud account to access console.firebase.google.com.
Next, create a new project

and open settings

In the page that follows is 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 SNS service
Step 2a. Subscribe to SNS. Using AWS console (aws.amazon.com/console) goto AWS service and select Simple Notification Service (SNS)

Step 2b. Select Create platform application. You’ll now have to provide the data to access APNS and GCM services. For APNS, do

Step 2c. Select “Choose P12 file”, provide password by which this file is protected (remember that this file contains both, your private and public key) and click “Load credentials from file”. The field containing certificates and 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.

If all goes well, your AWS SNS application shows up under applications together with their endpoint.
These endpoints look like arn:aws:sns:eu-west-1:0123456787:app/APNS_SANDBOX/FRDemo and need to be entered on Access Manager’s Push Service configuration.
To prevent people accessing the endpoints in AWS for APNS or GCM, these endpoint are protected with a clientID/clientSecret pair. 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. Click on “Attach existing policies directly” area

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

That’s it. We can now configure OpenAM’s push service to use those values and give it a try.
DEBUGGING
If something goes wrong with registering the new app with the new SNS service, you can try if the app is able to receive push messages which are not issues by OpenAM. To do this, you can test push messages using Amazon’s AWS SDK
Step 3a. Download ForgeRock authenticator’s source code. Simply 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 allowed to receive Push Notification, you’ll see something like
2017–07–20 08:46:29.111970+0200 ForgeRock[7354:2548462] Registered for remote notifications. deviceToken=<8e0729bb 565fbddc bde0bd42 e06ecf2 4464f063 7932a580 73add12c ee6e3af7>’
in XCode console’s output. The deviceToken is a sort of phone number, that SNS must know in order to send a message to this sepcific device. This is exactly what happens during the the QR registration step. After a successful registration, OpenAM’s profile of a push user has an attribute pushDeviceProfiles which contains the deviceToken (among other data).
Step 3b. Try to send push message to your device using 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. Goto SNS

service
and select your application. Click on the correct ARN (eg iOS for Apple devices). Now click on Create Endpoint (this will add a device specific endpoint).

Enter deviceToken without spaces (you can leave User Data field empty) and publish a message this endpoint (eg “Long live Rock’n’Roll”). You should now receive this message on your phone.

