Instructions for creating a push authenticator app for your mobile phone to handle registration and authentication using AM push notification.
In this article, you will learn how to create a push authenticator for your mobile phone. The push authenticator is an app that handles registration and authentication using AM push notification. Included is a sample iOS project to get started. You will:
- Set up a push service with ForgeRock Authenticator
- Implement registration and authentication flows
- Configure the app to receive incoming push notifications
- Add common cryptography
- Include support for JWT and JSON objects
- Add support for the registration flow
- Get permission to use the camera
- Compile and enjoy the app
Set up a push service with ForgeRock Authenticator
Download the free ForgeRock Authenticator app from a leading app store. Follow the instructions in Steffo Weber's article to set up a sending service, application signing keys, and other configurations: https://developer.forgerock.com/node/351.
Implement registration and authentication flows
Registration exchanges various data, including a shared secret, REST endpoints, and a challenge encoded in QR format. The client app scans the QR code, extracts the data, and POSTs to the REST endpoint with a challenge response that is encrypted using a mutual secret. The authentication flow is similar; it is essentially an encrypted response to a challenge, and the user’s accept or reject decision.
In the sample app, all interaction for both flows is in the FRPushUtils class. It handles the data encodings, the challenge responses, and interaction with the push service. You just need a simple user UI and some AV code to capture a QR code. Thankfully, Apple and iOS makes that fairly trivial.
If you’re starting with the sample app, change the bundle ID to match the ID associated with the push service, as Apple uses it to route messages to apps. If you aren't starting with the sample app, we'll assume you prepared the app, including code signing and any properties needed for the app to receive push notifications. Be sure to also include a copy of the FRPushUtils from the sample project.
Configure the app to receive incoming push notifications
In your AppDelegate.swift file, add the following before the main AppDelegate class:
When the app first launches, it will retrieve and store the device’s unique SNS push notification device ID. This is needed in the registration step.
Add or update the didFinishLaunchWithOptions function as follows:
Add common cryptography
Access to iOS standard cryptography functions is needed, as registration and authentication flows involve encryption of a challenge using a shared secret. Since these functions aren’t available by default in Swift, we need to set up a bridging header to use the objective C methods.
Create/add a new header file (.h) to your project with the following code:
// // BridgingHeader.h // ForgeBank // #ifndef BridgingHeader_h #define BridgingHeader_h #import <CommonCrypto/CommonHMAC.h> #endif /* BridgingHeader_h */
Include support for JWT and JSON objects
Add the following CocoaPods to your project Podfile (use pod init to create a new Podfile if needed) to make handling JWT and JSON objects easier:
Run pod install to install them. Because you're using CocoaPods, you’ll need to open your XCode project by selecting the .xcworkspace file rather than the .xcodeproj file from now on.
Add support for the registration flow
Assuming your app has a suitable ViewController available, add support to use the device’s camera, and a delegate function to handle QR recognition:
Add the delegate function, which will be called by the AV system to handle a found QR code. It halts the video preview and calls the FRPushUtils.registerWithQRCode function with arguments containing the found QR code, the device’s SNS device ID, and some success/failure handlers to feed back the result to the user. Alert the user with the result:
Get permission to use the camera
Permission from the user is needed to access the device’s camera. Browse the project’s Info.plist resource and add a new key for Privacy — Camera Usage Description. Set it to something descriptive like “To take profile photo and scan QR codes”:
Compile and enjoy your mobile phone app
Compile and run the app. You should have the basics of an app to handle registration and authentication flows using AM push notification. Besides making your app look pretty, you might want to consider the following enhancements:
- In its current form, the app can only handle registration to a single AM deployment for a single user ID. That’s probably fine for the most use cases. You might want to extend it to become a generic authenticator (similar to the ForgeRock Authenticator) for multiple different accounts on different AM services.
- Because the app doesn’t use any local security for the flows, you might want to add FaceID, TouchID, or a PIN, before letting the user approve or deny an authentication request.
- The app doesn’t record a log of pending requests, or previously handled requests. Generally, authentication notifications have a short timeout period (defined by AM) so there’s little benefit in letting them queue up on the client. You could handle this if the use case warranted it. It might be useful to store a log of previous requests, so the user can see missed, approved, or rejected authentications.
In the next article, you'll learn how to use an adapted version of the default AM push authentication node to send geolocation data.