This article has been archived and is no longer maintained by ForgeRock.
Push Messages are a (relatively) easy way to communicate with a mobile phone. While similar to SMS messages, they are considered to be more secure and NIST (National Institute of Standards and Technology), for example, recommends favoring push messages over traditional SMS messages.
AM/OpenAM provides push authentication as a secure authentication mechanism, which can utilize the TouchID of modern phones (iOS® and Android™). ForgeRock also provides a mobile app, which can:
- Register a smartphone for use with push authentication.
- Receive Push messages and authenticate the user using the TouchID fingerprint mechanism.
This app (ForgeRock Authenticator) is available on both the Apple® App Store and Google Play Store. ForgeRock provides a push notification service via AWS SNS. ForgeRock customers can easily subscribe to this service, which sends out push messages from both cloud-based and on-premise based AM/OpenAM installations. See How do I set up AM/OpenAM Push Notification Service credentials? for further details.
The need for customization
The push messages technology needs the messaging service to know exactly which mobile app the message should be sent to. For iOS, the mobile app is identified by a so-called bundle identifier. This bundle ID cannot be changed once the developer has signed the app and submitted it to the App Store. As a result, the configuration of the message service must be changed whenever the app is modified and vice versa. This requirement prevents people who do not own or develop the app from sending push messages to other apps (for example, this prevents a potentially hostile entity sending messages to apps such as LinkedIn or WhatsApp).
- If you want to modify the app, you have to use your own AWS SNS service.
- If you want to use your own AWS SNS service, you have to modify/recompile the app with a new bundle ID.
See How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)? for further information on branding the iOS app.
How to create your own SNS service
The following sections explain how to create your own SNS service and how to connect to the Apple Push Notification Service (APNS) as well as Google Cloud Messaging (GCM):
If you experience issues registering the new app with the new SNS service, see the Debugging section for further help.
To set up AWS SNS you need:
- A valid AWS account
- An Apple Developer account
- A Google Firebase account
Creating 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. You can, for example, use the Keychain app on Mac OS X to generate the keypair as demonstrated here:
- Navigate to the Apple Developer page (developer.apple.com) and log in with your iOS developer account; select Certificates, IDs & Profiles.
- Create an XCode project, enable Push Notifications and choose a new bundle ID. Alternatively, you can check out the ForgeRock Authenticator app (iOS or Android) and amend the bundle ID.
The bundle ID should now show up in Apple developer console “iOS App IDs”.
- Create the keypair that AWS uses to access APNS. Add a development or production certificate for Push Notifications. Then add a certificate for APNS:
- Select which application should receive the push notifications. Since an app is identified by the App ID (which matches the Bundle ID) we need to select the Bundle ID we entered in step 2 (io.push.demo in this example):
- The Apple wizard will now guide you through the steps using the Keychain app to generate a CSR (Certificate Signing Request), submit it to Apple CA via the developer console, download it and then import it into the Keychain. The new certificate will appear with type “Apple Push Services” in the Apple developer certificates section:
- Create a PKCS12 version from the Keychain app, which has the public and private parts in one file. This file will be uploaded to your AWS SNS later:
This completes the preparation for iOS.
Creating a GCM service
You can create a GCM service as follows:
- Navigate to the Firebase console (console.firebase.google.com) and log in with your Google cloud account.
- Create a new project:
- Open settings:
The project ID and an API key are on the page that follows. You’ll need the API key in the next step to access GCM from the AWS SNS service.
Creating a SNS service
- Navigate to the AWS console (aws.amazon.com/console) and then go to AWS service and select Simple Notification Service (SNS):
- Select Create platform application. You’ll now have to provide the data to access APNS and GCM services. For APNS, do:
- Select “Choose P12 file”, provide the password that protects the file (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.
- 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 will show up under applications together with their endpoint. These endpoints look like the following and need to be entered in the AM/OpenAM 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 the AWS console using the IAM service. Make sure you tick the box for programmatic access.
- Click on “Attach existing policies directly” area and select the “AmazonSNSFullAccess” policy:
- Select the user and retrieve the Access Key ID and Secret Access Key from the IAM console. You can download these values as a CSV file:
That’s it. You can now configure the AM/OpenAM’s push service to use these values and test it. See the following links for further information:
- About Push Authentication
- Configuring Multi-Factor Authentication Service Settings
- Authentication and Single Sign-On Guide › ForgeRock Authenticator (OATH) Service
- Authentication and Single Sign-On Guide › ForgeRock Authenticator (Push) Service
- Authentication and Single Sign-On Guide › Push Notification Service
You should also try updating the AWS SDK jar files to the latest version to ensure there are no jar incompatibilities. You should obtain the latest aws-java-sdk-core-<version>.jar, aws-java-sdk-sns-<version>.jar and aws-java-sdk-sqs-<version>.jar files, copy them to the /path/to/tomcat/webapps/openam/WEB-INF/lib directory and delete the old jar files.
To do this, you can test push messages using Amazon’s AWS SDK:
- Download the ForgeRock authenticator’s source code: iOS or Android.
- 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. Once you have allowed Push
Notifications to be received, you’ll see something similar to the following in the
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, the AM/OpenAM’s profile for the push user will have a pushDeviceProfiles attribute that contains the deviceToken (among other data).
- Try to send push message to your device using the AWS console or a NodeJS program (for example, tmarshall - aws-sns-example.js).
- Navigate to the AWS console (aws.amazon.com/console) and then go to SNS service:
- Select your application. Click on the correct ARN (for example, iOS for Apple devices). Now click on Create Endpoint (this will add a device specific endpoint).
- Enter the deviceToken without spaces (you can leave the User Data field empty) and publish a message to this endpoint (for example, “Long live Rock’n’Roll”). You should now receive this message on your phone.
To use NodeJS code, simply set the following parameters to match your environment:
- SNS Endpoints of the application
- ID/Secret to access AWS
- region (for example, us-east-1) where you created your service
Related Issue Tracker IDs